POD index entries with X<>
authorIvan Tubert-Brohman <itub@cpan.org>
Wed, 12 Oct 2005 19:20:18 +0000 (15:20 -0400)
committerRafael Garcia-Suarez <rgarciasuarez@gmail.com>
Thu, 13 Oct 2005 11:20:23 +0000 (11:20 +0000)
Message-ID: <434D9A32.4050305@cpan.org>

p4raw-id: //depot/perl@25748

18 files changed:
pod/perldata.pod
pod/perldebug.pod
pod/perldsc.pod
pod/perlfaq5.pod
pod/perlfaq6.pod
pod/perlform.pod
pod/perlfunc.pod
pod/perllexwarn.pod
pod/perlmod.pod
pod/perlobj.pod
pod/perlop.pod
pod/perlpod.pod
pod/perlre.pod
pod/perlref.pod
pod/perlrun.pod
pod/perlsub.pod
pod/perlsyn.pod
pod/perltie.pod

index d828d4a..82ad855 100644 (file)
@@ -5,6 +5,7 @@ perldata - Perl data types
 =head1 DESCRIPTION
 
 =head2 Variable names
+X<variable, name> X<variable name> X<data type> X<type>
 
 Perl has three built-in data types: scalars, arrays of scalars, and
 associative arrays of scalars, known as "hashes".  A scalar is a 
@@ -27,6 +28,7 @@ to locate the namespace in which to look up the final identifier
 for a simple identifier, an expression that produces a reference
 to the value at runtime.   This is described in more detail below
 and in L<perlref>.
+X<identifier>
 
 Perl also has its own built-in variables whose names don't follow
 these rules.  They have strange names so they don't accidentally
@@ -36,11 +38,13 @@ containing only digits after the C<$> (see L<perlop> and L<perlre>).
 In addition, several special variables that provide windows into
 the inner working of Perl have names containing punctuation characters
 and control characters.  These are documented in L<perlvar>.
+X<variable, built-in>
 
 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.
+X<scalar>
 
     $days              # the simple scalar value "days"
     $days[28]          # the 29th element of array @days
@@ -50,12 +54,14 @@ single value is expected.
 Entire arrays (and slices of arrays and hashes) are denoted by '@',
 which works much like the word "these" or "those" does in English,
 in that it indicates multiple values are expected.
+X<array>
 
     @days              # ($days[0], $days[1],... $days[n])
     @days[3,4,5]       # same as ($days[3],$days[4],$days[5])
     @days{'a','c'}     # same as ($days{'a'},$days{'c'})
 
 Entire hashes are denoted by '%':
+X<hash>
 
     %days              # (key1, val1, key2, val2 ...)
 
@@ -72,6 +78,7 @@ subroutine name, a format name, or a label.  This means that $foo
 and @foo are two different variables.  It also means that C<$foo[1]>
 is a part of @foo, not a part of $foo.  This may seem a bit weird,
 but that's okay, because it is weird.
+X<namespace>
 
 Because variable references always start with '$', '@', or '%', the
 "reserved" words aren't in fact reserved with respect to variable
@@ -83,6 +90,8 @@ uppercase filehandles also improves readability and protects you
 from conflict with future reserved words.  Case I<is> significant--"FOO",
 "Foo", and "foo" are all different names.  Names that start with a
 letter or underscore may also contain digits and underscores.
+X<identifier, case sensitivity>
+X<case>
 
 It is possible to replace such an alphanumeric name with an expression
 that returns a reference to the appropriate type.  For a description
@@ -96,6 +105,7 @@ significance to Perl.  For instance, C<$$> is the current process
 id.)
 
 =head2 Context
+X<context> X<scalar context> X<list context>
 
 The interpretation of operations and values in Perl sometimes depends
 on the requirements of the context around the operation or value.
@@ -148,6 +158,7 @@ for how you would dynamically discern your function's calling
 context.
 
 =head2 Scalar values
+X<scalar> X<number> X<string> X<reference>
 
 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
@@ -172,6 +183,7 @@ A scalar value is interpreted as TRUE in the Boolean sense if it is not
 the null string or the number 0 (or its string equivalent, "0").  The
 Boolean context is just a special kind of scalar context where no 
 conversion to a string or a number is ever performed.
+X<boolean> X<bool> X<true> X<false> X<truth>
 
 There are actually two varieties of null strings (sometimes referred
 to as "empty" strings), a defined one and an undefined one.  The
@@ -186,6 +198,7 @@ rare cases of autovivification as explained in L<perlref>.  You can
 use the defined() operator to determine whether a scalar value is
 defined (this has no meaning on arrays or hashes), and the undef()
 operator to produce an undefined value.
+X<defined> X<undefined> X<undef> X<null> X<string, null>
 
 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
@@ -220,6 +233,7 @@ Shortening an array this way destroys intervening values.  Lengthening
 an array that was previously shortened does not recover values
 that were in those elements.  (It used to do so in Perl 4, but we
 had to break this to make sure destructors were called when expected.)
+X<$#> X<array, length>
 
 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
@@ -235,6 +249,7 @@ 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:
+X<array, length>
 
     scalar(@whatever) == $#whatever - $[ + 1;
 
@@ -242,6 +257,7 @@ Version 5 of Perl changed the semantics of C<$[>: files that don't set
 the value of C<$[> no longer need to worry about whether another
 file changed its value.  (In other words, use of C<$[> is deprecated.)
 So in general you can assume that
+X<$[>
 
     scalar(@whatever) == $#whatever + 1;
 
@@ -262,6 +278,7 @@ of sixteen buckets has been touched, and presumably contains all
 10,000 of your items.  This isn't supposed to happen.  If a tied hash
 is evaluated in scalar context, a fatal error will result, since this
 bucket usage information is currently not available for tied hashes.
+X<hash, scalar context> X<hash, bucket> X<bucket>
 
 You can preallocate space for a hash by assigning to the keys() function.
 This rounds up the allocated buckets to the next power of two:
@@ -269,6 +286,7 @@ This rounds up the allocated buckets to the next power of two:
     keys(%users) = 1000;               # allocate 1024 buckets
 
 =head2 Scalar value constructors
+X<scalar, literal> X<scalar, constant>
 
 Numeric literals are specified in any of the following floating point or
 integer formats:
@@ -287,6 +305,7 @@ You are allowed to use underscores (underbars) in numeric literals
 between digits for legibility.  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.
+X<number, literal>
 
 String literals are usually delimited by either single or double
 quotes.  They work much like quotes in the standard Unix shells:
@@ -295,6 +314,7 @@ substitution; single-quoted strings are not (except for C<\'> and
 C<\\>).  The usual C-style backslash rules apply for making
 characters such as newline, tab, etc., as well as some more exotic
 forms.  See L<perlop/"Quote and Quote-like Operators"> for a list.
+X<string, literal>
 
 Hexadecimal, octal, or binary, representations in string literals
 (e.g. '0xff') are not automatically converted to their integer
@@ -310,6 +330,7 @@ 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 $Z<>100."
+X<interpolation>
 
     $Price = '$100';   # not interpolated
     print "The price is $Price.\n";    # interpolated
@@ -322,6 +343,7 @@ 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:
+X<interpolation>
 
     $who = "Larry";
     print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n";
@@ -341,6 +363,7 @@ expression.  This means for example that C<$version{2.0}++> is
 equivalent to C<$version{2}++>, not to C<$version{'2.0'}++>.
 
 =head3 Version Strings
+X<version string> X<vstring> X<v-string>
 
 B<Note:> Version Strings (v-strings) have been deprecated.  They will
 be removed in some future release after Perl 5.8.1.  The marginal
@@ -375,6 +398,8 @@ Multi-number v-strings like C<v65.66> and C<65.66.67> continue to
 be v-strings always.
 
 =head3 Special Literals
+X<special literal> X<__END__> X<__DATA__> X<END> X<DATA>
+X<end> X<data> X<^D> X<^Z>
 
 The special literals __FILE__, __LINE__, and __PACKAGE__
 represent the current filename, line number, and package name at that
@@ -382,6 +407,7 @@ point in your program.  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 C<package;> directive), __PACKAGE__ is the undefined
 value.
+X<__FILE__> X<__LINE__> X<__PACKAGE__> X<line> X<file> X<package>
 
 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
@@ -404,6 +430,7 @@ as it is seen (during compilation), at which point the corresponding
 __DATA__ (or __END__) token has not yet been seen.
 
 =head3 Barewords
+X<bareword>
 
 A word that has no other interpretation in the grammar will
 be treated as if it were a quoted string.  These are known as
@@ -422,6 +449,7 @@ end of the enclosing block.  An inner block may countermand this
 by saying C<no strict 'subs'>.
 
 =head3 Array Joining Delimiter
+X<array, interpolation> X<interpolation, array> X<$">
 
 Arrays and slices are interpolated into double-quoted strings
 by joining the elements with the delimiter specified in the C<$">
@@ -448,6 +476,7 @@ which used to be here, that's been moved to
 L<perlop/Quote and Quote-like Operators>.
 
 =head2 List value constructors
+X<list>
 
 List values are denoted by separating individual values by commas
 (and enclosing the list in parentheses where precedence requires it):
@@ -660,6 +689,7 @@ are used. For example:
     print "Darwin's First Name is ", $scientists{"Darwin"}, "\n";
 
 =head2 Slices
+X<slice> X<array, slice> X<hash, slice>
 
 A common way to access an array or a hash is one scalar element at a
 time.  You can also subscript a list to get a single element from it.
@@ -736,6 +766,7 @@ hash indicates whether you are getting back a singular value (a
 scalar) or a plural one (a list).
 
 =head2 Typeglobs and Filehandles
+X<typeglob> X<filehandle> X<*>
 
 Perl uses an internal type called a I<typeglob> to hold an entire
 symbol table entry.  The type prefix of a typeglob is a C<*>, because
index 91b72ff..2e21941 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<debug> X<debugger>
 
 perldebug - Perl debugging
 
@@ -19,6 +20,7 @@ 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:
+X<-d>
 
     $ perl -d -e 42
 
@@ -59,6 +61,7 @@ The debugger understands the following commands:
 =over 12
 
 =item h
+X<debugger command, h>
 
 Prints out a summary help message
 
@@ -80,6 +83,7 @@ You may change the pager which is used via C<o pager=...> command.
 
 
 =item p expr
+X<debugger command, p>
 
 Same as C<print {$DB::OUT} expr> in the current package.  In particular,
 because this is just Perl's own C<print> function, this means that nested
@@ -89,6 +93,7 @@ The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
 where STDOUT may be redirected to.
 
 =item x [maxdepth] expr
+X<debugger command, x>
 
 Evaluates its expression in list context and dumps out the result in a
 pretty-printed fashion.  Nested data structures are printed out
@@ -104,6 +109,7 @@ dumped only I<N> levels deep, as if the C<dumpDepth> option had been
 temporarily set to I<N>.
 
 =item V [pkg [vars]]
+X<debugger command, V>
 
 Display all (or some) variables in package (defaulting to C<main>)
 using a data pretty-printer (hashes show their keys and values so
@@ -118,10 +124,12 @@ Use C<~pattern> and C<!pattern> for positive and negative regexes.
 This is similar to calling the C<x> command on each applicable var.
 
 =item X [vars]
+X<debugger command, X>
 
 Same as C<V currentpackage [vars]>.
 
 =item y [level [vars]]
+X<debugger command, y>
 
 Display all (or some) lexical variables (mnemonic: C<mY> variables)
 in the current scope or I<level> scopes higher.  You can limit the
@@ -132,16 +140,19 @@ is pretty-printed in the same style as for C<V> and the format is
 controlled by the same options.
 
 =item T
+X<debugger command, T> X<backtrace> X<stack, backtrace>
 
 Produce a stack backtrace.  See below for details on its output.
 
 =item s [expr]
+X<debugger command, s> X<step>
 
 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.
 
 =item n [expr]
+X<debugger command, n>
 
 Next.  Executes over subroutine calls, until the beginning
 of the next statement.  If an expression is supplied that includes
@@ -149,6 +160,7 @@ function calls, those functions will be executed with stops before
 each statement.
 
 =item r
+X<debugger command, r>
 
 Continue until the return from the current subroutine.
 Dump the return value if the C<PrintRet> option is set (default).
@@ -158,11 +170,13 @@ Dump the return value if the C<PrintRet> option is set (default).
 Repeat last C<n> or C<s> command.
 
 =item c [line|sub]
+X<debugger command, c>
 
 Continue, optionally inserting a one-time-only breakpoint
 at the specified line or subroutine.
 
 =item l
+X<debugger command, l>
 
 List next window of lines.
 
@@ -184,19 +198,23 @@ List first window of lines from subroutine.  I<subname> may
 be a variable that contains a code reference.
 
 =item -
+X<debugger command, ->
 
 List previous window of lines.
 
 =item v [line]
+X<debugger command, v>
 
 View a few lines of code around the current line.
 
 =item .
+X<debugger command, .>
 
 Return the internal debugger pointer to the line last
 executed, and print out that line.
 
 =item f filename
+X<debugger command, f>
 
 Switch to viewing a different file or C<eval> statement.  If I<filename>
 is not a full pathname found in the values of %INC, it is considered
@@ -219,27 +237,35 @@ Search backwards for pattern; final ? is optional.
 The search is case-insensitive by default.
 
 =item L [abw]
+X<debugger command, L>
 
 List (default all) actions, breakpoints and watch expressions
 
 =item S [[!]regex]
+X<debugger command, S>
 
 List subroutine names [not] matching the regex.
 
 =item t
+X<debugger command, t>
 
 Toggle trace mode (see also the C<AutoTrace> option).
 
 =item t expr
+X<debugger command, t>
 
 Trace through execution of C<expr>.
 See L<perldebguts/"Frame Listing Output Examples"> for examples.
 
 =item b
+X<breakpoint>
+X<debugger command, b>
 
 Sets breakpoint on current line
 
 =item b [line] [condition]
+X<breakpoint>
+X<debugger command, b>
 
 Set a breakpoint before the given line.  If a condition
 is specified, it's evaluated each time the statement is reached: a
@@ -252,34 +278,47 @@ don't use C<if>:
     b 33 /pattern/i
 
 =item b subname [condition]
+X<breakpoint>
+X<debugger command, b>
 
 Set a breakpoint before the first line of the named subroutine.  I<subname> may
 be a variable containing a code reference (in this case I<condition>
 is not supported).
 
 =item b postpone subname [condition]
+X<breakpoint>
+X<debugger command, b>
 
 Set a breakpoint at first line of subroutine after it is compiled.
 
 =item b load filename
+X<breakpoint>
+X<debugger command, b>
 
 Set a breakpoint before the first executed line of the I<filename>,
 which should be a full pathname found amongst the %INC values.
 
 =item b compile subname
+X<breakpoint>
+X<debugger command, b>
 
 Sets a breakpoint before the first statement executed after the specified
 subroutine is compiled.
 
 =item B line
+X<breakpoint>
+X<debugger command, B>
 
 Delete a breakpoint from the specified I<line>.
 
 =item B *
+X<breakpoint>
+X<debugger command, B>
 
 Delete all installed breakpoints.
 
 =item a [line] command
+X<debugger command, a>
 
 Set an action to be done before the line is executed.  If I<line> is
 omitted, set an action on the line about to be executed.
@@ -297,39 +336,48 @@ For example, this will print out $foo every time line
     a 53 print "DB FOUND $foo\n"
 
 =item A line
+X<debugger command, A>
 
 Delete an action from the specified line.
 
 =item A *
+X<debugger command, A>
 
 Delete all installed actions.
 
 =item w expr
+X<debugger command, w>
 
 Add a global watch-expression.  We hope you know what one of these
 is, because they're supposed to be obvious.
 
 =item W expr
+X<debugger command, W>
 
 Delete watch-expression
 
 =item W *
+X<debugger command, W>
 
 Delete all watch-expressions.
 
 =item o
+X<debugger command, o>
 
 Display all options
 
 =item o booloption ...
+X<debugger command, o>
 
 Set each listed Boolean option to the value C<1>.
 
 =item o anyoption? ...
+X<debugger command, o>
 
 Print out the value of one or more options.
 
 =item o option=value ...
+X<debugger command, o>
 
 Set the value of one or more options.  If the value has internal
 whitespace, it should be quoted.  For example, you could set C<o
@@ -350,28 +398,34 @@ not be.  Several options can be set together.  See L<"Configurable Options">
 for a list of these.
 
 =item < ?
+X<< debugger command, < >>
 
 List out all pre-prompt Perl command actions.
 
 =item < [ command ]
+X<< debugger command, < >>
 
 Set an action (Perl command) to happen before every debugger prompt.
 A multi-line command may be entered by backslashing the newlines.
 
 =item < *
+X<< debugger command, < >>
 
 Delete all pre-prompt Perl command actions.
 
 =item << command
+X<< debugger command, << >>
 
 Add an action (Perl command) to happen before every debugger prompt.
 A multi-line command may be entered by backwhacking the newlines.
 
 =item > ?
+X<< debugger command, > >>
 
 List out post-prompt Perl command actions.
 
 =item > command
+X<< debugger 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
@@ -379,16 +433,19 @@ command may be entered by backslashing the newlines (we bet you
 couldn't've guessed this by now).
 
 =item > *
+X<< debugger command, > >>
 
 Delete all post-prompt Perl command actions.
 
 =item >> command
+X<<< debugger 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.
 
 =item { ?
+X<debugger command, {>
 
 List out pre-prompt debugger commands.
 
@@ -403,28 +460,34 @@ what you mean to do, write it as with C<;{ ... }> or even
 C<do { ... }>.
 
 =item { *
+X<debugger command, {>
 
 Delete all pre-prompt debugger commands.
 
 =item {{ command
+X<debugger 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.
 
 =item ! number
+X<debugger command, !>
 
 Redo a previous command (defaults to the previous command).
 
 =item ! -number
+X<debugger command, !>
 
 Redo number'th previous command.
 
 =item ! pattern
+X<debugger command, !>
 
 Redo last command that started with pattern.
 See C<o recallCommand>, too.
 
 =item !! cmd
+X<debugger command, !!>
 
 Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
 C<o shellBang>, also.  Note that the user's current shell (well,
@@ -433,16 +496,20 @@ with proper interpretation of exit status or signal and coredump
 information.
 
 =item source file
+X<debugger command, source>
 
 Read and execute debugger commands from I<file>.
 I<file> may itself contain C<source> commands.
 
 =item H -number
+X<debugger command, H>
 
 Display last n commands.  Only commands longer than one character are
 listed.  If I<number> is omitted, list them all.
 
 =item q or ^D
+X<debugger command, q>
+X<debugger command, ^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
@@ -453,6 +520,7 @@ off the end the script.  You may also need to set $finished to 0
 if you want to step through global destruction.
 
 =item R
+X<debugger command, R>
 
 Restart the debugger by C<exec()>ing a new session.  We try to maintain
 your history across this, but internal settings and command-line options
@@ -463,14 +531,17 @@ actions, debugger options, and the Perl command-line
 options B<-w>, B<-I>, and B<-e>.
 
 =item |dbcmd
+X<debugger command, |>
 
 Run the debugger command, piping DB::OUT into your current pager.
 
 =item ||dbcmd
+X<debugger command, ||>
 
 Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
 
 =item = [alias value]
+X<debugger command, =>
 
 Define a command alias, like
 
@@ -485,17 +556,20 @@ supplied.  If the Perl statement would otherwise be confused for a
 Perl debugger, use a leading semicolon, too.
 
 =item m expr
+X<debugger command, m>
 
 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.
 
 =item M
+X<debugger command, M>
 
 Displays all loaded modules and their versions
 
 
 =item man [manpage]
+X<debugger command, man>
 
 Despite its name, this calls your system's default documentation
 viewer on the given page, or on the viewer itself if I<manpage> is
@@ -528,11 +602,14 @@ either interactively or from the environment or an rc file.
 =over 12
 
 =item C<recallCommand>, C<ShellBang>
+X<debugger option, recallCommand>
+X<debugger option, ShellBang>
 
 The characters used to recall command or spawn shell.  By
 default, both are set to C<!>, which is unfortunate.
 
 =item C<pager>
+X<debugger option, pager>
 
 Program to use for output of pager-piped commands (those beginning
 with a C<|> character.)  By default, C<$ENV{PAGER}> will be used.
@@ -542,10 +619,13 @@ sequences through unchanged, the output of some debugger commands
 will not be readable when sent through the pager.
 
 =item C<tkRunning>
+X<debugger option, tkRunning>
 
 Run Tk while prompting (with ReadLine).
 
 =item C<signalLevel>, C<warnLevel>, C<dieLevel>
+X<debugger option, signalLevel> X<debugger option, warnLevel>
+X<debugger option, dieLevel>
 
 Level of verbosity.  By default, the debugger leaves your exceptions
 and warnings alone, because altering them can break correctly running
@@ -566,11 +646,13 @@ This may perhaps be useful for some tracing purposes, but tends to hopelessly
 destroy any program that takes its exception handling seriously.
 
 =item C<AutoTrace>
+X<debugger option, AutoTrace>
 
 Trace mode (similar to C<t> command, but can be put into
 C<PERLDB_OPTS>).
 
 =item C<LineInfo>
+X<debugger option, LineInfo>
 
 File or pipe to print line number info to.  If it is a pipe (say,
 C<|visual_perl_db>), then a short message is used.  This is the
@@ -579,14 +661,17 @@ such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
 debugger.
 
 =item C<inhibit_exit>
+X<debugger option, inhibit_exit>
 
 If 0, allows I<stepping off> the end of the script.
 
 =item C<PrintRet>
+X<debugger option, PrintRet>
 
 Print return value after C<r> command if set (default).
 
 =item C<ornaments>
+X<debugger option, ornaments>
 
 Affects screen appearance of the command line (see L<Term::ReadLine>).
 There is currently no way to disable these, which can render
@@ -594,6 +679,7 @@ some output illegible on some displays, or with some pagers.
 This is considered a bug.
 
 =item C<frame>
+X<debugger option, frame>
 
 Affects the printing of messages upon entry and exit from subroutines.  If
 C<frame & 2> is false, messages are printed on entry only. (Printing
@@ -608,11 +694,13 @@ The length at which the argument list is truncated is governed by the
 next option:
 
 =item C<maxTraceLen>
+X<debugger option, maxTraceLen>
 
 Length to truncate the argument list when the C<frame> option's
 bit 4 is set.
 
 =item C<windowSize>
+X<debugger option, windowSize>
 
 Change the size of code list window (default is 10 lines).
 
@@ -624,36 +712,45 @@ commands:
 =over 12
 
 =item C<arrayDepth>, C<hashDepth>
+X<debugger option, arrayDepth> X<debugger option, hashDepth>
 
 Print only first N elements ('' for all).
 
 =item C<dumpDepth>
+X<debugger option, dumpDepth>
 
 Limit recursion depth to N levels when dumping structures.
 Negative values are interpreted as infinity.  Default: infinity.
 
 =item C<compactDump>, C<veryCompact>
+X<debugger option, compactDump> X<debugger option, veryCompact>
 
 Change the style of array and hash output.  If C<compactDump>, short array
 may be printed on one line.
 
 =item C<globPrint>
+X<debugger option, globPrint>
 
 Whether to print contents of globs.
 
 =item C<DumpDBFiles>
+X<debugger option, DumpDBFiles>
 
 Dump arrays holding debugged files.
 
 =item C<DumpPackages>
+X<debugger option, DumpPackages>
 
 Dump symbol tables of packages.
 
 =item C<DumpReused>
+X<debugger option, DumpReused>
 
 Dump contents of "reused" addresses.
 
 =item C<quote>, C<HighBit>, C<undefPrint>
+X<debugger option, quote> X<debugger option, HighBit>
+X<debugger option, undefPrint>
 
 Change the style of string dump.  The default value for C<quote>
 is C<auto>; one can enable double-quotish or single-quotish format
@@ -661,6 +758,7 @@ by setting it to C<"> or C<'>, respectively.  By default, characters
 with their high bit set are printed verbatim.
 
 =item C<UsageOnly>
+X<debugger option, UsageOnly>
 
 Rudimentary per-package memory usage dump.  Calculates total
 size of strings found in variables in the package.  This does not
@@ -685,10 +783,12 @@ better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)
 =over 12
 
 =item C<TTY>
+X<debugger option, TTY>
 
 The TTY to use for debugging I/O.
 
 =item C<noTTY>
+X<debugger option, noTTY>
 
 If set, the debugger goes into C<NonStop> mode and will not connect to a TTY.  If
 interrupted (or if control goes to the debugger via explicit setting of
@@ -705,11 +805,13 @@ inspected for proper ownership, so security hazards are theoretically
 possible.
 
 =item C<ReadLine>
+X<debugger option, ReadLine>
 
 If false, readline support in the debugger is disabled in order
 to debug applications that themselves use ReadLine.
 
 =item C<NonStop>
+X<debugger option, NonStop>
 
 If set, the debugger goes into non-interactive mode until interrupted, or
 programmatically by setting $DB::signal or $DB::single.
@@ -792,6 +894,7 @@ Note that this business of escaping a newline is specific to interactive
 commands typed into the debugger.
 
 =item Stack backtrace
+X<backtrace> X<stack, backtrace>
 
 Here's an example of what a stack backtrace via C<T> command might
 look like:
@@ -968,6 +1071,7 @@ fall somewhat short of the mark, especially if you don't program
 your Perl as a C programmer might.
 
 =head2 The Perl Profiler
+X<profile> X<profiling> X<profiler>
 
 If you wish to supply an alternative debugger for Perl to run, just
 invoke your script with a colon and a package argument given to the
@@ -984,6 +1088,8 @@ also supplied with the standard Perl distribution, can be used to
 interpret the information in that profile.
 
 =head1 Debugging regular expressions
+X<regular expression, debugging>
+X<regex, debugging> X<regexp, debugging>
 
 C<use re 'debug'> enables you to see the gory details of how the Perl
 regular expression engine works. In order to understand this typically
@@ -994,6 +1100,7 @@ are explored in some detail in
 L<perldebguts/"Debugging regular expressions">.
 
 =head1 Debugging memory usage
+X<memory usage>
 
 Perl contains internal support for reporting its own memory usage,
 but this is a fairly advanced concept that requires some understanding
index 11304a6..158322b 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<data structure> X<complex data structure> X<struct>
 
 perldsc - Perl Data Structures Cookbook
 
@@ -68,6 +69,7 @@ But for now, let's look at general issues common to all
 these types of data structures.
 
 =head1 REFERENCES
+X<reference> X<dereference> X<dereferencing> X<pointer>
 
 The most important thing to understand about all data structures in Perl
 -- including multidimensional arrays--is that even though they might
@@ -75,6 +77,7 @@ appear otherwise, Perl C<@ARRAY>s and C<%HASH>es 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 I<references> to other arrays or hashes.
+X<multidimensional array> X<array, multidimensional>
 
 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
@@ -174,6 +177,7 @@ in memory!  In C, you'd have to remember to malloc() yourself some new
 memory.  In Perl, you'll want to use the array constructor C<[]> or the
 hash constructor C<{}> instead.   Here's the right way to do the preceding
 broken code fragments:
+X<[]> X<{}>
 
     for $i (1..10) {
        @array = somefunc($i);
@@ -248,9 +252,11 @@ In summary:
 
 
 =head1 CAVEAT ON PRECEDENCE
+X<dereference, precedence> X<dereferencing, precedence>
 
 Speaking of things like C<@{$AoA[$i]}>, the following are actually the
 same thing:
+X<< -> >>
 
     $aref->[2][2]      # clear
     $$aref[2][2]       # confusing
@@ -298,6 +304,10 @@ variable, and it would thereby remind you to write instead:
     print $aref->[2][2]
 
 =head1 DEBUGGING
+X<data structure, debugging> X<complex data structure, debugging>
+X<AoA, debugging> X<HoA, debugging> X<AoH, debugging> X<HoH, debugging>
+X<array of arrays, debugging> X<hash of arrays, debugging>
+X<array of hashes, debugging> X<hash of hashes, debugging>
 
 Before version 5.002, the standard Perl debugger didn't do a very nice job of
 printing out complex data structures.  With 5.002 or above, the
@@ -331,6 +341,7 @@ here are short code examples illustrating access of various
 types of data structures.
 
 =head1 ARRAYS OF ARRAYS
+X<array of arrays> X<AoA>
 
 =head2 Declaration of an ARRAY OF ARRAYS
 
@@ -387,6 +398,7 @@ types of data structures.
  }
 
 =head1 HASHES OF ARRAYS
+X<hash of arrays> X<HoA>
 
 =head2 Declaration of a HASH OF ARRAYS
 
@@ -465,6 +477,7 @@ types of data structures.
  }
 
 =head1 ARRAYS OF HASHES
+X<array of hashes> X<AoH>
 
 =head2 Declaration of an ARRAY OF HASHES
 
@@ -555,6 +568,7 @@ types of data structures.
  }
 
 =head1 HASHES OF HASHES
+X<hass of hashes> X<HoH>
 
 =head2 Declaration of a HASH OF HASHES
 
@@ -673,6 +687,7 @@ types of data structures.
 
 
 =head1 MORE ELABORATE RECORDS
+X<record> X<structure> X<struct>
 
 =head2 Declaration of MORE ELABORATE RECORDS
 
index 85f1c54..bab49a2 100644 (file)
@@ -8,6 +8,7 @@ This section deals with I/O and the "f" issues: filehandles, flushing,
 formats, and footers.
 
 =head2 How do I flush/unbuffer an output filehandle?  Why must I do this?
+X<flush> X<buffer> X<unbuffer> X<autoflush>
 
 Perl does not support truly unbuffered output (except
 insofar as you can C<syswrite(OUT, $char, 1)>), although it
@@ -61,11 +62,13 @@ or IO::Socket:
     $sock->autoflush();
 
 =head2 How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
+X<file, editing>
 
 Use the Tie::File module, which is included in the standard
 distribution since Perl 5.8.0.
 
 =head2 How do I count the number of lines in a file?
+X<file, counting lines> X<lines> X<line>
 
 One fairly efficient way is to count newlines in the file. The
 following program uses a feature of tr///, as documented in L<perlop>.
@@ -82,6 +85,7 @@ proper text file, so this may report one fewer line than you expect.
 This assumes no funny games with newline translations.
 
 =head2 How can I use Perl's C<-i> option from within a program?
+X<-i> X<in-place>
 
 C<-i> sets the value of Perl's C<$^I> variable, which in turn affects
 the behavior of C<< <> >>; see L<perlrun> for more details.  By
@@ -107,6 +111,7 @@ leaving a backup of the original data from each file in a new
 C<.c.orig> file.
 
 =head2 How can I copy a file?
+X<copy> X<file, copy>
 
 (contributed by brian d foy)
 
@@ -123,6 +128,7 @@ open the original file, open the destination file, then print
 to the destination file as you read the original.
 
 =head2 How do I make a temporary file name?
+X<file, temporary>
 
 If you don't need to know the name of the file, you can use C<open()>
 with C<undef> in place of the file name.  The C<open()> function
@@ -175,6 +181,7 @@ temporary files in one process, use a counter:
     }
 
 =head2 How can I manipulate fixed-record-length files?
+X<fixed-length> X<file, fixed-length records>
 
 The most efficient way is using L<pack()|perlfunc/"pack"> and
 L<unpack()|perlfunc/"unpack">.  This is faster than using
@@ -206,6 +213,7 @@ group or loop over them with for. It also avoids polluting the program
 with global variables and using symbolic references.
 
 =head2 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?
+X<filehandle, local> X<filehandle, passing> X<filehandle, reference>
 
 As of perl5.6, open() autovivifies file and directory handles
 as references if you pass it an uninitialized scalar variable.
@@ -234,6 +242,7 @@ If you want to create many anonymous handles, you should
 check out the Symbol or IO::Handle modules.
 
 =head2 How can I use a filehandle indirectly?
+X<filehandle, indirect>
 
 An indirect filehandle is using something other than a symbol
 in a place that a filehandle is expected.  Here are ways
@@ -329,15 +338,18 @@ It's the syntax of the fundamental operators.  Playing the object
 game doesn't help you at all here.
 
 =head2 How can I set up a footer format to be used with write()?
+X<footer>
 
 There's no builtin way to do this, but L<perlform> has a couple of
 techniques to make it possible for the intrepid hacker.
 
 =head2 How can I write() into a string?
+X<write, into a string>
 
 See L<perlform/"Accessing Formatting Internals"> for an swrite() function.
 
 =head2 How can I output my numbers with commas added?
+X<number, commify>
 
 (contributed by brian d foy and Benjamin Goldberg)
 
@@ -373,6 +385,7 @@ It is easier to see with comments:
    )/$1,/xg;
 
 =head2 How can I translate tildes (~) in a filename?
+X<tilde> X<tilde expansion>
 
 Use the <> (glob()) operator, documented in L<perlfunc>.  Older
 versions of Perl require that you have a shell installed that groks
@@ -395,6 +408,7 @@ Within Perl, you may use this directly:
        }ex;
 
 =head2 How come when I open a file read-write it wipes it out?
+X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating>
 
 Because you're using something like this, which truncates the file and
 I<then> gives you read-write access:
@@ -468,6 +482,7 @@ isn't as exclusive as you might wish.
 See also the new L<perlopentut> if you have it (new for 5.6).
 
 =head2 Why do I sometimes get an "Argument list too long" when I use E<lt>*E<gt>?
+X<argument list too long>
 
 The C<< <> >> operator performs a globbing operation (see above).
 In Perl versions earlier than v5.6.0, the internal glob() operator forks
@@ -481,6 +496,7 @@ yourself with readdir() and patterns, or use a module like File::KGlob,
 one that doesn't use the shell to do globbing.
 
 =head2 Is there a leak/bug in glob()?
+X<glob>
 
 Due to the current implementation on some operating systems, when you
 use the glob() function or its angle-bracket alias in a scalar
@@ -488,6 +504,7 @@ context, you may cause a memory leak and/or unpredictable behavior.  It's
 best therefore to use glob() only in list context.
 
 =head2 How can I open a file with a leading ">" or trailing blanks?
+X<filename, special characters>
 
 (contributed by Brian McCauley)
 
@@ -504,6 +521,7 @@ charcters in the filename as special.
        open FILE, ">", ">file";     # filename is ">file"
 
 =head2 How can I reliably rename a file?
+X<rename> X<mv> X<move> X<file, rename> X<ren>
 
 If your operating system supports a proper mv(1) utility or its
 functional equivalent, this works:
@@ -519,6 +537,7 @@ permissions, timestamps, inode info, etc.
 Newer versions of File::Copy export a move() function.
 
 =head2 How can I lock a file?
+X<lock> X<file, lock> X<flock>
 
 Perl's builtin flock() function (see L<perlfunc> for details) will call
 flock(2) if that exists, fcntl(2) if it doesn't (on perl version 5.004 and
@@ -566,6 +585,7 @@ L<perlopentut/"File Locking"> if you have it (new for 5.6).
 =back
 
 =head2 Why can't I just open(FH, "E<gt>file.lock")?
+X<lock, lockfile race condition>
 
 A common bit of code B<NOT TO USE> is this:
 
@@ -585,6 +605,7 @@ Various schemes involving link() have been suggested, but
 these tend to involve busy-wait, which is also subdesirable.
 
 =head2 I still don't get locking.  I just want to increment the number in the file.  How can I do this?
+X<counter> X<file, counter>
 
 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
@@ -609,6 +630,7 @@ Here's a much better web-page hit counter:
 If the count doesn't impress your friends, then the code might.  :-)
 
 =head2 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?
+X<append> X<file, append>
 
 If you are on a system that correctly implements flock() and you use the
 example appending code from "perldoc -f flock" everything will be OK
@@ -637,6 +659,7 @@ level write()s even if the buffer was empty to start.  There may be some
 systems where this probability is reduced to zero.
 
 =head2 How do I randomly update a binary file?
+X<file, binary patch>
 
 If you're just trying to patch a binary, in many cases something as
 simple as this works:
@@ -660,6 +683,7 @@ Locking and error checking are left as an exercise for the reader.
 Don't forget them or you'll be quite sorry.
 
 =head2 How do I get a file's timestamp in perl?
+X<timestamp> X<file, timestamp>
 
 If you want to retrieve the time at which the file was last
 read, written, or had its meta-data (owner, etc) changed,
@@ -693,6 +717,7 @@ in theory, independent of the current locale.  See L<perllocale>
 for details.
 
 =head2 How do I set a file's timestamp in perl?
+X<timestamp> X<file, timestamp>
 
 You use the utime() function documented in L<perlfunc/utime>.
 By way of example, here's a little program that copies the
@@ -718,6 +743,7 @@ a finer granularity than two seconds.  This is a limitation of
 the filesystems, not of utime().
 
 =head2 How do I print to more than one file at once?
+X<print, to multiple files>
 
 To connect one filehandle to several output filehandles,
 you can use the IO::Tee or Tie::FileHandle::Multiplex modules.
@@ -728,6 +754,7 @@ to each filehandle.
     for $fh (FH1, FH2, FH3) { print $fh "whatever\n" }
 
 =head2 How can I read in an entire file all at once?
+X<slurp> X<file, slurping>
 
 You can use the File::Slurp module to do it in one step.
 
@@ -781,6 +808,7 @@ The third argument tests the byte size of the data on the INPUT filehandle
 and reads that many bytes into the buffer $var.
 
 =head2 How can I read in a file by paragraphs?
+X<file, reading by paragraphs>
 
 Use the C<$/> variable (see L<perlvar> for details).  You can either
 set it to C<""> to eliminate empty paragraphs (C<"abc\n\n\n\ndef">,
@@ -791,6 +819,7 @@ Note that a blank line must have no blanks in it.  Thus
 S<C<"fred\n \nstuff\n\n">> is one paragraph, but C<"fred\n\nstuff\n\n"> is two.
 
 =head2 How can I read a single character from a file?  From the keyboard?
+X<getc> X<file, reading one character at a time>
 
 You can use the builtin C<getc()> function for most filehandles, but
 it won't (easily) work on a terminal device.  For STDIN, either use
@@ -922,6 +951,7 @@ FIONREAD requires a filehandle connected to a stream, meaning that sockets,
 pipes, and tty devices work, but I<not> files.
 
 =head2 How do I do a C<tail -f> in perl?
+X<tail>
 
 First try
 
@@ -950,6 +980,7 @@ more.  Lather, rinse, repeat.
 There's also a File::Tail module from CPAN.
 
 =head2 How do I dup() a filehandle in Perl?
+X<dup>
 
 If you check L<perlfunc/open>, you'll see that several of the ways
 to call open() should do the trick.  For example:
@@ -970,6 +1001,7 @@ a copied one.
 Error checking, as always, has been left as an exercise for the reader.
 
 =head2 How do I close a file descriptor by number?
+X<file, closing file descriptors>
 
 This should rarely be necessary, as the Perl close() function is to be
 used for things that Perl opened itself, even if it was a dup of a
@@ -989,6 +1021,7 @@ Or, just use the fdopen(3S) feature of open():
     }
 
 =head2 Why can't I use "C:\temp\foo" in DOS paths?  Why doesn't `C:\temp\foo.exe` work?
+X<filename, DOS issues>
 
 Whoops!  You just put a tab and a formfeed into that filename!
 Remember that within double quoted strings ("like\this"), the
@@ -1005,6 +1038,7 @@ awk, Tcl, Java, or Python, just to mention a few.  POSIX paths
 are more portable, too.
 
 =head2 Why doesn't glob("*.*") get all the files?
+X<glob>
 
 Because even on non-Unix ports, Perl's glob function follows standard
 Unix globbing semantics.  You'll need C<glob("*")> to get all (non-hidden)
@@ -1027,6 +1061,7 @@ 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.
 
 =head2 How do I select a random line from a file?
+X<file, selecting a random line>
 
 Here's an algorithm from the Camel Book:
 
index ed0bc29..b778a58 100644 (file)
@@ -13,6 +13,8 @@ on the web" and L<perlfaq4>: "How do I determine whether a scalar is
 a number/whole/integer/float", to be precise).
 
 =head2 How can I hope to use regular expressions without creating illegible and unmaintainable code?
+X<regex, legibility> X<regexp, legibility>
+X<regular expression, legibility> X</x>
 
 Three techniques can make regular expressions maintainable and
 understandable.
@@ -69,6 +71,7 @@ delimiter within the pattern:
 =back
 
 =head2 I'm having trouble matching over more than one line.  What's wrong?
+X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
 
 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
@@ -121,6 +124,7 @@ Here's code that finds everything between START and END in a paragraph:
     }
 
 =head2 How can I pull out lines between two patterns that are themselves on different lines?
+X<..>
 
 You can use Perl's somewhat exotic C<..> operator (documented in
 L<perlop>):
@@ -146,6 +150,8 @@ Here's another example of using C<..>:
     }
 
 =head2 I put a regular expression into $/ but it didn't work. What's wrong?
+X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
+X<$RS, regexes in>
 
 Up to Perl 5.8.0, $/ has to be a string.  This may change in 5.10,
 but don't get your hopes up. Until then, you can use these examples
@@ -189,6 +195,8 @@ complete line (using your regular expression).
 
 
 =head2 How do I substitute case insensitively on the LHS while preserving case on the RHS?
+X<replace, case preserving> X<substitute, case preserving>
+X<substitution, case preserving> X<s, case preserving>
 
 Here's a lovely Perlish solution by Larry Rosler.  It exploits
 properties of bitwise xor on ASCII strings.
@@ -278,6 +286,7 @@ the case of the last character is used for the rest of the substitution.
     }
 
 =head2 How can I make C<\w> match national character sets?
+X<\w>
 
 Put C<use locale;> in your script.  The \w character class is taken
 from the current locale.
@@ -285,6 +294,7 @@ from the current locale.
 See L<perllocale> for details.
 
 =head2 How can I match a locale-smart version of C</[a-zA-Z]/>?
+X<alpha>
 
 You can use the POSIX character class syntax C</[[:alpha:]]/>
 documented in L<perlre>.
@@ -296,6 +306,7 @@ the non-alphabetics, is then everything in \W along with
 the digits and the underscore, or C</[\W\d_]/>.
 
 =head2 How can I quote a variable to use in a regex?
+X<regex, escaping> X<regexp, escaping> X<regular expression, escaping>
 
 The Perl parser will expand $variable and @variable references in
 regular expressions unless the delimiter is a single quote.  Remember,
@@ -326,6 +337,7 @@ The use of C<\Q> causes the <.> in the regex to be treated as a
 regular character, so that C<P.> matches a C<P> followed by a dot.
 
 =head2 What is C</o> really for?
+X</o>
 
 Using a variable in a regular expression match forces a re-evaluation
 (and perhaps recompilation) each time the regular expression is
@@ -414,6 +426,8 @@ A slight modification also removes C++ comments:
     s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//[^\n]*|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;
 
 =head2 Can I use Perl regular expressions to match balanced text?
+X<regex, matching balanced test> X<regexp, matching balanced test>
+X<regular expression, matching balanced test>
 
 Historically, Perl regular expressions were not capable of matching
 balanced text.  As of more recent versions of perl including 5.6.1
@@ -442,6 +456,7 @@ The C::Scan module from CPAN also contains such subs for internal use,
 but they are undocumented.
 
 =head2 What does it mean that regexes are greedy?  How can I get around it?
+X<greedy> X<greediness>
 
 Most people mean that greedy regexes match as much as they can.
 Technically speaking, it's actually the quantifiers (C<?>, C<*>, C<+>,
@@ -462,6 +477,7 @@ control on to whatever is next in line, like you would if you were
 playing hot potato.
 
 =head2 How do I process each word on each line?
+X<word>
 
 Use the split function:
 
@@ -513,10 +529,13 @@ If you want these output in a sorted order, see L<perlfaq4>: "How do I
 sort a hash (optionally by value instead of key)?".
 
 =head2 How can I do approximate matching?
+X<match, approximate> X<matching, approximate>
 
 See the module String::Approx available from CPAN.
 
 =head2 How do I efficiently match many regular expressions at once?
+X<regex, efficiency> X<regexp, efficiency>
+X<regular expression, efficiency>
 
 ( contributed by brian d foy )
 
@@ -572,6 +591,7 @@ inefficient.  Once you understand how perl applies regular
 expressions, you can tune them for individual situations.
 
 =head2 Why don't word-boundary searches with C<\b> work for me?
+X<\b>
 
 (contributed by brian d foy)
 
@@ -629,6 +649,7 @@ These strings do not match /\Bam\B/
 
 
 =head2 Why does using $&, $`, or $' slow my program down?
+X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
 
 (contributed by Anno Siegel)
 
@@ -649,6 +670,7 @@ essentially the same information, but without the risk of excessive
 string copying.
 
 =head2 What good is C<\G> in a regular expression?
+X<\G>
 
 You use the C<\G> anchor to start the next match on the same
 string where the last match left off.  The regular
@@ -742,6 +764,7 @@ match starts at the same position to try a different
 pattern.
 
 =head2 Are Perl regexes DFAs or NFAs?  Are they POSIX compliant?
+X<DFA> X<NFA> X<POSIX>
 
 While it's true that Perl's regular expressions resemble the DFAs
 (deterministic finite automata) of the egrep(1) program, they are in
@@ -755,6 +778,7 @@ hope to know on these matters (a full citation appears in
 L<perlfaq2>).
 
 =head2 What's wrong with using grep in a void context?
+X<grep>
 
 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
@@ -767,6 +791,8 @@ But since 5.8.1, this has been fixed, and map is context aware - in void
 context, no lists are constructed.
 
 =head2 How can I match strings with multibyte characters?
+X<regex, and multibyte characters> X<regexp, and multibyte characters>
+X<regular expression, and 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
index 6e104bb..c72a940 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<format> X<report> X<chart>
 
 perlform - Perl formats
 
@@ -12,6 +13,7 @@ etc.  Keywords are borrowed from FORTRAN: format() to declare and write()
 to execute; see their entries in L<perlfunc>.  Fortunately, the layout is
 much more legible, more like BASIC's PRINT USING statement.  Think of it
 as a poor man's nroff(1).
+X<nroff>
 
 Formats, like packages and subroutines, are declared rather than
 executed, so they may occur at any point in your program.  (Usually it's
@@ -54,6 +56,9 @@ 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:
+X<format, picture line>
+X<@> X<^> X<< < >> X<< | >> X<< > >> X<#> X<0> X<.> X<...>
+X<@*> X<^*> X<~> X<~~>
   
    @    start of regular field
    ^    start of special field
@@ -77,6 +82,7 @@ the various possibilities in detail.
 
 
 =head2 Text Fields
+X<format, text field>
 
 The length of the field is supplied by padding out the field with multiple 
 "E<lt>", "E<gt>", or "|" characters to specify a non-numeric field with,
@@ -97,6 +103,7 @@ multi-line text block filling; see L</Using Fill Mode> for details.
 
 
 =head2 Numeric Fields
+X<#> X<format, numeric field>
 
 Using "#" as a padding character specifies a numeric field, with
 right justification. An optional "." defines the position of the
@@ -116,6 +123,7 @@ filled with "#" as overflow evidence.
 
 
 =head2 The Field @* for Variable Width Multi-Line Text
+X<@*>
 
 The field "@*" can be used for printing multi-line, nontruncated
 values; it should (but need not) appear by itself on a line. A final
@@ -123,6 +131,7 @@ line feed is chomped off, but all other characters are emitted verbatim.
 
 
 =head2 The Field ^* for Variable Width One-line-at-a-time Text
+X<^*>
 
 Like "@*", this is a variable width field. The value supplied must be a 
 scalar variable. Perl puts the first line (up to the first "\n") of the 
@@ -145,6 +154,7 @@ The variable will I<not> be restored.
 
 
 =head2 Specifying Values
+X<format, 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
@@ -163,6 +173,7 @@ L<perllocale> and L<"WARNINGS"> for more information.
 
 
 =head2 Using Fill Mode
+X<format, 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
@@ -184,6 +195,7 @@ if the text was too long to appear in its entirety.
 
 
 =head2 Suppressing Lines Where All Fields Are Void
+X<format, suppressing lines>
 
 Using caret fields can produce lines where all fields are blank. You can
 suppress such lines by putting a "~" (tilde) character anywhere in the
@@ -191,6 +203,7 @@ line.  The tilde will be translated to a space upon output.
 
 
 =head2 Repeating Format Lines
+X<format, repeating 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,
@@ -202,6 +215,7 @@ field in such lines, because it will never go blank.
 
 
 =head2 Top of Form Processing
+X<format, top of form> X<top> X<header>
 
 Top-of-form processing is by default handled by a format with the
 same name as the current filehandle with "_TOP" concatenated to it.
@@ -256,6 +270,8 @@ channel, but you'll have to handle C<$-> (C<$FORMAT_LINES_LEFT>)
 yourself.
 
 =head2 Format Variables
+X<format variables>
+X<format, variables>
 
 The current format name is stored in the variable C<$~> (C<$FORMAT_NAME>),
 and the current top of form format name is in C<$^> (C<$FORMAT_TOP_NAME>).
@@ -365,6 +381,7 @@ Here's a little program that's somewhat like fmt(1):
  }
 
 =head2 Footers
+X<format, footer> X<footer>
 
 While $FORMAT_TOP_NAME contains the name of the current header format,
 there is no corresponding mechanism to automatically do the same thing
@@ -381,6 +398,7 @@ Have your child process massage its STDIN to rearrange headers and footers
 however you like.  Not very convenient, but doable.
 
 =head2 Accessing Formatting Internals
+X<format, internals>
 
 For low-level access to the formatting mechanism.  you may use formline()
 and access C<$^A> (the $ACCUMULATOR variable) directly.
index 44ce1c4..362055f 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<function>
 
 perlfunc - Perl builtin functions
 
@@ -68,6 +69,7 @@ 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.
+X<context>
 
 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
@@ -85,6 +87,7 @@ C<waitpid>, and C<syscall>.  System calls also set the special C<$!>
 variable on failure.  Other functions do not, except accidentally.
 
 =head2 Perl Functions by Category
+X<function>
 
 Here are Perl's functions (including things that look like
 functions, like some keywords and named operators)
@@ -94,33 +97,40 @@ than one place.
 =over 4
 
 =item Functions for SCALARs or strings
+X<scalar> X<string> X<character>
 
 C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
 C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>,
 C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
 
 =item Regular expressions and pattern matching
+X<regular expression> X<regex> X<regexp>
 
 C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
 
 =item Numeric functions
+X<numeric> X<number> X<trigonometric> X<trigonometry>
 
 C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
 C<sin>, C<sqrt>, C<srand>
 
 =item Functions for real @ARRAYs
+X<array>
 
 C<pop>, C<push>, C<shift>, C<splice>, C<unshift>
 
 =item Functions for list data
+X<list>
 
 C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack>
 
 =item Functions for real %HASHes
+X<hash>
 
 C<delete>, C<each>, C<exists>, C<keys>, C<values>
 
 =item Input and output functions
+X<I/O> X<input> X<output> X<dbm>
 
 C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
 C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
@@ -133,6 +143,7 @@ C<warn>, C<write>
 C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
 
 =item Functions for filehandles, files, or directories
+X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
 
 C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
 C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
@@ -140,6 +151,7 @@ C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
 C<umask>, C<unlink>, C<utime>
 
 =item Keywords related to the control flow of your Perl program
+X<control flow>
 
 C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
 C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
@@ -154,38 +166,45 @@ C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>,
 C<scalar>, C<undef>, C<wantarray>
 
 =item Functions for processes and process groups
+X<process> X<pid> X<process id>
 
 C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
 C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
 C<times>, C<wait>, C<waitpid>
 
 =item Keywords related to perl modules
+X<module>
 
 C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
 
 =item Keywords related to classes and object-orientedness
+X<object> X<class> X<package>
 
 C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
 C<untie>, C<use>
 
 =item Low-level socket functions
+X<socket> X<sock>
 
 C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
 C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
 C<socket>, C<socketpair>
 
 =item System V interprocess communication functions
+X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
 
 C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
 C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
 
 =item Fetching user and group info
+X<user> X<group> X<password> X<uid> X<gid>  X<passwd> X</etc/passwd>
 
 C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
 C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
 C<getpwuid>, C<setgrent>, C<setpwent>
 
 =item Fetching network info
+X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
 
 C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
 C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
@@ -194,10 +213,12 @@ C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>,
 C<setnetent>, C<setprotoent>, C<setservent>
 
 =item Time-related functions
+X<time> X<date>
 
 C<gmtime>, C<localtime>, C<time>, C<times>
 
 =item Functions new in perl5
+X<perl5>
 
 C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>,
 C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>,
@@ -214,6 +235,7 @@ C<dbmclose>, C<dbmopen>
 =back
 
 =head2 Portability
+X<portability> X<Unix> X<portable>
 
 Perl was born in Unix and can therefore access all common Unix
 system calls.  In non-Unix environments, the functionality of some
@@ -247,6 +269,8 @@ L<perlport> and other available platform-specific documentation.
 =over 8
 
 =item -X FILEHANDLE
+X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
+X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 
 =item -X EXPR
 
@@ -261,8 +285,6 @@ the undefined value if the file doesn't exist.  Despite the funny
 names, precedence is the same as any other named unary operator, and
 the argument may be parenthesized like any other unary operator.  The
 operator may be any of:
-X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
-X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
 
     -r File is readable by effective uid/gid.
     -w File is writable by effective uid/gid.
@@ -373,6 +395,7 @@ the return value of C<-f $file> as an argument to another filetest
 operator, no special magic will happen.)
 
 =item abs VALUE
+X<abs> X<absolute>
 
 =item abs
 
@@ -380,6 +403,7 @@ Returns the absolute value of its argument.
 If VALUE is omitted, uses C<$_>.
 
 =item accept NEWSOCKET,GENERICSOCKET
+X<accept>
 
 Accepts an incoming socket connect, just as the accept(2) system call
 does.  Returns the packed address if it succeeded, false otherwise.
@@ -390,6 +414,9 @@ be set for the newly opened file descriptor, as determined by the
 value of $^F.  See L<perlvar/$^F>.
 
 =item alarm SECONDS
+X<alarm>
+X<SIGALRM>
+X<timer>
 
 =item alarm
 
@@ -438,6 +465,7 @@ modulo the caveats given in L<perlipc/"Signals">.
 For more information see L<perlipc>.
 
 =item atan2 Y,X
+X<atan2> X<arctangent> X<tan> X<tangent>
 
 Returns the arctangent of Y/X in the range -PI to PI.
 
@@ -449,6 +477,7 @@ function, or use the familiar relation:
 Note that atan2(0, 0) is not well-defined.
 
 =item bind SOCKET,NAME
+X<bind>
 
 Binds a network address to a socket, just as the bind system call
 does.  Returns true if it succeeded, false otherwise.  NAME should be a
@@ -456,6 +485,7 @@ packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item binmode FILEHANDLE, LAYER
+X<binmode> X<binary> X<text> X<DOS> X<Windows>
 
 =item binmode FILEHANDLE
 
@@ -542,6 +572,7 @@ in L<perlvar> for how to manually set your input and output
 line-termination sequences.
 
 =item bless REF,CLASSNAME
+X<bless>
 
 =item bless REF
 
@@ -562,6 +593,7 @@ that CLASSNAME is a true value.
 See L<perlmod/"Perl Modules">.
 
 =item caller EXPR
+X<caller> X<call stack> X<stack> X<stack trace>
 
 =item caller
 
@@ -604,6 +636,8 @@ C<< N > 1 >>.  In particular, C<@DB::args> might have information from the
 previous time C<caller> was called.
 
 =item chdir EXPR
+X<chdir>
+X<cd>
 
 =item chdir FILEHANDLE
 
@@ -623,6 +657,7 @@ directory handle as argument.  On systems that don't support fchdir,
 passing handles produces a fatal error at run time.
 
 =item chmod LIST
+X<chmod> X<permission> X<mode>
 
 Changes the permissions of a list of files.  The first element of the
 list must be the numerical mode, which should probably be an octal
@@ -654,6 +689,7 @@ module:
     # This is identical to the chmod 0755 of the above example.
 
 =item chomp VARIABLE
+X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
 
 =item chomp( LIST )
 
@@ -699,6 +735,7 @@ C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
 as C<chomp($a, $b)>.
 
 =item chop VARIABLE
+X<chop>
 
 =item chop( LIST )
 
@@ -720,6 +757,7 @@ character, use C<substr($string, 0, -1)>.
 See also L</chomp>.
 
 =item chown LIST
+X<chown> X<owner> X<user> X<group>
 
 Changes the owner (and group) of a list of files.  The first two
 elements of the list must be the I<numeric> uid and gid, in that
@@ -757,6 +795,7 @@ On POSIX systems, you can detect this condition this way:
     $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
 
 =item chr NUMBER
+X<chr> X<character> X<ASCII> X<Unicode>
 
 =item chr
 
@@ -780,6 +819,7 @@ the low eight bits.
 See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item chroot FILENAME
+X<chroot> X<root>
 
 =item chroot
 
@@ -791,6 +831,7 @@ reasons, this call is restricted to the superuser.  If FILENAME is
 omitted, does a C<chroot> to C<$_>.
 
 =item close FILEHANDLE
+X<close>
 
 =item close
 
@@ -833,11 +874,13 @@ FILEHANDLE may be an expression whose value can be used as an indirect
 filehandle, usually the real filehandle name.
 
 =item closedir DIRHANDLE
+X<closedir>
 
 Closes a directory opened by C<opendir> and returns the success of that
 system call.
 
 =item connect SOCKET,NAME
+X<connect>
 
 Attempts to connect to a remote socket, just as the connect system call
 does.  Returns true if it succeeded, false otherwise.  NAME should be a
@@ -845,6 +888,7 @@ packed address of the appropriate type for the socket.  See the examples in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item continue BLOCK
+X<continue>
 
 C<continue> is actually a flow control statement rather than a function.  If
 there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
@@ -874,6 +918,7 @@ empty one, logically enough.  In that case, C<next> goes directly back
 to check the condition at the top of the loop.
 
 =item cos EXPR
+X<cos> X<cosine> X<acos> X<arccosine>
 
 =item cos
 
@@ -886,6 +931,8 @@ function, or use this relation:
     sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
 
 =item crypt PLAINTEXT,SALT
+X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
+X<decrypt> X<cryptography> X<passwd>
 
 Creates a digest string exactly like the crypt(3) function in the C
 library (assuming that you actually have a version there that has not
@@ -963,12 +1010,14 @@ the string back to an eight-bit byte string before calling crypt()
 C<Wide character in crypt>.
 
 =item dbmclose HASH
+X<dbmclose>
 
 [This function has been largely superseded by the C<untie> function.]
 
 Breaks the binding between a DBM file and a hash.
 
 =item dbmopen HASH,DBNAME,MASK
+X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
 
 [This function has been largely superseded by the C<tie> function.]
 
@@ -1011,6 +1060,7 @@ before you call dbmopen():
        or die "Can't open netscape history file: $!";
 
 =item defined EXPR
+X<defined> X<undef> X<undefined>
 
 =item defined
 
@@ -1074,6 +1124,7 @@ what you want.
 See also L</undef>, L</exists>, L</ref>.
 
 =item delete EXPR
+X<delete>
 
 Given an expression that specifies a hash element, array element, hash slice,
 or array slice, deletes the specified element(s) from the hash or array.
@@ -1138,6 +1189,7 @@ lookup:
     delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
 
 =item die LIST
+X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
 
 Outside an C<eval>, prints the value of LIST to C<STDERR> and
 exits with the current value of C<$!> (errno).  If C<$!> is C<0>,
@@ -1229,6 +1281,7 @@ this promotes strange action at a distance, this counterintuitive
 behavior may be fixed in a future release.
 
 =item do BLOCK
+X<do> X<block>
 
 Not really a function.  Returns the value of the last command in the
 sequence of commands indicated by BLOCK.  When modified by the C<while> or
@@ -1241,10 +1294,12 @@ C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
 See L<perlsyn> for alternative strategies.
 
 =item do SUBROUTINE(LIST)
+X<do>
 
 This form of subroutine call is deprecated.  See L<perlsub>.
 
 =item do EXPR
+X<do>
 
 Uses the value of EXPR as a filename and executes the contents of the
 file as a Perl script.
@@ -1288,6 +1343,7 @@ file.  Manual error checking can be done this way:
     }
 
 =item dump LABEL
+X<dump> X<core> X<undump>
 
 =item dump
 
@@ -1320,6 +1376,7 @@ You might also consider autoloading or selfloading, which at least
 make your program I<appear> to run faster.
 
 =item each HASH
+X<each> X<hash, iterator>
 
 When called in list context, returns a 2-element list consisting of the
 key and value for the next element of a hash, so that you can iterate over
@@ -1359,6 +1416,9 @@ only in a different order:
 See also C<keys>, C<values> and C<sort>.
 
 =item eof FILEHANDLE
+X<eof>
+X<end of file>
+X<end-of-file>
 
 =item eof ()
 
@@ -1409,6 +1469,7 @@ input operators typically return C<undef> when they run out of data, or if
 there was an error.
 
 =item eval EXPR
+X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
 
 =item eval BLOCK
 
@@ -1527,6 +1588,7 @@ 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.
 
 =item exec LIST
+X<exec> X<execute>
 
 =item exec PROGRAM LIST
 
@@ -1602,6 +1664,7 @@ Note that C<exec> will not call your C<END> blocks, nor will it call
 any C<DESTROY> methods in your objects.
 
 =item exists EXPR
+X<exists> X<autovivification>
 
 Given an expression that specifies a hash element or array element,
 returns true if the specified element in the hash or array has ever
@@ -1662,6 +1725,7 @@ to exists() is an error.
     exists &sub();     # Error
 
 =item exit EXPR
+X<exit> X<terminate> X<abort>
 
 =item exit
 
@@ -1689,6 +1753,7 @@ can call C<POSIX:_exit($status)> to avoid END and destructor processing.
 See L<perlmod> for details.
 
 =item exp EXPR
+X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
 
 =item exp
 
@@ -1696,6 +1761,7 @@ Returns I<e> (the natural logarithm base) to the power of EXPR.
 If EXPR is omitted, gives C<exp($_)>.
 
 =item fcntl FILEHANDLE,FUNCTION,SCALAR
+X<fcntl>
 
 Implements the fcntl(2) function.  You'll probably have to say
 
@@ -1732,6 +1798,7 @@ on your own, though.
                 or die "Can't set flags for the socket: $!\n";
 
 =item fileno FILEHANDLE
+X<fileno>
 
 Returns the file descriptor for a filehandle, or undefined if the
 filehandle is not open.  This is mainly useful for constructing
@@ -1751,6 +1818,7 @@ return undefined even though they are open.)
 
 
 =item flock FILEHANDLE,OPERATION
+X<flock> X<lock> X<locking>
 
 Calls flock(2), or an emulation of it, on FILEHANDLE.  Returns true
 for success, false on failure.  Produces a fatal error if used on a
@@ -1828,6 +1896,7 @@ function lose the locks, making it harder to write servers.
 See also L<DB_File> for other flock() examples.
 
 =item fork
+X<fork> X<child> X<parent>
 
 Does a fork(2) system call to create a new process running the
 same program at the same point.  It returns the child pid to the
@@ -1856,6 +1925,7 @@ backgrounded job launched from a remote shell) won't think you're done.
 You should reopen those to F</dev/null> if it's any issue.
 
 =item format
+X<format>
 
 Declare a picture format for use by the C<write> function.  For
 example:
@@ -1873,6 +1943,7 @@ example:
 See L<perlform> for many details and examples.
 
 =item formline PICTURE,LIST
+X<formline>
 
 This is an internal function used by C<format>s, though you may call it,
 too.  It formats (see L<perlform>) a list of values according to the
@@ -1892,6 +1963,7 @@ character may be taken to mean the beginning of an array name.
 C<formline> always returns true.  See L<perlform> for other examples.
 
 =item getc FILEHANDLE
+X<getc> X<getchar>
 
 =item getc
 
@@ -1928,6 +2000,7 @@ module from your nearest CPAN site; details on CPAN can be found on
 L<perlmodlib/CPAN>.
 
 =item getlogin
+X<getlogin> X<login>
 
 This implements the C library function of the same name, which on most
 systems returns the current login from F</etc/utmp>, if any.  If null,
@@ -1939,6 +2012,7 @@ Do not consider C<getlogin> for authentication: it is not as
 secure as C<getpwuid>.
 
 =item getpeername SOCKET
+X<getpeername> X<peer>
 
 Returns the packed sockaddr address of other end of the SOCKET connection.
 
@@ -1949,6 +2023,7 @@ Returns the packed sockaddr address of other end of the SOCKET connection.
     $herstraddr     = inet_ntoa($iaddr);
 
 =item getpgrp PID
+X<getpgrp> X<group>
 
 Returns the current process group for the specified PID.  Use
 a PID of C<0> to get the current process group for the
@@ -1958,6 +2033,7 @@ group of current process.  Note that the POSIX version of C<getpgrp>
 does not accept a PID argument, so only C<PID==0> is truly portable.
 
 =item getppid
+X<getppid> X<parent> X<pid>
 
 Returns the process id of the parent process.
 
@@ -1969,12 +2045,19 @@ to call the underlying C<getppid()>, you may use the CPAN module
 C<Linux::Pid>.
 
 =item getpriority WHICH,WHO
+X<getpriority> X<priority> X<nice>
 
 Returns the current priority for a process, a process group, or a user.
 (See L<getpriority(2)>.)  Will raise a fatal exception if used on a
 machine that doesn't implement getpriority(2).
 
 =item getpwnam NAME
+X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
+X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
+X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
+X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
+X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
+X<endnetent> X<endprotoent> X<endservent> 
 
 =item getgrnam NAME
 
@@ -2128,6 +2211,7 @@ they aren't, because a C<File::stat> object is different from
 a C<User::pwent> object.
 
 =item getsockname SOCKET
+X<getsockname>
 
 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
@@ -2141,6 +2225,7 @@ IPs that the connection might have come in on.
        inet_ntoa($myaddr);
 
 =item getsockopt SOCKET,LEVEL,OPTNAME
+X<getsockopt>
 
 Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
 Options may exist at multiple protocol levels depending on the socket
@@ -2172,6 +2257,7 @@ An example testing if Nagle's algorithm is turned on on a socket:
 
 
 =item glob EXPR
+X<glob> X<wildcard> X<filename, expansion> X<expand>
 
 =item glob
 
@@ -2187,6 +2273,7 @@ Beginning with v5.6.0, this operator is implemented using the standard
 C<File::Glob> extension.  See L<File::Glob> for details.
 
 =item gmtime EXPR
+X<gmtime> X<UTC> X<Greenwich>
 
 =item gmtime
 
@@ -2236,6 +2323,7 @@ strings, see the example in L</localtime>.
 See L<perlport/gmtime> for portability concerns.
 
 =item goto LABEL
+X<goto> X<jump> X<jmp>
 
 =item goto EXPR
 
@@ -2277,6 +2365,7 @@ containing a code reference, or a block that evaluates to a code
 reference.
 
 =item grep BLOCK LIST
+X<grep>
 
 =item grep EXPR,LIST
 
@@ -2311,6 +2400,7 @@ can't be seen from the outside, avoiding any potential side-effects.
 See also L</map> for a list composed of the results of the BLOCK or EXPR.
 
 =item hex EXPR
+X<hex> X<hexadecimal>
 
 =item hex
 
@@ -2327,6 +2417,7 @@ unlike oct(). To present something as hex, look into L</printf>,
 L</sprintf>, or L</unpack>.
 
 =item import LIST
+X<import>
 
 There is no builtin C<import> function.  It is just an ordinary
 method (subroutine) defined (or inherited) by modules that wish to export
@@ -2334,6 +2425,7 @@ names to another module.  The C<use> function calls the C<import> method
 for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
 
 =item index STR,SUBSTR,POSITION
+X<index> X<indexOf> X<InStr>
 
 =item index STR,SUBSTR
 
@@ -2348,6 +2440,7 @@ you've set the C<$[> variable to--but don't do that).  If the substring
 is not found, C<index> returns one less than the base, ordinarily C<-1>.
 
 =item int EXPR
+X<int> X<integer> X<truncate> X<trunc>
 
 =item int
 
@@ -2361,6 +2454,7 @@ the C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil>
 functions will serve you better than will int().
 
 =item ioctl FILEHANDLE,FUNCTION,SCALAR
+X<ioctl>
 
 Implements the ioctl(2) function.  You'll probably first have to say
 
@@ -2397,6 +2491,7 @@ The special string C<"0 but true"> is exempt from B<-w> complaints
 about improper numeric conversions.
 
 =item join EXPR,LIST
+X<join>
 
 Joins the separate strings of LIST into a single string with fields
 separated by the value of EXPR, and returns that new string.  Example:
@@ -2407,6 +2502,7 @@ Beware that unlike C<split>, C<join> doesn't take a pattern as its
 first argument.  Compare L</split>.
 
 =item keys HASH
+X<keys> X<key>
 
 Returns a list consisting of all the keys of the named hash.
 (In scalar context, returns the number of keys.)
@@ -2465,6 +2561,7 @@ as trying has no effect).
 See also C<each>, C<values> and C<sort>.
 
 =item kill SIGNAL, LIST
+X<kill> X<signal>
 
 Sends a signal to a list of processes.  Returns the number of
 processes successfully signaled (which is not necessarily the
@@ -2487,6 +2584,7 @@ use a signal name in quotes.
 See L<perlipc/"Signals"> for more details.
 
 =item last LABEL
+X<last> X<break>
 
 =item last
 
@@ -2512,6 +2610,7 @@ See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
 =item lc EXPR
+X<lc> X<lowercase>
 
 =item lc
 
@@ -2523,6 +2622,7 @@ and L<perlunicode> for more details about locale and Unicode support.
 If EXPR is omitted, uses C<$_>.
 
 =item lcfirst EXPR
+X<lcfirst> X<lowercase>
 
 =item lcfirst
 
@@ -2535,6 +2635,7 @@ details about locale and Unicode support.
 If EXPR is omitted, uses C<$_>.
 
 =item length EXPR
+X<length> X<size>
 
 =item length
 
@@ -2548,17 +2649,20 @@ number of characters, not the number of bytes.  To get the length
 in bytes, use C<do { use bytes; length(EXPR) }>, see L<bytes>.
 
 =item link OLDFILE,NEWFILE
+X<link>
 
 Creates a new filename linked to the old filename.  Returns true for
 success, false otherwise.
 
 =item listen SOCKET,QUEUESIZE
+X<listen>
 
 Does the same thing that the listen system call does.  Returns true if
 it succeeded, false otherwise.  See the example in
 L<perlipc/"Sockets: Client/Server Communication">.
 
 =item local EXPR
+X<local>
 
 You really probably want to be using C<my> instead, because C<local> isn't
 what most people think of as "local".  See
@@ -2570,6 +2674,7 @@ be placed in parentheses.  See L<perlsub/"Temporary Values via local()">
 for details, including issues with tied arrays and hashes.
 
 =item localtime EXPR
+X<localtime>
 
 =item localtime
 
@@ -2637,6 +2742,7 @@ and the month of the year, may not necessarily be three characters wide.
 See L<perlport/localtime> for portability concerns.
 
 =item lock THING
+X<lock>
 
 This function places an advisory lock on a shared variable, or referenced
 object contained in I<THING> until the lock goes out of scope.
@@ -2647,6 +2753,7 @@ instead. (However, if you've said C<use threads>, lock() is always a
 keyword.) See L<threads>.
 
 =item log EXPR
+X<log> X<logarithm> X<e> X<ln> X<base>
 
 =item log
 
@@ -2663,6 +2770,7 @@ divided by the natural log of N.  For example:
 See also L</exp> for the inverse operation.
 
 =item lstat EXPR
+X<lstat>
 
 =item lstat
 
@@ -2679,6 +2787,7 @@ If EXPR is omitted, stats C<$_>.
 The match operator.  See L<perlop>.
 
 =item map BLOCK LIST
+X<map>
 
 =item map EXPR,LIST
 
@@ -2738,6 +2847,7 @@ or to force an anon hash constructor use C<+{>
 and you get list of anonymous hashes each with only 1 entry.
 
 =item mkdir FILENAME,MASK
+X<mkdir> X<md> X<directory, create>
 
 =item mkdir FILENAME
 
@@ -2762,6 +2872,7 @@ this right, so Perl automatically removes all trailing slashes to keep
 everyone happy.
 
 =item msgctl ID,CMD,ARG
+X<msgctl>
 
 Calls the System V IPC function msgctl(2).  You'll probably have to say
 
@@ -2774,12 +2885,14 @@ C<"0 but true"> for zero, or the actual return value otherwise.  See also
 L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation.
 
 =item msgget KEY,FLAGS
+X<msgget>
 
 Calls the System V IPC function msgget(2).  Returns the message queue
 id, or the undefined value if there is an error.  See also
 L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation.
 
 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
+X<msgrcv>
 
 Calls the System V IPC function msgrcv to receive a message from
 message queue ID into variable VAR with a maximum message size of
@@ -2791,6 +2904,7 @@ an error.  See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and
 C<IPC::SysV::Msg> documentation.
 
 =item msgsnd ID,MSG,FLAGS
+X<msgsnd>
 
 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
@@ -2801,6 +2915,7 @@ or false if there is an error.  See also C<IPC::SysV>
 and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
+X<my>
 
 =item my TYPE EXPR
 
@@ -2820,6 +2935,7 @@ L<perlsub/"Private Variables via my()"> for details, and L<fields>,
 L<attributes>, and L<Attribute::Handlers>.
 
 =item next LABEL
+X<next> X<continue>
 
 =item next
 
@@ -2846,6 +2962,7 @@ See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
 =item no Module VERSION LIST
+X<no>
 
 =item no Module VERSION
 
@@ -2856,6 +2973,7 @@ C<redo> work.
 See the C<use> function, of which C<no> is the opposite.
 
 =item oct EXPR
+X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>
 
 =item oct
 
@@ -2880,6 +2998,7 @@ automatically convert strings into numbers as needed, this automatic
 conversion assumes base 10.)
 
 =item open FILEHANDLE,EXPR
+X<open> X<pipe> X<file, open> X<fopen>
 
 =item open FILEHANDLE,MODE,EXPR
 
@@ -3249,6 +3368,7 @@ them, and automatically close whenever and however you leave that scope:
 See L</seek> for some details about mixing reading and writing.
 
 =item opendir DIRHANDLE,EXPR
+X<opendir>
 
 Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
 C<seekdir>, C<rewinddir>, and C<closedir>.  Returns true if successful.
@@ -3259,6 +3379,7 @@ reference to a new anonymous dirhandle.
 DIRHANDLEs have their own namespace separate from FILEHANDLEs.
 
 =item ord EXPR
+X<ord> X<encoding>
 
 =item ord
 
@@ -3270,6 +3391,7 @@ For the reverse, see L</chr>.
 See L<perlunicode> and L<encoding> for more about Unicode.
 
 =item our EXPR
+X<our> X<global>
 
 =item our EXPR TYPE
 
@@ -3364,6 +3486,7 @@ also has the effect of C<our @x : unique; our %x : unique>. This may be
 subject to change.
 
 =item pack TEMPLATE,LIST
+X<pack>
 
 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
@@ -3883,6 +4006,7 @@ Examples:
 The same template may generally also be used in unpack().
 
 =item package NAMESPACE
+X<package> X<module> X<namespace>
 
 =item package
 
@@ -3912,6 +4036,7 @@ See L<perlmod/"Packages"> for more information about packages, modules,
 and classes.  See L<perlsub> for other scoping issues.
 
 =item pipe READHANDLE,WRITEHANDLE
+X<pipe>
 
 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
@@ -3927,6 +4052,7 @@ for the newly opened file descriptors as determined by the value of $^F.
 See L<perlvar/$^F>.
 
 =item pop ARRAY
+X<pop> X<stack>
 
 =item pop
 
@@ -3941,6 +4067,7 @@ omitted, pops the C<@ARGV> array in the main program, and the C<@_>
 array in subroutines, just like C<shift>.
 
 =item pos SCALAR
+X<pos> X<match, position>
 
 =item pos
 
@@ -3956,6 +4083,7 @@ the return from C<pos> won't change either in this case.  See L<perlre> and
 L<perlop>.
 
 =item print FILEHANDLE LIST
+X<print>
 
 =item print LIST
 
@@ -3990,6 +4118,7 @@ you will have to use a block returning the filehandle value instead:
     print { $OK ? STDOUT : STDERR } "stuff\n";
 
 =item printf FILEHANDLE FORMAT, LIST
+X<printf>
 
 =item printf FORMAT, LIST
 
@@ -4005,6 +4134,7 @@ C<print> would do.  The C<print> is more efficient and less
 error prone.
 
 =item prototype FUNCTION
+X<prototype>
 
 Returns the prototype of a function as a string (or C<undef> if the
 function has no prototype).  FUNCTION is a reference to, or the name of,
@@ -4018,6 +4148,7 @@ like a Perl function.  Otherwise, the string describing the equivalent
 prototype is returned.
 
 =item push ARRAY,LIST
+X<push>, X<stack>
 
 Treats ARRAY as a stack, and pushes the values of LIST
 onto the end of ARRAY.  The length of ARRAY increases by the length of
@@ -4043,6 +4174,7 @@ the completed C<push>.
 Generalized quotes.  See L<perlop/"Regexp Quote-Like Operators">.
 
 =item quotemeta EXPR
+X<quotemeta> X<metacharacter>
 
 =item quotemeta
 
@@ -4056,6 +4188,7 @@ the C<\Q> escape in double-quoted strings.
 If EXPR is omitted, uses C<$_>.
 
 =item rand EXPR
+X<rand> X<random>
 
 =item rand
 
@@ -4078,6 +4211,7 @@ large or too small, then your version of Perl was probably compiled
 with the wrong number of RANDBITS.)
 
 =item read FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<read>
 
 =item read FILEHANDLE,SCALAR,LENGTH
 
@@ -4107,6 +4241,7 @@ characters, not bytes.  Similarly for the C<:encoding> pragma:
 in that case pretty much any characters can be read.
 
 =item readdir DIRHANDLE
+X<readdir>
 
 Returns the next directory entry for a directory opened by C<opendir>.
 If used in list context, returns all the rest of the entries in the
@@ -4122,6 +4257,7 @@ C<chdir> there, it would have been testing the wrong file.
     closedir DIR;
 
 =item readline EXPR
+X<readline> X<gets> X<fgets>
 
 Reads from the filehandle whose typeglob is contained in EXPR.  In scalar
 context, each call reads and returns the next line, until end-of-file is
@@ -4157,6 +4293,7 @@ steps to ensure that C<readline> was successful.
     }
 
 =item readlink EXPR
+X<readlink>
 
 =item readlink
 
@@ -4166,6 +4303,7 @@ error, returns the undefined value and sets C<$!> (errno).  If EXPR is
 omitted, uses C<$_>.
 
 =item readpipe EXPR
+X<readpipe>
 
 EXPR is executed as a system command.
 The collected standard output of the command is returned.
@@ -4177,6 +4315,7 @@ operator, but you can use it directly.  The C<qx/EXPR/>
 operator is discussed in more detail in L<perlop/"I/O Operators">.
 
 =item recv SOCKET,SCALAR,LENGTH,FLAGS
+X<recv>
 
 Receives a message on a socket.  Attempts to receive LENGTH characters
 of data into variable SCALAR from the specified SOCKET filehandle.
@@ -4196,6 +4335,7 @@ characters, not bytes.  Similarly for the C<:encoding> pragma:
 in that case pretty much any characters can be read.
 
 =item redo LABEL
+X<redo>
 
 =item redo
 
@@ -4234,6 +4374,7 @@ See also L</continue> for an illustration of how C<last>, C<next>, and
 C<redo> work.
 
 =item ref EXPR
+X<ref> X<reference>
 
 =item ref
 
@@ -4264,6 +4405,7 @@ name is returned instead.  You can think of C<ref> as a C<typeof> operator.
 See also L<perlref>.
 
 =item rename OLDNAME,NEWNAME
+X<rename> X<move> X<mv> X<ren>
 
 Changes the name of a file; an existing file NEWNAME will be
 clobbered.  Returns true for success, false otherwise.
@@ -4276,6 +4418,7 @@ open files, or pre-existing files.  Check L<perlport> and either the
 rename(2) manpage or equivalent system documentation for details.
 
 =item require VERSION
+X<require>
 
 =item require EXPR
 
@@ -4432,6 +4575,7 @@ corresponding to the files they have loaded. See L<perlvar/%INC>.
 For a yet-more-powerful import facility, see L</use> and L<perlmod>.
 
 =item reset EXPR
+X<reset>
 
 =item reset
 
@@ -4455,6 +4599,7 @@ up on scope exit anyway, so you'll probably want to use them instead.
 See L</my>.
 
 =item return EXPR
+X<return>
 
 =item return
 
@@ -4470,6 +4615,7 @@ or do FILE will automatically return the value of the last expression
 evaluated.)
 
 =item reverse LIST
+X<reverse> X<rev> X<invert>
 
 In list context, returns a list value consisting of the elements
 of LIST in the opposite order.  In scalar context, concatenates the
@@ -4492,11 +4638,13 @@ on a large hash, such as from a DBM file.
     %by_name = reverse %by_address;    # Invert the hash
 
 =item rewinddir DIRHANDLE
+X<rewinddir>
 
 Sets the current position to the beginning of the directory for the
 C<readdir> routine on DIRHANDLE.
 
 =item rindex STR,SUBSTR,POSITION
+X<rindex>
 
 =item rindex STR,SUBSTR
 
@@ -4505,6 +4653,7 @@ occurrence of SUBSTR in STR.  If POSITION is specified, returns the
 last occurrence at or before that position.
 
 =item rmdir FILENAME
+X<rmdir> X<rd> X<directory, remove>
 
 =item rmdir
 
@@ -4517,6 +4666,7 @@ sets C<$!> (errno).  If FILENAME is omitted, uses C<$_>.
 The substitution operator.  See L<perlop>.
 
 =item scalar EXPR
+X<scalar> X<context>
 
 Forces EXPR to be interpreted in scalar context and returns the value
 of EXPR.
@@ -4546,6 +4696,7 @@ is the moral equivalent of these two:
 See L<perlop> for more details on unary operators and the comma operator.
 
 =item seek FILEHANDLE,POSITION,WHENCE
+X<seek> X<fseek> X<filehandle, position>
 
 Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
 FILEHANDLE may be an expression whose value gives the name of the
@@ -4592,6 +4743,7 @@ cantankerous), then you may need something more like this:
     }
 
 =item seekdir DIRHANDLE,POS
+X<seekdir>
 
 Sets the current position for the C<readdir> routine on DIRHANDLE.  POS
 must be a value returned by C<telldir>.  C<seekdir> also has the same caveats
@@ -4599,6 +4751,7 @@ about possible directory compaction as the corresponding system library
 routine.
 
 =item select FILEHANDLE
+X<select> X<filehandle, default>
 
 =item select
 
@@ -4627,6 +4780,7 @@ methods, preferring to write the last example as:
     STDERR->autoflush(1);
 
 =item select RBITS,WBITS,EBITS,TIMEOUT
+X<select>
 
 This calls the select(2) system call with the bit masks specified, which
 can be constructed using C<fileno> and C<vec>, along these lines:
@@ -4688,6 +4842,7 @@ or <FH>) with C<select>, except as permitted by POSIX, and even
 then only on POSIX systems.  You have to use C<sysread> instead.
 
 =item semctl ID,SEMNUM,CMD,ARG
+X<semctl>
 
 Calls the System V IPC function C<semctl>.  You'll probably have to say
 
@@ -4703,6 +4858,7 @@ See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore>
 documentation.
 
 =item semget KEY,NSEMS,FLAGS
+X<semget>
 
 Calls the System V IPC function semget.  Returns the semaphore id, or
 the undefined value if there is an error.  See also
@@ -4710,6 +4866,7 @@ L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore>
 documentation.
 
 =item semop KEY,OPSTRING
+X<semop>
 
 Calls the System V IPC function semop to perform semaphore operations
 such as signalling and waiting.  OPSTRING must be a packed array of
@@ -4727,6 +4884,7 @@ L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore>
 documentation.
 
 =item send SOCKET,MSG,FLAGS,TO
+X<send>
 
 =item send SOCKET,MSG,FLAGS
 
@@ -4747,6 +4905,7 @@ Unicode characters, not bytes.  Similarly for the C<:encoding> pragma:
 in that case pretty much any characters can be sent.
 
 =item setpgrp PID,PGRP
+X<setpgrp> X<group>
 
 Sets the current process group for the specified PID, C<0> for the current
 process.  Will produce a fatal error if used on a machine that doesn't
@@ -4756,18 +4915,21 @@ accept any arguments, so only C<setpgrp(0,0)> is portable.  See also
 C<POSIX::setsid()>.
 
 =item setpriority WHICH,WHO,PRIORITY
+X<setpriority> X<priority> X<nice> X<renice>
 
 Sets the current priority for a process, a process group, or a user.
 (See setpriority(2).)  Will produce a fatal error if used on a machine
 that doesn't implement setpriority(2).
 
 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
+X<setsockopt>
 
 Sets the socket option requested.  Returns undefined if there is an
 error.  OPTVAL may be specified as C<undef> if you don't want to pass an
 argument.
 
 =item shift ARRAY
+X<shift>
 
 =item shift
 
@@ -4784,6 +4946,7 @@ same thing to the left end of an array that C<pop> and C<push> do to the
 right end.
 
 =item shmctl ID,CMD,ARG
+X<shmctl>
 
 Calls the System V IPC function shmctl.  You'll probably have to say
 
@@ -4796,12 +4959,15 @@ true" for zero, or the actual return value otherwise.
 See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmget KEY,SIZE,FLAGS
+X<shmget>
 
 Calls the System V IPC function shmget.  Returns the shared memory
 segment id, or the undefined value if there is an error.
 See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
 
 =item shmread ID,VAR,POS,SIZE
+X<shmread>
+X<shmwrite>
 
 =item shmwrite ID,STRING,POS,SIZE
 
@@ -4815,6 +4981,7 @@ shmread() taints the variable. See also L<perlipc/"SysV IPC">,
 C<IPC::SysV> documentation, and the C<IPC::Shareable> module from CPAN.
 
 =item shutdown SOCKET,HOW
+X<shutdown>
 
 Shuts down a socket connection in the manner indicated by HOW, which
 has the same interpretation as in the system call of the same name.
@@ -4830,6 +4997,7 @@ disables the file descriptor in any forked copies in other
 processes.
 
 =item sin EXPR
+X<sin> X<sine> X<asin> X<arcsine>
 
 =item sin
 
@@ -4842,6 +5010,7 @@ function, or use this relation:
     sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
 
 =item sleep EXPR
+X<sleep> X<pause>
 
 =item sleep
 
@@ -4866,6 +5035,7 @@ help.
 See also the POSIX module's C<pause> function.
 
 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
+X<socket>
 
 Opens a socket of the specified kind and attaches it to filehandle
 SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
@@ -4878,6 +5048,7 @@ be set for the newly opened file descriptor, as determined by the
 value of $^F.  See L<perlvar/$^F>.
 
 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
+X<socketpair>
 
 Creates an unnamed pair of sockets in the specified domain, of the
 specified type.  DOMAIN, TYPE, and PROTOCOL are specified the same as
@@ -4901,6 +5072,7 @@ emulate socketpair using IP sockets to localhost if your system implements
 sockets but not socketpair.
 
 =item sort SUBNAME LIST
+X<sort> X<qsort> X<quicksort> X<mergesort>
 
 =item sort BLOCK LIST
 
@@ -5071,6 +5243,7 @@ eliminate any C<NaN>s from the input.
     @result = sort { $a <=> $b } grep { $_ == $_ } @input;
 
 =item splice ARRAY,OFFSET,LENGTH,LIST
+X<splice>
 
 =item splice ARRAY,OFFSET,LENGTH
 
@@ -5113,6 +5286,7 @@ Example, assuming array lengths are passed before arrays:
     if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }
 
 =item split /PATTERN/,EXPR,LIMIT
+X<split>
 
 =item split /PATTERN/,EXPR
 
@@ -5227,6 +5401,7 @@ matched in a C<split()> will be set to C<undef> when returned:
     # @fields is (1, 'A', 2, undef, 3)
 
 =item sprintf FORMAT, LIST
+X<sprintf>
 
 Returns a string formatted by the usual C<printf> conventions of the C
 library function C<sprintf>.  See below for more details
@@ -5363,6 +5538,7 @@ If a field width obtained through C<*> is negative, it has the same
 effect as the C<-> flag: left-justification.
 
 =item precision, or maximum width
+X<precision>
 
 You can specify a precision (for numeric conversions) or a maximum
 width (for string conversions) by specifying a C<.> followed by a number.
@@ -5500,6 +5676,7 @@ point in formatted real numbers is affected by the LC_NUMERIC locale.
 See L<perllocale>.
 
 =item sqrt EXPR
+X<sqrt> X<root> X<square root>
 
 =item sqrt
 
@@ -5511,6 +5688,7 @@ loaded the standard Math::Complex module.
     print sqrt(-2);    # prints 1.4142135623731i
 
 =item srand EXPR
+X<srand> X<seed> X<randseed>
 
 =item srand
 
@@ -5572,6 +5750,7 @@ for a seed can fall prey to the mathematical property that
 one-third of the time.  So don't do that.
 
 =item stat FILEHANDLE
+X<stat> X<file, status>
 
 =item stat EXPR
 
@@ -5702,6 +5881,7 @@ about the C<S_*> constants.  To get status info for a symbolic link
 instead of the target file behind the link, use the C<lstat> function.
 
 =item study SCALAR
+X<study>
 
 =item study
 
@@ -5761,6 +5941,7 @@ out the names of those files that contain a match:
     }
 
 =item sub NAME BLOCK
+X<sub>
 
 =item sub NAME (PROTO) BLOCK
 
@@ -5778,6 +5959,7 @@ references, and L<attributes> and L<Attribute::Handlers> for more
 information about attributes.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
+X<substr> X<substring> X<mid> X<left> X<right>
 
 =item substr EXPR,OFFSET,LENGTH
 
@@ -5831,6 +6013,7 @@ Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
 unspecified.
 
 =item symlink OLDFILE,NEWFILE
+X<symlink> X<link> X<symbolic link> X<link, symbolic>
 
 Creates a new filename symbolically linked to the old filename.
 Returns C<1> for success, C<0> otherwise.  On systems that don't support
@@ -5840,6 +6023,7 @@ use eval:
     $symlink_exists = eval { symlink("",""); 1 };
 
 =item syscall NUMBER, LIST
+X<syscall> X<system call>
 
 Calls the system call specified as the first element of the list,
 passing the remaining elements as arguments to the system call.  If
@@ -5874,6 +6058,7 @@ to retrieve the file number of the other end.  You can avoid this
 problem by using C<pipe> instead.
 
 =item sysopen FILEHANDLE,FILENAME,MODE
+X<sysopen>
 
 =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
 
@@ -5892,6 +6077,7 @@ using the C<|>-operator.
 Some of the most common values are C<O_RDONLY> for opening the file in
 read-only mode, C<O_WRONLY> for opening the file in write-only mode,
 and C<O_RDWR> for opening the file in read-write mode.
+X<O_RDONLY> X<O_RDWR> X<O_WRONLY>
 
 For historical reasons, some values work on almost every system
 supported by perl: zero means read-only, one means write-only, and two
@@ -5905,6 +6091,7 @@ PERMS specifies the permissions of the newly created file.  If you omit
 the PERMS argument to C<sysopen>, Perl uses the octal value C<0666>.
 These permission values need to be in octal, and are modified by your
 process's current C<umask>.
+X<O_CREAT>
 
 In many systems the C<O_EXCL> flag is available for opening files in
 exclusive mode.  This is B<not> locking: exclusiveness means here that
@@ -5913,10 +6100,12 @@ on network filesystems, and has no effect unless the C<O_CREAT> flag
 is set as well.  Setting C<O_CREAT|O_EXCL> prevents the file from
 being opened if it is a symbolic link.  It does not protect against
 symbolic links in the file's path.
+X<O_EXCL>
 
 Sometimes you may want to truncate an already-existing file.  This
 can be done using the C<O_TRUNC> flag.  The behavior of
 C<O_TRUNC> with C<O_RDONLY> is undefined.
+X<O_TRUNC>
 
 You should seldom if ever use C<0644> as argument to C<sysopen>, because
 that takes away the user's option to have a more permissive umask.
@@ -5932,6 +6121,7 @@ library, or perhaps using the POSIX::open() function.
 See L<perlopentut> for a kinder, gentler explanation of opening files.
 
 =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<sysread>
 
 =item sysread FILEHANDLE,SCALAR,LENGTH
 
@@ -5963,6 +6153,7 @@ The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
 See L</binmode>, L</open>, and the C<open> pragma, L<open>.
 
 =item sysseek FILEHANDLE,POSITION,WHENCE
+X<sysseek> X<lseek>
 
 Sets FILEHANDLE's system position in bytes using the system call
 lseek(2).  FILEHANDLE may be an expression whose value gives the name
@@ -5994,6 +6185,7 @@ true on success and false on failure, yet you can still easily determine
 the new position.
 
 =item system LIST
+X<system> X<shell>
 
 =item system PROGRAM LIST
 
@@ -6059,6 +6251,7 @@ and return codes will be subject to its quirks and capabilities.
 See L<perlop/"`STRING`"> and L</exec> for details.
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<syswrite>
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH
 
@@ -6087,6 +6280,7 @@ The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
 See L</binmode>, L</open>, and the C<open> pragma, L<open>.
 
 =item tell FILEHANDLE
+X<tell>
 
 =item tell
 
@@ -6111,6 +6305,7 @@ that has been manipulated by sysread(), syswrite() or sysseek().
 Those functions ignore the buffering, while tell() does not.
 
 =item telldir DIRHANDLE
+X<telldir>
 
 Returns the current position of the C<readdir> routines on DIRHANDLE.
 Value may be given to C<seekdir> to access a particular location in a
@@ -6118,6 +6313,7 @@ directory.  C<telldir> has the same caveats about possible directory
 compaction as the corresponding system library routine.
 
 =item tie VARIABLE,CLASSNAME,LIST
+X<tie>
 
 This function binds a variable to a package class that will provide the
 implementation for the variable.  VARIABLE is the name of the variable
@@ -6209,6 +6405,7 @@ or the F<Config> module for interesting C<tie> implementations.
 For further details see L<perltie>, L<"tied VARIABLE">.
 
 =item tied VARIABLE
+X<tied>
 
 Returns a reference to the object underlying VARIABLE (the same value
 that was originally returned by the C<tie> call that bound the variable
@@ -6216,6 +6413,7 @@ to a package.)  Returns the undefined value if VARIABLE isn't tied to a
 package.
 
 =item time
+X<time> X<epoch>
 
 Returns the number of non-leap seconds since whatever time the system
 considers to be the epoch, suitable for feeding to C<gmtime> and
@@ -6230,6 +6428,7 @@ gettimeofday(2), you may be able to use the C<syscall> interface of Perl.
 See L<perlfaq8> for details.
 
 =item times
+X<times>
 
 Returns a four-element list giving the user and system times, in
 seconds, for this process and the children of this process.
@@ -6243,6 +6442,7 @@ In scalar context, C<times> returns C<$user>.
 The transliteration operator.  Same as C<y///>.  See L<perlop>.
 
 =item truncate FILEHANDLE,LENGTH
+X<truncate>
 
 =item truncate EXPR,LENGTH
 
@@ -6255,6 +6455,7 @@ The behavior is undefined if LENGTH is greater than the length of the
 file.
 
 =item uc EXPR
+X<uc> X<uppercase> X<toupper>
 
 =item uc
 
@@ -6268,6 +6469,7 @@ C<ucfirst> for that.
 If EXPR is omitted, uses C<$_>.
 
 =item ucfirst EXPR
+X<ucfirst> X<uppercase>
 
 =item ucfirst
 
@@ -6280,6 +6482,7 @@ for more details about locale and Unicode support.
 If EXPR is omitted, uses C<$_>.
 
 =item umask EXPR
+X<umask>
 
 =item umask
 
@@ -6317,6 +6520,7 @@ Remember that a umask is a number, usually given in octal; it is I<not> a
 string of octal digits.  See also L</oct>, if all you have is a string.
 
 =item undef EXPR
+X<undef> X<undefine>
 
 =item undef
 
@@ -6343,6 +6547,7 @@ parameter.  Examples:
 Note that this is a unary operator, not a list operator.
 
 =item unlink LIST
+X<unlink> X<delete> X<remove> X<rm>
 
 =item unlink
 
@@ -6361,6 +6566,7 @@ filesystem.  Use C<rmdir> instead.
 If LIST is omitted, uses C<$_>.
 
 =item unpack TEMPLATE,EXPR
+X<unpack>
 
 =item unpack TEMPLATE
 
@@ -6421,11 +6627,13 @@ the rest is ignored.
 See L</pack> for more examples and notes.
 
 =item untie VARIABLE
+X<untie>
 
 Breaks the binding between a variable and a package.  (See C<tie>.)
 Has no effect if the variable is not tied.
 
 =item unshift ARRAY,LIST
+X<unshift>
 
 Does the opposite of a C<shift>.  Or the opposite of a C<push>,
 depending on how you look at it.  Prepends list to the front of the
@@ -6438,6 +6646,7 @@ prepended elements stay in the same order.  Use C<reverse> to do the
 reverse.
 
 =item use Module VERSION LIST
+X<use> X<module> X<import>
 
 =item use Module VERSION
 
@@ -6536,6 +6745,7 @@ for the C<-M> and C<-m> command-line options to perl that give C<use>
 functionality from the command-line.
 
 =item utime LIST
+X<utime>
 
 Changes the access and modification times on each file of a list of
 files.  The first two elements of the list must be the NUMERICAL access
@@ -6570,6 +6780,7 @@ described when they are both C<undef>.  This case will also trigger an
 uninitialized warning.
 
 =item values HASH
+X<values>
 
 Returns a list consisting of all the values of the named hash.
 (In a scalar context, returns the number of values.)
@@ -6594,6 +6805,7 @@ modify the contents of the hash:
 See also C<keys>, C<each>, and C<sort>.
 
 =item vec EXPR,OFFSET,BITS
+X<vec> X<bit> X<bit vector>
 
 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
@@ -6834,6 +7046,7 @@ example should print the following table:
     vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
 
 =item wait
+X<wait>
 
 Behaves like the wait(2) system call on your system: it waits for a child
 process to terminate and returns the pid of the deceased process, or
@@ -6843,6 +7056,7 @@ Note that a return value of C<-1> could mean that child processes are
 being automatically reaped, as described in L<perlipc>.
 
 =item waitpid PID,FLAGS
+X<waitpid>
 
 Waits for a particular child process to terminate and returns the pid of
 the deceased process, or C<-1> if there is no such child process.  On some
@@ -6867,6 +7081,7 @@ processes are being automatically reaped.  See L<perlipc> for details,
 and for other examples.
 
 =item wantarray
+X<wantarray> X<context>
 
 Returns true if the context of the currently executing subroutine or
 C<eval> is looking for a list value.  Returns false if the context is
@@ -6884,6 +7099,7 @@ method.
 This function should have been named wantlist() instead.
 
 =item warn LIST
+X<warn> X<warning> X<STDERR>
 
 Produces a message on STDERR just like C<die>, but doesn't exit or throw
 an exception.
@@ -6927,6 +7143,7 @@ examples.  See the Carp module for other kinds of warnings using its
 carp() and cluck() functions.
 
 =item write FILEHANDLE
+X<write>
 
 =item write EXPR
 
index f250fb4..8274c4d 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<warning, lexical> X<warnings> X<warning>
 
 perllexwarn - Perl Lexical Warnings
 
@@ -130,6 +131,7 @@ warnings are (or aren't) produced:
 =over 5
 
 =item B<-w>
+X<-w>
 
 This is  the existing flag. If the lexical warnings pragma is B<not>
 used in any of you code, or any of the modules that you use, this flag
@@ -137,6 +139,7 @@ will enable warnings everywhere. See L<Backward Compatibility> for
 details of how this flag interacts with lexical warnings.
 
 =item B<-W>
+X<-W>
 
 If the B<-W> flag is used on the command line, it will enable all warnings
 throughout the program regardless of whether warnings were disabled
@@ -145,6 +148,7 @@ included via C<use>, C<require> or C<do>.
 Think of it as the Perl equivalent of the "lint" command.
 
 =item B<-X>
+X<-X>
 
 Does the exact opposite to the B<-W> flag, i.e. it disables all warnings.
 
@@ -199,6 +203,7 @@ the C<warnings> pragma to control the warning behavior of $^W-type
 code (using a C<local $^W=0>) if it really wants to, but not vice-versa.
 
 =head2 Category Hierarchy
+X<warning, categories>
 
 A hierarchy of "categories" have been defined to allow groups of warnings
 to be enabled/disabled in isolation.
@@ -322,6 +327,7 @@ in its own right.
 
 
 =head2 Fatal Warnings
+X<warning, fatal>
 
 The presence of the word "FATAL" in the category list will escalate any
 warnings detected from the categories specified in the lexical scope
@@ -366,6 +372,7 @@ except for those in the "syntax" category.
     use warnings FATAL => 'all', NONFATAL => 'syntax';
 
 =head2 Reporting Warnings from a Module
+X<warning, reporting> X<warning, registering>
 
 The C<warnings> pragma provides a number of functions that are useful for
 module authors. These are used when you want to report a module-specific
index 99d08eb..fc49e34 100644 (file)
@@ -5,6 +5,7 @@ perlmod - Perl modules (packages and symbol tables)
 =head1 DESCRIPTION
 
 =head2 Packages
+X<package> X<namespace> X<variable, global> X<global variable> X<global>
 
 Perl provides a mechanism for alternative namespaces to protect
 packages from stomping on each other's variables.  In fact, there's
@@ -38,6 +39,7 @@ supported for backwards compatibility, if you try to use a string like
 C<"This is $owner's house">, you'll be accessing C<$owner::s>; that is,
 the $s variable in package C<owner>, which is probably not what you meant.
 Use braces to disambiguate, as in C<"This is ${owner}'s house">.
+X<::> X<'>
 
 Packages may themselves contain package separators, as in
 C<$OUTER::INNER::var>.  This implies nothing about the order of
@@ -57,6 +59,7 @@ even when used for other purposes than their built-in ones.  If you
 have a package called C<m>, C<s>, or C<y>, 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.
+X<variable, punctuation> 
 
 Variables beginning with underscore used to be forced into package
 main, but we decided it was more useful for package writers to be able
@@ -83,6 +86,7 @@ See L<perlsub> for other scoping issues related to my() and local(),
 and L<perlref> regarding closures.
 
 =head2 Symbol Tables
+X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias>
 
 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
@@ -179,6 +183,7 @@ when you don't want to have to remember to dereference variables
 explicitly.
 
 Another use of symbol tables is for making "constant" scalars.
+X<constant> X<scalar, constant>
 
     *PI = \3.14159265358979;
 
@@ -254,6 +259,7 @@ This also has implications for the use of the SUPER:: qualifier
 (see L<perlobj>).
 
 =head2 BEGIN, CHECK, INIT and END
+X<BEGIN> X<CHECK> X<INIT> X<END>
 
 Four specially named code blocks are executed at the beginning and at the end
 of a running Perl program.  These are the C<BEGIN>, C<CHECK>, C<INIT>, and
@@ -299,6 +305,7 @@ Inside an C<END> code block, C<$?> contains the value that the program is
 going to pass to C<exit()>.  You can modify C<$?> to change the exit
 value of the program.  Beware of changing C<$?> by accident (e.g. by
 running something via C<system>).
+X<$?>
 
 C<CHECK> and C<INIT> code blocks are useful to catch the transition between
 the compilation phase and the execution phase of the main program.
@@ -348,6 +355,7 @@ The B<begincheck> program makes it all clear, eventually:
   __END__
 
 =head2 Perl Classes
+X<class> X<@ISA>
 
 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
@@ -358,6 +366,7 @@ must be a package global, not a lexical).
 For more on this, see L<perltoot> and L<perlobj>.
 
 =head2 Perl Modules
+X<module>
 
 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
@@ -529,6 +538,9 @@ although the POSIX module happens to do both dynamic loading and
 autoloading, the user can say just C<use POSIX> to get it all.
 
 =head2 Making your module threadsafe
+X<threadsafe> X<thread safe>
+X<module, threadsafe> X<module, thread safe>
+X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
 
 Since 5.6.0, Perl has had support for a new type of threads called
 interpreter threads (ithreads). These threads can be used explicitly
index f427de7..ad99627 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<object> X<OOP>
 
 perlobj - Perl objects
 
@@ -34,6 +35,7 @@ a package name, for class methods) as the first argument.
 We'll cover these points now in more depth.
 
 =head2 An Object is Simply a Reference
+X<object> X<bless> X<constructor> X<new>
 
 Unlike say C++, Perl doesn't provide any special syntax for
 constructors.  A constructor is merely a subroutine that returns a
@@ -139,6 +141,7 @@ This reports $b as being a BLAH, so obviously bless()
 operated on the object and not on the reference.
 
 =head2 A Class is Simply a Package
+X<class> X<package> X<@ISA> X<inheritance>
 
 Unlike say C++, Perl doesn't provide any special syntax for class
 definitions.  You use a package as a class by putting method
@@ -156,6 +159,7 @@ All classes implicitly inherit from class C<UNIVERSAL> as their
 last base class.  Several commonly used methods are automatically
 supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> for
 more details.
+X<UNIVERSAL> X<base class> X<class, base>
 
 If a missing method is found in a base class, it is cached
 in the current class for efficiency.  Changing @ISA or defining new
@@ -167,10 +171,12 @@ all over again, this time looking for a method named AUTOLOAD().  If an
 AUTOLOAD is found, this method is called on behalf of the missing method,
 setting the package global $AUTOLOAD to be the fully qualified name of
 the method that was intended to be called.
+X<AUTOLOAD>
 
 If none of that works, Perl finally gives up and complains.
 
 If you want to stop the AUTOLOAD inheritance say simply
+X<AUTOLOAD>
 
        sub AUTOLOAD;
 
@@ -184,6 +190,7 @@ by the various classes that might want to do something with the object.
 The only problem with this is that you can't sure that you aren't using
 a piece of the hash that isn't already used.  A reasonable workaround
 is to prepend your fieldname in the hash with the package name.
+X<inheritance, method> X<inheritance, data>
 
     sub bump {
        my $self = shift;
@@ -191,6 +198,7 @@ is to prepend your fieldname in the hash with the package name.
     } 
 
 =head2 A Method is Simply a Subroutine
+X<method>
 
 Unlike say C++, Perl doesn't provide any special syntax for method
 definition.  (It does provide a little syntax for method invocation
@@ -228,6 +236,7 @@ and then uses that as an ordinary reference.
     }
 
 =head2 Method Invocation
+X<invocation> X<method> X<arrow> X<< -> >>
 
 For various historical and other reasons, Perl offers two equivalent
 ways to write a method call.  The simpler and more common way is to use
@@ -268,6 +277,7 @@ to start looking for the subroutines in C<Critter>.
 As a special case of the above, you may use the C<SUPER> pseudo-class to
 tell Perl to start looking for the method in the packages named in the
 current class's C<@ISA> list.  
+X<SUPER>
 
     package MyCritter;
     use base 'Critter';    # sets @MyCritter::ISA = ('Critter');
@@ -282,6 +292,7 @@ I<current package> and not to the superclass(es) of the object. Also, the
 C<SUPER> pseudo-class can only currently be used as a modifier to a method
 name, but not in any of the other ways that class names are normally used,
 eg:
+X<SUPER>
 
     something->SUPER::method(...);     # OK
     SUPER::method(...);                        # WRONG
@@ -298,6 +309,7 @@ and so is the following:
     my $fred = (reverse "rettirC")->find(reverse "derF");
 
 =head2 Indirect Object Syntax
+X<indirect object syntax> X<invocation, indirect> X<indirect>
 
 The other way to invoke a method is by using the so-called "indirect
 object" notation.  This syntax was available in Perl 4 long before
@@ -363,6 +375,7 @@ to read code using the indirect object notation, so it's important to be
 familiar with it.
 
 =head2 Default UNIVERSAL methods
+X<UNIVERSAL>
 
 The C<UNIVERSAL> package automatically contains the following methods that
 are inherited by all other classes:
@@ -370,6 +383,7 @@ are inherited by all other classes:
 =over 4
 
 =item isa(CLASS)
+X<isa>
 
 C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
 
@@ -379,6 +393,7 @@ class, so don't do it.
 
 If you need to determine whether you've received a valid invocant, use the
 C<blessed> function from L<Scalar::Util>:
+X<invocant> X<blessed>
 
     if (blessed($ref) && $ref->isa( 'Some::Class')) {
         # ...
@@ -388,6 +403,7 @@ C<blessed> returns the name of the package the argument has been
 blessed into, or C<undef>.
 
 =item can(METHOD)
+X<can>
 
 C<can> checks to see if its object has a method called C<METHOD>,
 if it does then a reference to the sub is returned, if it does not then
@@ -398,6 +414,7 @@ always return I<undef> if its first argument isn't an object or a class name.
 The same caveats for calling C<UNIVERSAL::isa> directly apply here, too.
 
 =item VERSION( [NEED] )
+X<VERSION>
 
 C<VERSION> returns the version number of the class (package).  If the
 NEED argument is given then it will check that the current version (as
@@ -421,6 +438,7 @@ You do not need to C<use UNIVERSAL> to make these methods
 available to your program (and you should not do so).
 
 =head2 Destructors
+X<destructor> X<DESTROY>
 
 When the last reference to an object goes away, the object is
 automatically destroyed.  (This may even be after you exit, if you've
@@ -453,6 +471,8 @@ book about object-oriented design methodology, and bang your forehead
 with it for the next six months or so.
 
 =head2 Two-Phased Garbage Collection
+X<garbage collection> X<GC> X<circular reference>
+X<reference, circular> X<DESTROY> X<destructor>
 
 For most purposes, Perl uses a fast and simple, reference-based
 garbage collection system.  That means there's an extra
index da7cef5..32a58b8 100644 (file)
@@ -1,10 +1,12 @@
 =head1 NAME
+X<operator>
 
 perlop - Perl operators and precedence
 
 =head1 DESCRIPTION
 
-=head2 Operator Precedence and Associativity
+=head2 Operator Precedence and Associativity 
+X<operator, precedence> X<precedence> X<associativity>
 
 Operator precedence and associativity work in Perl more or less like
 they do in mathematics.
@@ -58,6 +60,7 @@ In the following sections, these operators are covered in precedence order.
 Many operators can be overloaded for objects.  See L<overload>.
 
 =head2 Terms and List Operators (Leftward)
+X<list operator> X<operator, list> X<term>
 
 A TERM has the highest precedence in Perl.  They include variables,
 quote and quote-like operators, any expression in parentheses,
@@ -119,6 +122,7 @@ See also L<Quote and Quote-like Operators> toward the end of this section,
 as well as L<"I/O Operators">.
 
 =head2 The Arrow Operator
+X<arrow> X<dereference> X<< -> >>
 
 "C<< -> >>" is an infix dereference operator, just as it is in C
 and C++.  If the right side is either a C<[...]>, C<{...}>, or a
@@ -134,6 +138,7 @@ and the left side must be either an object (a blessed reference)
 or a class name (that is, a package name).  See L<perlobj>.
 
 =head2 Auto-increment and Auto-decrement
+X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
 
 "++" and "--" work as in C.  That is, if placed before a variable,
 they increment or decrement the variable by one before returning the
@@ -175,6 +180,7 @@ will return C<0> rather than C<undef>).
 The auto-decrement operator is not magical.
 
 =head2 Exponentiation
+X<**> X<exponentiation> X<power>
 
 Binary "**" is the exponentiation operator.  It binds even more
 tightly than unary minus, so -2**4 is -(2**4), not (-2)**4. (This is
@@ -182,9 +188,11 @@ implemented using C's pow(3) function, which actually works on doubles
 internally.)
 
 =head2 Symbolic Unary Operators
+X<unary operator> X<operator, unary>
 
 Unary "!" performs logical negation, i.e., "not".  See also C<not> for a lower
 precedence version of this.
+X<!>
 
 Unary "-" performs arithmetic negation if the operand is numeric.  If
 the operand is an identifier, a string consisting of a minus sign
@@ -192,6 +200,7 @@ 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 -bareword is equivalent
 to the string "-bareword".
+X<-> X<negation, arithmetic>
 
 Unary "~" performs bitwise negation, i.e., 1's complement.  For
 example, C<0666 & ~027> is 0640.  (See also L<Integer Arithmetic> and
@@ -199,18 +208,22 @@ L<Bitwise String Operators>.)  Note that the width of the result is
 platform-dependent: ~0 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 & operator to mask off the excess bits.
+X<~> X<negation, binary>
 
 Unary "+" 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 L<Terms and List Operators (Leftward)>.)
+X<+>
 
 Unary "\" creates a reference to whatever follows it.  See L<perlreftut>
 and L<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.
+X<\> X<reference> X<backslash>
 
 =head2 Binding Operators
+X<binding> X<operator, binding> X<=~> X<!~>
 
 Binary "=~" binds a scalar expression to a pattern match.  Certain operations
 search or modify the string $_ by default.  This operator makes that kind
@@ -230,10 +243,13 @@ Binary "!~" is just like "=~" except the return value is negated in
 the logical sense.
 
 =head2 Multiplicative Operators
+X<operator, multiplicative>
 
 Binary "*" multiplies two numbers.
+X<*>
 
 Binary "/" divides two numbers.
+X</> X<slash>
 
 Binary "%" computes the modulus of two numbers.  Given integer
 operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is
@@ -245,6 +261,7 @@ Note that when C<use integer> is in scope, "%" gives you direct access
 to the modulus operator as implemented by your C compiler.  This
 operator is not as well defined for negative operands, but it will
 execute faster.
+X<%> X<remainder> X<modulus> X<mod>
 
 Binary "x" is the repetition operator.  In scalar context or if the left
 operand is not enclosed in parentheses, it returns a string consisting
@@ -253,6 +270,7 @@ operand.  In list context, if the left operand is enclosed in
 parentheses or is a list formed by C<qw/STRING/>, it repeats the list.
 If the right operand is zero or negative, it returns an empty string
 or an empty list, depending on the context.
+X<x>
 
     print '-' x 80;            # print row of dashes
 
@@ -263,14 +281,22 @@ or an empty list, depending on the context.
 
 
 =head2 Additive Operators
+X<operator, additive>
 
 Binary "+" returns the sum of two numbers.
+X<+>
 
 Binary "-" returns the difference of two numbers.
+X<->
 
 Binary "." concatenates two strings.
+X<string, concatenation> X<concatenation>
+X<cat> X<concat> X<concatenate> X<.>
 
 =head2 Shift Operators
+X<shift operator> X<operator, shift> X<<< << >>>
+X<<< >> >>> X<right shift> X<left shift> X<bitwise shift>
+X<shl> X<shr> X<shift, right> X<shift, left>
 
 Binary "<<" returns the value of its left argument shifted left by the
 number of bits specified by the right argument.  Arguments should be
@@ -293,6 +319,7 @@ integers, C<< 1 << 32 >> is undefined.  Shifting by a negative number
 of bits is also undefined.
 
 =head2 Named Unary Operators
+X<operator, named unary>
 
 The various named unary operators are treated as functions with one
 argument, with optional parentheses.
@@ -324,42 +351,55 @@ Regarding precedence, the filetest operators, like C<-f>, C<-M>, etc. are
 treated like named unary operators, but they don't follow this functional
 parenthesis rule.  That means, for example, that C<-f($file).".bak"> is
 equivalent to C<-f "$file.bak">.
+X<-X> X<filetest> X<operator, filetest>
 
 See also L<"Terms and List Operators (Leftward)">.
 
 =head2 Relational Operators
+X<relational operator> X<operator, relational>
 
 Binary "<" returns true if the left argument is numerically less than
 the right argument.
+X<< < >>
 
 Binary ">" returns true if the left argument is numerically greater
 than the right argument.
+X<< > >>
 
 Binary "<=" returns true if the left argument is numerically less than
 or equal to the right argument.
+X<< <= >>
 
 Binary ">=" returns true if the left argument is numerically greater
 than or equal to the right argument.
+X<< >= >>
 
 Binary "lt" returns true if the left argument is stringwise less than
 the right argument.
+X<< lt >>
 
 Binary "gt" returns true if the left argument is stringwise greater
 than the right argument.
+X<< gt >>
 
 Binary "le" returns true if the left argument is stringwise less than
 or equal to the right argument.
+X<< le >>
 
 Binary "ge" returns true if the left argument is stringwise greater
 than or equal to the right argument.
+X<< ge >>
 
 =head2 Equality Operators
+X<equality> X<equal> X<equals> X<operator, equality>
 
 Binary "==" returns true if the left argument is numerically equal to
 the right argument.
+X<==>
 
 Binary "!=" returns true if the left argument is numerically not equal
 to the right argument.
+X<!=>
 
 Binary "<=>" returns -1, 0, or 1 depending on whether the left
 argument is numerically less than, equal to, or greater than the right
@@ -368,24 +408,29 @@ values, using them with "<=>" returns undef.  NaN is not "<", "==", ">",
 "<=" or ">=" anything (even NaN), so those 5 return false. NaN != NaN
 returns true, as does NaN != anything else. If your platform doesn't
 support NaNs then NaN is just a string with numeric value 0.
+X<< <=> >> X<spaceship>
 
     perl -le '$a = "NaN"; print "No NaN support here" if $a == $a'
     perl -le '$a = "NaN"; print "NaN support here" if $a != $a'
 
 Binary "eq" returns true if the left argument is stringwise equal to
 the right argument.
+X<eq>
 
 Binary "ne" returns true if the left argument is stringwise not equal
 to the right argument.
+X<ne>
 
 Binary "cmp" returns -1, 0, or 1 depending on whether the left
 argument is stringwise less than, equal to, or greater than the right
 argument.
+X<cmp>
 
 "lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
 by the current locale if C<use locale> is in effect.  See L<perllocale>.
 
 =head2 Bitwise And
+X<operator, bitwise, and> X<bitwise and> X<&>
 
 Binary "&" returns its operands ANDed together bit by bit.
 (See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
@@ -396,6 +441,8 @@ the brackets are essential in a test like
        print "Even\n" if ($x & 1) == 0;
 
 =head2 Bitwise Or and Exclusive Or
+X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
+X<bitwise xor> X<^>
 
 Binary "|" returns its operands ORed together bit by bit.
 (See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
@@ -409,6 +456,7 @@ for example the brackets are essential in a test like
        print "false\n" if (8 | 2) != 10;
 
 =head2 C-style Logical And
+X<&&> X<logical and> X<operator, logical, and>
 
 Binary "&&" performs a short-circuit logical AND operation.  That is,
 if the left operand is false, the right operand is not even evaluated.
@@ -416,6 +464,7 @@ Scalar or list context propagates down to the right operand if it
 is evaluated.
 
 =head2 C-style Logical Or
+X<||> X<operator, logical, or>
 
 Binary "||" performs a short-circuit logical OR operation.  That is,
 if the left operand is true, the right operand is not even evaluated.
@@ -423,6 +472,7 @@ Scalar or list context propagates down to the right operand if it
 is evaluated.
 
 =head2 C-style Logical Defined-Or
+X<//> X<operator, logical, defined-or>
 
 Although it has no direct equivalent in C, Perl's C<//> operator is related
 to its C-style or.  In fact, it's exactly the same as C<||>, except that it 
@@ -464,6 +514,7 @@ With the C-style operators that would have been written like this:
 Using "or" for assignment is unlikely to do what you want; see below.
 
 =head2 Range Operators
+X<operator, range> X<range> X<..> X<...>
 
 Binary ".." is the range operator, which is really two different
 operators depending on the context.  In list context, it returns a
@@ -595,6 +646,7 @@ return two elements in list context.
     @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
 
 =head2 Conditional Operator
+X<operator, conditional> X<operator, ternary> X<ternary> X<?:>
 
 Ternary "?:" is the conditional operator, just as in C.  It works much
 like an if-then-else.  If the argument before the ? is true, the
@@ -634,6 +686,9 @@ That should probably be written more simply as:
     $a += ($a % 2) ? 10 : 2;
 
 =head2 Assignment Operators
+X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=>
+X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<.=>
+X<%=> X<^=> X<x=>
 
 "=" is the ordinary assignment operator.
 
@@ -679,6 +734,7 @@ the number of elements produced by the expression on the right hand
 side of the assignment.
 
 =head2 Comma Operator
+X<comma> X<operator, comma> X<,>
 
 Binary "," is the comma operator.  In scalar context it evaluates
 its left argument, throws that value away, then evaluates its right
@@ -714,6 +770,7 @@ between keys and values in hashes, and other paired elements in lists.
         login( $username => $password );
 
 =head2 List Operators (Rightward)
+X<operator, list, rightward> X<list operator>
 
 On the right side of a list operator, it has very low precedence,
 such that it controls all comma-separated expressions found there.
@@ -727,11 +784,13 @@ operators without the need for extra parentheses:
 See also discussion of list operators in L<Terms and List Operators (Leftward)>.
 
 =head2 Logical Not
+X<operator, logical, not> X<not>
 
 Unary "not" returns the logical negation of the expression to its right.
 It's the equivalent of "!" except for the very low precedence.
 
 =head2 Logical And
+X<operator, logical, and> X<and>
 
 Binary "and" returns the logical conjunction of the two surrounding
 expressions.  It's equivalent to && except for the very low
@@ -739,6 +798,9 @@ precedence.  This means that it short-circuits: i.e., the right
 expression is evaluated only if the left expression is true.
 
 =head2 Logical or, Defined or, and Exclusive Or
+X<operator, logical, or> X<operator, logical, xor> X<operator, logical, err>
+X<operator, logical, defined or> X<operator, logical, exclusive or>
+X<or> X<xor> X<err>
 
 Binary "or" returns the logical disjunction of the two surrounding
 expressions.  It's equivalent to || except for the very low precedence.
@@ -772,6 +834,8 @@ Binary "xor" returns the exclusive-OR of the two surrounding expressions.
 It cannot short circuit, of course.
 
 =head2 C Operators Missing From Perl
+X<operator, missing from perl> X<&> X<*>
+X<typecasting> X<(TYPE)>
 
 Here is what C has that Perl doesn't:
 
@@ -793,6 +857,10 @@ Type-casting operator.
 =back
 
 =head2 Quote and Quote-like Operators
+X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m> 
+X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>>
+X<escape sequence> X<escape>
+
 
 While we usually think of quotes as literal values, in Perl they
 function as operators, providing various kinds of interpolating and
@@ -843,6 +911,7 @@ from the next line.  This allows you to write:
 
 The following escape sequences are available in constructs that interpolate
 and in transliterations.
+X<\t> X<\n> X<\r> X<\f> X<\b> X<\a> X<\e> X<\x> X<\0> X<\c> X<\N>
 
     \t         tab             (HT, TAB)
     \n         newline         (NL)
@@ -862,6 +931,7 @@ the vertical tab (VT - ASCII 11).
 
 The following escape sequences are available in constructs that interpolate
 but not in transliterations.
+X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q>
 
     \l         lowercase next char
     \u         uppercase next char
@@ -890,6 +960,8 @@ and prefer a CR+LF (C<"\015\012"> or C<"\cM\cJ">) for line terminators,
 and although they often accept just C<"\012">, they seldom tolerate just
 C<"\015">.  If you get in the habit of using C<"\n"> for networking,
 you may be burned some day.
+X<newline> X<line terminator> X<eol> X<end of line>
+X<\n> X<\r> X<\r\n>
 
 For constructs that do interpolate, variables beginning with "C<$>"
 or "C<@>" are interpolated.  Subscripted variables such as C<$a[3]> or
@@ -919,6 +991,7 @@ within double quotes, nor do single quotes impede evaluation of
 variables when used within double quotes.
 
 =head2 Regexp Quote-Like Operators
+X<operator, regexp>
 
 Here are the quote-like operators that apply to pattern
 matching and related activities.
@@ -926,6 +999,7 @@ matching and related activities.
 =over 8
 
 =item ?PATTERN?
+X<?>
 
 This is just like the C</pattern/> search, except that it matches only
 once between calls to the reset() operator.  This is a useful
@@ -946,6 +1020,9 @@ be removed in some distant future version of Perl, perhaps somewhere
 around the year 2168.
 
 =item m/PATTERN/cgimosx
+X<m> X<operator, match> 
+X<regexp, options> X<regexp> X<regex, options> X<regex> 
+X</c> X</i> X</m> X</o> X</s> X</x>
 
 =item /PATTERN/cgimosx
 
@@ -1127,6 +1204,7 @@ Here is the output (split into several lines):
  MiXeD line-noise. That's all!
 
 =item q/STRING/
+X<q> X<quote, double> X<'> X<''>
 
 =item C<'STRING'>
 
@@ -1139,6 +1217,7 @@ the delimiter or backslash is interpolated.
     $baz = '\n';               # a two-character string
 
 =item qq/STRING/
+X<qq> X<quote, double> X<"> X<"">
 
 =item "STRING"
 
@@ -1150,6 +1229,7 @@ A double-quoted, interpolated string.
     $baz = "\n";               # a one-character string
 
 =item qr/STRING/imosx
+X<qr> X</i> X</m> X</o> X</s> X</x>
 
 This operator quotes (and possibly compiles) its I<STRING> as a regular
 expression.  I<STRING> is interpolated the same way as I<PATTERN>
@@ -1207,6 +1287,7 @@ See L<perlre> for additional information on valid syntax for STRING, and
 for a detailed look at the semantics of regular expressions.
 
 =item qx/STRING/
+X<qx> X<`> X<``> X<backtick>
 
 =item `STRING`
 
@@ -1288,6 +1369,7 @@ Just understand what you're getting yourself into.
 See L<"I/O Operators"> for more discussion.
 
 =item qw/STRING/
+X<qw> X<quote, list> X<quote, words>
 
 Evaluates to a list of the words extracted out of STRING, using embedded
 whitespace as the word delimiters.  It can be understood as being roughly
@@ -1316,6 +1398,8 @@ C<use warnings> pragma and the B<-w> switch (that is, the C<$^W> variable)
 produces warnings if the STRING contains the "," or the "#" character.
 
 =item s/PATTERN/REPLACEMENT/egimosx
+X<substitute> X<substitution> X<replace> X<regexp, replace>
+X<regexp, substitute> X</e> X</g> X</i> X</m> X</o> X</s> X</x>
 
 Searches a string for a pattern, and if found, replaces that pattern
 with the replacement text and returns the number of substitutions
@@ -1423,6 +1507,7 @@ to occur that you might want.  Here are two common cases:
     1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
 
 =item tr/SEARCHLIST/REPLACEMENTLIST/cds
+X<tr> X<y> X<transliterate> X</c> X</d> X</s>
 
 =item y/SEARCHLIST/REPLACEMENTLIST/cds
 
@@ -1512,6 +1597,7 @@ must use an eval():
     eval "tr/$oldlist/$newlist/, 1" or die $@;
 
 =item <<EOF
+X<here-doc> X<heredoc> X<here-document> X<<< << >>>
 
 A line-oriented form of quoting is based on the shell "here-document"
 syntax.  Following a C<< << >> you specify a string to terminate
@@ -1606,6 +1692,7 @@ should be safe.
 =back
 
 =head2 Gory details of parsing quoted constructs
+X<quote, gory details>
 
 When presented with something that might have several different
 interpretations, Perl uses the B<DWIM> (that's "Do What I Mean")
@@ -1686,6 +1773,7 @@ Starting from this step no information about the delimiters is
 used in parsing.
 
 =item Interpolation
+X<interpolation>
 
 The next step is interpolation in the text obtained, which is now
 delimiter-independent.  There are four different cases.
@@ -1799,6 +1887,7 @@ This step is the last one for all constructs except regular expressions,
 which are processed further.
 
 =item Interpolation of regular expressions
+X<regexp, interpolation>
 
 Previous steps were performed during the compilation of Perl code,
 but this one happens at run time--although it may be optimized to
@@ -1837,6 +1926,7 @@ in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line
 switch documented in L<perlrun/"Command Switches">.
 
 =item Optimization of regular expressions
+X<regexp, optimization>
 
 This step is listed for completeness only.  Since it does not change
 semantics, details of this step are not documented and are subject
@@ -1849,6 +1939,8 @@ mean C</^/m>.
 =back
 
 =head2 I/O Operators
+X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle>
+X<< <> >> X<@ARGV>
 
 There are several I/O operators you should know about.
 
@@ -1868,6 +1960,7 @@ literal dollar-sign through to the shell you need to hide it with a
 backslash.  The generalized form of backticks is C<qx//>.  (Because
 backticks always undergo shell expansion as well, see L<perlsec> for
 security concerns.)
+X<qx> X<`> X<``> X<backtick> X<glob>
 
 In scalar context, evaluating a filehandle in angle brackets yields
 the next line from that file (the newline, if any, included), or
@@ -1921,6 +2014,7 @@ in packages, where they would be interpreted as local identifiers
 rather than global.)  Additional filehandles may be created with
 the open() function, amongst others.  See L<perlopentut> and
 L<perlfunc/open> for details on this.
+X<stdin> X<stdout> X<sterr>
 
 If a <FILEHANDLE> is used in a context that is looking for
 a list, a list comprising all input lines is returned, one line per
@@ -2066,6 +2160,7 @@ to become confused with the indirect filehandle notation.
     @files = glob($files[$i]);
 
 =head2 Constant Folding
+X<constant folding> X<folding>
 
 Like C, Perl does a certain amount of expression evaluation at
 compile time whenever it determines that all arguments to an
@@ -2088,6 +2183,7 @@ the compiler will precompute the number which that expression
 represents so that the interpreter won't have to.
 
 =head2 No-ops
+X<no-op> X<nop>
 
 Perl doesn't officially have a no-op operator, but the bare constants
 C<0> and C<1> are special-cased to not produce a warning in a void
@@ -2096,6 +2192,7 @@ context, so you can for example safely do
     1 while foo();
 
 =head2 Bitwise String Operators
+X<operator, bitwise, string>
 
 Bitstrings of any size may be manipulated by the bitwise operators
 (C<~ | & ^>).
@@ -2130,6 +2227,7 @@ See L<perlfunc/vec> for information on how to manipulate individual bits
 in a bit vector.
 
 =head2 Integer Arithmetic
+X<integer>
 
 By default, Perl assumes that it must do most of its arithmetic in
 floating point.  But by saying
@@ -2158,6 +2256,7 @@ integral value.  However, C<use integer; ~0> is C<-1> on twos-complement
 machines.
 
 =head2 Floating-point Arithmetic
+X<floating-point> X<floating point> X<float> X<real>
 
 While C<use integer> provides integer-only arithmetic, there is no
 analogous mechanism to provide automatic rounding or truncation to a
@@ -2200,6 +2299,7 @@ being used by Perl, but to instead implement the rounding function you
 need yourself.
 
 =head2 Bigger Numbers
+X<number, arbitrary precision>
 
 The standard Math::BigInt and Math::BigFloat modules provide
 variable-precision arithmetic and overloaded operators, although
index 955d706..3c8a67b 100644 (file)
@@ -4,6 +4,7 @@ This document is in Pod format.  To read this, use a Pod formatter,
 like "perldoc perlpod".
 
 =head1 NAME
+X<POD> X<plain old documentation>
 
 perlpod - the Plain Old Documentation format
 
@@ -22,6 +23,7 @@ L<command|/"Command Paragraph">.
 
 
 =head2 Ordinary Paragraph
+X<POD, ordinary paragraph>
 
 Most paragraphs in your documentation will be ordinary blocks
 of text, like this one.  You can simply type in your text without
@@ -37,6 +39,7 @@ section, below.
 
 
 =head2 Verbatim Paragraph
+X<POD, verbatim paragraph> X<verbatim>
 
 Verbatim paragraphs are usually used for presenting a codeblock or
 other text which does not require any special parsing or formatting,
@@ -51,6 +54,7 @@ nothing else.
 
 
 =head2 Command Paragraph
+X<POD, command>
 
 A command paragraph is used for special treatment of whole chunks
 of text, usually as headings or parts of lists.
@@ -78,6 +82,8 @@ To explain them each in detail:
 =over
 
 =item C<=head1 I<Heading Text>>
+X<=head1> X<=head2> X<=head3> X<=head4>
+X<head1> X<head2> X<head3> X<head4>
 
 =item C<=head2 I<Heading Text>>
 
@@ -102,6 +108,7 @@ Such commands are explained in the
 "L<Formatting Codes|/"Formatting Codes">" section, below.
 
 =item C<=over I<indentlevel>>
+X<=over> X<=item> X<=back> X<over> X<item> X<back>
 
 =item C<=item I<stuff...>>
 
@@ -157,6 +164,7 @@ list.
 =back
 
 =item C<=cut>
+X<=cut> X<cut>
 
 To end a Pod block, use a blank line,
 then a line beginning with "=cut", and a blank
@@ -165,6 +173,7 @@ this is where Perl code is resuming.  (The blank line before the "=cut"
 is not technically necessary, but many older Pod processors require it.)
 
 =item C<=pod>
+X<=pod> X<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
@@ -191,6 +200,7 @@ paragraph or a verbatim paragraph.  For example:
   =cut
 
 =item C<=begin I<formatname>>
+X<=begin> X<=end> X<=for> X<begin> X<end> X<for>
 
 =item C<=end I<formatname>>
 
@@ -270,6 +280,7 @@ normal formatting (e.g., may not be a normal-use paragraph, but might
 be for formatting as a footnote).
 
 =item C<=encoding I<encodingname>>
+X<=encoding> X<encoding>
 
 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 or Latin-1,
@@ -321,6 +332,8 @@ Some examples of lists include:
 
 
 =head2 Formatting Codes
+X<POD, formatting code> X<formatting code>
+X<POD, interior sequence> X<interior sequence>
 
 In ordinary paragraphs and in some command paragraphs, various
 formatting codes (a.k.a. "interior sequences") can be used:
@@ -332,11 +345,13 @@ formatting codes (a.k.a. "interior sequences") can be used:
 =over
 
 =item C<IE<lt>textE<gt>> -- italic text
+X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic>
 
 Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters
 ("C<redo IE<lt>LABELE<gt>>")
 
 =item C<BE<lt>textE<gt>> -- bold text
+X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold>
 
 Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs
 ("C<some systems provide a BE<lt>chfnE<gt> for that>"),
@@ -344,12 +359,14 @@ emphasis ("C<be BE<lt>careful!E<gt>>"), and so on
 ("C<and that feature is known as BE<lt>autovivificationE<gt>>").
 
 =item C<CE<lt>codeE<gt>> -- code text
+X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code>
 
 Renders code in a typewriter font, or gives some other indication that
 this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other
 form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>").
 
 =item C<LE<lt>nameE<gt>> -- a hyperlink
+X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink>
 
 There are various syntaxes, listed below.  In the syntaxes given,
 C<text>, C<name>, and C<section> cannot contain the characters
@@ -435,6 +452,7 @@ various reasons.
 =back
 
 =item C<EE<lt>escapeE<gt>> -- a character escape
+X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>
 
 Very similar to HTML/XML C<&I<foo>;> "entity references":
 
@@ -487,21 +505,26 @@ rendering C<EE<lt>eacuteE<gt>> as just a plain "e".)
 =back
 
 =item C<FE<lt>filenameE<gt>> -- used for filenames
+X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>
 
 Typically displayed in italics.  Example: "C<FE<lt>.cshrcE<gt>>"
 
 =item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
+X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space> 
+X<non-breaking space>
 
 This means that the words in I<text> should not be broken
 across lines.  Example: S<C<SE<lt>$x ? $y : $zE<gt>>>.
 
 =item C<XE<lt>topic nameE<gt>> -- an index entry
+X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>
 
 This is ignored by most formatters, but some may use it for building
 indexes.  It always renders as empty-string.
 Example: C<XE<lt>absolutizing relative URLsE<gt>>
 
 =item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code
+X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>
 
 This is rarely used.  It's one way to get around using an
 EE<lt>...E<gt> code sometimes.  For example, instead of
@@ -538,6 +561,7 @@ angle brackets ("<<" and ">>") may be used I<if and only if there is
 whitespace right after the opening delimiter and whitespace right
 before the closing delimiter!>  For example, the following will
 do the trick:
+X<POD, formatting code, escaping with multiple brackets>
 
     C<< $a <=> $b >>
 
@@ -547,6 +571,7 @@ 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:
+X<POD, formatting code, escaping with multiple brackets>
 
     C<<< $a <=> $b >>>
     C<<<<  $a <=> $b     >>>>
@@ -576,6 +601,7 @@ and any other pod2xxx or Pod::Xxxx translators that use
 Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
 
 =head2 The Intent
+X<POD, intent of>
 
 The intent is simplicity of use, not power of expression.  Paragraphs
 look like paragraphs (block format), so that they stand out
@@ -595,6 +621,7 @@ B<pod2fm>.  Various others are available in CPAN.
 
 
 =head2 Embedding Pods in Perl Modules
+X<POD, embedding>
 
 You can embed Pod documentation in your Perl modules and scripts.
 Start your documentation with an empty line, a "=head1" command at the
@@ -618,6 +645,7 @@ have recognized the "=head1" as starting a Pod block.
 =over
 
 =item *
+X<podchecker> X<POD, validating>
 
 The B<podchecker> command is provided for checking Pod syntax for errors
 and warnings.  For example, it checks for completely blank lines in
index 39110ff..23a7b0f 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<regular expression> X<regex> X<regexp>
 
 perlre - Perl regular expressions
 
@@ -24,6 +25,8 @@ L<perlop/"Gory details of parsing quoted constructs">.
 =over 4
 
 =item i
+X</i> X<regex, case-insensitive> X<regexp, case-insensitive>
+X<regular expression, case-insensitive>
 
 Do case-insensitive pattern matching.
 
@@ -31,12 +34,15 @@ If C<use locale> is in effect, the case map is taken from the current
 locale.  See L<perllocale>.
 
 =item m
+X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
 
 Treat string as multiple lines.  That is, change "^" and "$" from matching
 the start or end of the string to matching the start or end of any
 line anywhere within the string.
 
 =item s
+X</s> X<regex, single-line> X<regexp, single-line>
+X<regular expression, single-line>
 
 Treat string as single line.  That is, change "." to match any character
 whatsoever, even a newline, which normally it would not match.
@@ -46,6 +52,7 @@ while still allowing "^" and "$" to match, respectively, just after
 and just before newlines within the string.
 
 =item x
+X</x>
 
 Extend your pattern's legibility by permitting whitespace and comments.
 
@@ -70,6 +77,7 @@ more readable.  Note that you have to be careful not to include the
 pattern delimiter in the comment--perl has no way of knowing you did
 not intend to close the pattern early.  See the C-comment deletion code
 in L<perlop>.
+X</x>
 
 =head2 Regular Expressions
 
@@ -81,6 +89,9 @@ details.
 
 In particular the following metacharacters have their standard I<egrep>-ish
 meanings:
+X<metacharacter>
+X<\> X<^> X<.> X<$> X<|> X<(> X<()> X<[> X<[]>
+
 
     \  Quote the next metacharacter
     ^  Match the beginning of the line
@@ -100,12 +111,15 @@ newline within the string, and "$" will match before any newline.  At the
 cost of a little more overhead, you can do this by using the /m modifier
 on the pattern match operator.  (Older programs did this by setting C<$*>,
 but this practice has been removed in perl 5.9.)
+X<^> X<$> X</m>
 
 To simplify multi-line substitutions, the "." character never matches a
 newline unless you use the C</s> modifier, which in effect tells Perl to pretend
 the string is a single line--even if it isn't.
+X<.> X</s>
 
 The following standard quantifiers are recognized:
+X<metacharacter> X<quantifier> X<*> X<+> X<?> X<{n}> X<{n,}> X<{n,m}>
 
     *     Match 0 or more times
     +     Match 1 or more times
@@ -129,6 +143,8 @@ 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 "?".  Note
 that the meanings don't change, just the "greediness":
+X<metacharacter> X<greedy> X<greedyness>
+X<?> X<*?> X<+?> X<??> X<{n}?> X<{n,}?> X<{n,m}?>
 
     *?    Match 0 or more times
     +?    Match 1 or more times
@@ -139,6 +155,8 @@ that the meanings don't change, just the "greediness":
 
 Because patterns are processed as double quoted strings, the following
 also work:
+X<\t> X<\n> X<\r> X<\f> X<\a> X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q>
+X<\0> X<\c> X<\N> X<\x>
 
     \t         tab                   (HT, TAB)
     \n         newline               (LF, NL)
@@ -168,6 +186,9 @@ while escaping will cause the literal string C<\$> to be matched.
 You'll need to write something like C<m/\Quser\E\@\Qhost/>.
 
 In addition, Perl defines the following:
+X<metacharacter>
+X<\w> X<\W> X<\s> X<\S> X<\d> X<\D> X<\X> X<\p> X<\P> X<\C>
+X<word> X<whitespace>
 
     \w Match a "word" character (alphanumeric plus "_")
     \W Match a non-"word" character
@@ -196,13 +217,18 @@ literally.  If Unicode is in effect, C<\s> matches also "\x{85}",
 "\x{2028}, and "\x{2029}", see L<perlunicode> for more details about
 C<\pP>, C<\PP>, and C<\X>, and L<perluniintro> about Unicode in general.
 You can define your own C<\p> and C<\P> properties, see L<perlunicode>.
+X<\w> X<\W> X<word>
 
 The POSIX character class syntax
+X<character class>
 
     [:class:]
 
 is also available.  The available classes and their backslash
 equivalents (if available) are as follows:
+X<character class>
+X<alpha> X<alnum> X<ascii> X<blank> X<cntrl> X<digit> X<graph>
+X<lower> X<print> X<punct> X<space> X<upper> X<word> X<xdigit>
 
     alpha
     alnum
@@ -246,6 +272,7 @@ matches zero, one, any alphabetic character, and the percentage sign.
 
 The following equivalences to Unicode \p{} constructs and equivalent
 backslash character classes (if available), will hold:
+X<character class> X<\p> X<\p{}>
 
     [:...:]    \p{...}         backslash
 
@@ -276,6 +303,7 @@ The assumedly non-obviously named classes are:
 =over 4
 
 =item cntrl
+X<cntrl>
 
 Any control character.  Usually characters that don't produce output as
 such but instead control the terminal somehow: for example newline and
@@ -285,18 +313,22 @@ the ISO Latin character sets, and Unicode), as is the character with
 the ord() value of 127 (C<DEL>).
 
 =item graph
+X<graph>
 
 Any alphanumeric or punctuation (special) character.
 
 =item print
+X<print>
 
 Any alphanumeric or punctuation (special) character or the space character.
 
 =item punct
+X<punct>
 
 Any punctuation (special) character.
 
 =item xdigit
+X<xdigit>
 
 Any hexadecimal digit.  Though this may feel silly ([0-9A-Fa-f] would
 work just fine) it is included for completeness.
@@ -305,6 +337,7 @@ work just fine) it is included for completeness.
 
 You can negate the [::] character classes by prefixing the class name
 with a '^'. This is a Perl extension.  For example:
+X<character class, negation>
 
     POSIX      traditional Unicode
 
@@ -318,6 +351,10 @@ only supported within a character class.  The POSIX character classes
 use them will cause an error.
 
 Perl defines the following zero-width assertions:
+X<zero-width assertion> X<assertion> X<regex, zero-width assertion>
+X<regexp, zero-width assertion>
+X<regular expression, zero-width assertion>
+X<\b> X<\B> X<\A> X<\Z> X<\z> X<\G>
 
     \b Match a word boundary
     \B Match a non-(word boundary)
@@ -338,6 +375,7 @@ won't match multiple times when the C</m> modifier is used, while
 "^" and "$" will match at every internal line boundary.  To match
 the actual end of the string and not ignore an optional trailing
 newline, use C<\z>.
+X<\b> X<\A> X<\Z> X<\z> X</m>
 
 The C<\G> assertion can be used to chain global matches (using
 C<m//g>), as described in L<perlop/"Regexp Quote-Like Operators">.
@@ -350,6 +388,7 @@ supported when anchored to the start of the pattern; while it
 is permitted to use it elsewhere, as in C</(?<=\G..)./g>, some
 such uses (C</.\G/g>, for example) currently cause problems, and
 it is recommended that you avoid such usage for now.
+X<\G>
 
 The bracketing construct C<( ... )> creates capture buffers.  To
 refer to the digit'th buffer use \<digit> within the
@@ -358,6 +397,8 @@ match.  Outside the match use "$" instead of "\".  (The
 the match.  See the warning below about \1 vs $1 for details.)
 Referring back to another part of the match is called a
 I<backreference>.
+X<regex, capture buffer> X<regexp, capture buffer>
+X<regular expression, capture buffer> X<backreference>
 
 There is no limit to the number of captured substrings that you may
 use.  However Perl also uses \10, \11, etc. as aliases for \010,
@@ -393,11 +434,15 @@ after the matched string. And C<$^N> contains whatever was matched by
 the most-recently closed group (submatch). C<$^N> can be used in
 extended patterns (see below), for example to assign a submatch to a
 variable. 
+X<$+> X<$^N> X<$&> X<$`> X<$'>
 
 The numbered match variables ($1, $2, $3, etc.) and the related punctuation
 set (C<$+>, C<$&>, C<$`>, C<$'>, and C<$^N>) are all dynamically scoped
 until the end of the enclosing block or until the next successful
 match, whichever comes first.  (See L<perlsyn/"Compound Statements">.)
+X<$+> X<$^N> X<$&> X<$`> X<$'>
+X<$1> X<$2> X<$3> X<$4> X<$5> X<$6> X<$7> X<$8> X<$9>
+
 
 B<NOTE>: failed matches in Perl do not reset the match variables,
 which makes it easier to write code that tests for a series of more
@@ -416,6 +461,7 @@ 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.  As of 5.005, C<$&> is not so costly as the
 other two.
+X<$&> X<$`> X<$'>
 
 Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
 C<\w>, C<\n>.  Unlike some other regular expression languages, there
@@ -463,6 +509,7 @@ expressions, and 2) whenever you see one, you should stop and
 =over 10
 
 =item C<(?#text)>
+X<(?#)>
 
 A comment.  The text is ignored.  If the C</x> modifier enables
 whitespace formatting, a simple C<#> will suffice.  Note that Perl closes
@@ -470,6 +517,7 @@ the comment as soon as it sees a C<)>, so there is no way to put a literal
 C<)> in the comment.
 
 =item C<(?imsx-imsx)>
+X<(?)>
 
 One or more embedded pattern-match modifiers, to be turned on (or
 turned off, if preceded by C<->) for the remainder of the pattern or
@@ -497,6 +545,7 @@ case, assuming C<x> modifier, and no C<i> modifier outside this
 group.
 
 =item C<(?:pattern)>
+X<(?:)>
 
 =item C<(?imsx-imsx:pattern)>
 
@@ -522,11 +571,13 @@ is equivalent to the more verbose
     /(?:(?s-i)more.*than).*million/i
 
 =item C<(?=pattern)>
+X<(?=)> X<look-ahead, positive> X<lookahead, positive>
 
 A zero-width positive look-ahead assertion.  For example, C</\w+(?=\t)/>
 matches a word followed by a tab, without including the tab in C<$&>.
 
 =item C<(?!pattern)>
+X<(?!)> X<look-ahead, negative> X<lookahead, negative>
 
 A zero-width negative look-ahead assertion.  For example C</foo(?!bar)/>
 matches any occurrence of "foo" that isn't followed by "bar".  Note
@@ -546,18 +597,21 @@ Sometimes it's still easier just to say:
 For look-behind see below.
 
 =item C<(?<=pattern)>
+X<(?<=)> X<look-behind, positive> X<lookbehind, positive>
 
 A zero-width positive look-behind assertion.  For example, C</(?<=\t)\w+/>
 matches a word that follows a tab, without including the tab in C<$&>.
 Works only for fixed-width look-behind.
 
 =item C<(?<!pattern)>
+X<(?<!)> X<look-behind, negative> X<lookbehind, negative>
 
 A zero-width negative look-behind assertion.  For example C</(?<!bar)foo/>
 matches any occurrence of "foo" that does not follow "bar".  Works
 only for fixed-width look-behind.
 
 =item C<(?{ code })>
+X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression, code in>
 
 B<WARNING>: This extended regular expression feature is considered
 highly experimental, and may be changed or deleted without notice.
@@ -632,6 +686,9 @@ Better yet, use the carefully constrained evaluation within a Safe
 compartment.  See L<perlsec> for details about both these mechanisms.
 
 =item C<(??{ code })>
+X<(??{})>
+X<regex, postponed> X<regexp, postponed> X<regular expression, postponed>
+X<regex, recursive> X<regexp, recursive> X<regular expression, recursive>
 
 B<WARNING>: This extended regular expression feature is considered
 highly experimental, and may be changed or deleted without notice.
@@ -659,6 +716,7 @@ The following pattern matches a parenthesized group:
          }x;
 
 =item C<< (?>pattern) >>
+X<backtrack> X<backtracking>
 
 B<WARNING>: This extended regular expression feature is considered
 highly experimental, and may be changed or deleted without notice.
@@ -752,6 +810,7 @@ Which one you pick depends on which of these expressions better reflects
 the above specification of comments.
 
 =item C<(?(condition)yes-pattern|no-pattern)>
+X<(?()>
 
 =item C<(?(condition)yes-pattern)>
 
@@ -775,6 +834,7 @@ themselves.
 =back
 
 =head2 Backtracking
+X<backtrack> X<backtracking>
 
 NOTE: This section presents an abstract approximation of regular
 expression behavior.  For a more rigorous (and complicated) view of
@@ -981,6 +1041,7 @@ where side-effects of look-ahead I<might> have influenced the
 following match, see L<C<< (?>pattern) >>>.
 
 =head2 Version 8 Regular Expressions
+X<regular expression, version 8> X<regex, version 8> X<regexp, version 8>
 
 In case you're not familiar with the "regular" Version 8 regex
 routines, here are the pattern-matching rules not described above.
index 427fee7..96cd941 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<reference> X<pointer> X<data structure> X<structure> X<struct>
 
 perlref - Perl references and nested data structures
 
@@ -34,12 +35,15 @@ symbolic link in a Unix filesystem contains merely the name of a file.
 The C<*glob> 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.)
+X<reference, symbolic> X<reference, soft>
+X<symbolic reference> X<soft reference>
 
 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.
+X<reference, hard> X<hard reference>
 
 References are easy to use in Perl.  There is just one overriding
 principle: Perl does no implicit referencing or dereferencing.  When a
@@ -48,12 +52,14 @@ doesn't magically start being an array or hash or subroutine; you have to
 tell it explicitly to do so, by dereferencing it.
 
 =head2 Making References
+X<reference, creation> X<referencing>
 
 References can be created in several ways.
 
 =over 4
 
 =item 1.
+X<\> X<backslash>
 
 By using the backslash operator on a variable, subroutine, or value.
 (This works much like the & (address-of) operator in C.)  
@@ -75,6 +81,8 @@ But see the explanation of the C<*foo{THING}> syntax below.  However,
 you can still use type globs and globrefs as though they were IO handles.
 
 =item 2.
+X<array, anonymous> X<[> X<[]> X<square bracket>
+X<bracket, square> X<arrayref> X<array reference> X<reference, array>
 
 A reference to an anonymous array can be created using square
 brackets:
@@ -100,6 +108,8 @@ except that the key references are to copies (since the keys are just
 strings rather than full-fledged scalars).
 
 =item 3.
+X<hash, anonymous> X<{> X<{}> X<curly bracket>
+X<bracket, curly> X<brace> X<hashref> X<hash reference> X<reference, hash>
 
 A reference to an anonymous hash can be created using curly
 brackets:
@@ -140,6 +150,8 @@ The leading C<+{> and C<{;> always serve to disambiguate
 the expression to mean either the HASH reference, or the BLOCK.
 
 =item 4.
+X<subroutine, anonymous> X<subroutine, reference> X<reference, subroutine>
+X<scope, lexical> X<closure> X<lexical> X<lexical scope>
 
 A reference to an anonymous subroutine can be created by using
 C<sub> without a subname:
@@ -196,6 +208,7 @@ continue to work as they have always worked.  Closure is not something
 that most Perl programmers need trouble themselves about to begin with.
 
 =item 5.
+X<constructor> X<new>
 
 References are often returned by special subroutines called constructors.
 Perl objects are just references to a special type of object that happens to know
@@ -220,12 +233,14 @@ But don't have to be:
                             -borderwidth         => 2)
 
 =item 6.
+X<autovivification>
 
 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.
 
 =item 7.
+X<*foo{THING}> X<*>
 
 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
@@ -281,6 +296,7 @@ below, there's no risk of that happening.
 =back
 
 =head2 Using References
+X<reference, use> X<dereferencing> X<dereference>
 
 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
@@ -312,6 +328,7 @@ However, a "simple scalar" includes an identifier that itself uses method
     print $$$$refrefref;
 
 =item 2.
+X<${}> X<@{}> X<%{}>
 
 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
@@ -348,6 +365,7 @@ called %hashref, not dereferencing through $hashref to the hash
 it's presumably referencing.  That would be case 3.
 
 =item 3.
+X<autovivification> X<< -> >> X<arrow>
 
 Subroutine calls and lookups of individual array elements arise often
 enough that it gets cumbersome to use method 2.  As a form of
@@ -385,6 +403,7 @@ Well, okay, not entirely like C's arrays, actually.  C doesn't know how
 to grow its arrays on demand.  Perl does.
 
 =item 4.
+X<encapsulation>
 
 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
@@ -401,6 +420,7 @@ 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.
+X<reference, numeric context>
 
     if ($ref1 == $ref2) {  # cheap numeric compare of references
        print "refs 1 and 2 refer to the same thing\n";
@@ -411,6 +431,7 @@ including any package blessing as described in L<perlobj>, as well
 as the numeric address expressed in hex.  The ref() operator returns
 just the type of thing the reference is pointing to, without the
 address.  See L<perlfunc/ref> for details and examples of its use.
+X<reference, string context>
 
 The bless() operator may be used to associate the object a reference
 points to with a package functioning as an object class.  See L<perlobj>.
@@ -433,6 +454,8 @@ chicanery is also useful for arbitrary expressions:
     print "That yields @{[$n + 5]} widgets\n";
 
 =head2 Symbolic references
+X<reference, symbolic> X<reference, soft>
+X<symbolic reference> X<soft reference>
 
 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
@@ -536,11 +559,14 @@ But it will no longer warn you about using lowercase words, because the
 string is effectively quoted.
 
 =head2 Pseudo-hashes: Using an array as a hash
+X<pseudo-hash> X<pseudo hash> X<pseudohash>
 
 Pseudo-hashes have been removed from Perl.  The 'fields' pragma
 remains available.
 
 =head2 Function Templates
+X<scope, lexical> X<closure> X<lexical> X<lexical scope>
+X<subroutine, nested> X<sub, nested> X<subroutine, local> X<sub, local>
 
 As explained above, an anonymous function with access to the lexical
 variables visible when that function was compiled, creates a closure.  It
@@ -616,6 +642,7 @@ This has the interesting effect of creating a function local to another
 function, something not normally supported in Perl.
 
 =head1 WARNING
+X<reference, string context> X<reference, use as hash key>
 
 You may not (usefully) use a reference as the key to a hash.  It will be
 converted into a string:
index 519e24f..3eca0e9 100644 (file)
@@ -110,6 +110,7 @@ runs off the end without hitting an exit() or die() operator, an implicit
 C<exit(0)> is provided to indicate successful completion.
 
 =head2 #! and quoting on non-Unix systems
+X<hashbang> X<#!>
 
 Unix's #! technique can be simulated on other systems:
 
@@ -206,6 +207,7 @@ characters as control characters.
 There is no general solution to all of this.  It's just a mess.
 
 =head2 Location of Perl
+X<perl, location of interpreter>
 
 It may seem obvious to say, but Perl is useful only when users can
 easily find it.  When possible, it's good for both F</usr/bin/perl>
@@ -227,6 +229,7 @@ like this at the top of your program:
     use 5.005_54;
 
 =head2 Command Switches
+X<perl, command switches> X<command switches>
 
 As with all standard commands, a single-character switch may be
 clustered with the following switch, if any.
@@ -238,6 +241,7 @@ Switches include:
 =over 5
 
 =item B<-0>[I<octal/hexadecimal>]
+X<-0> X<$/>
 
 specifies the input record separator (C<$/>) as an octal or
 hexadecimal number.  If there are no digits, the null character is the
@@ -257,6 +261,7 @@ format: C<-0xHHH...>, where the C<H> are valid hexadecimal digits.
 consists of hexadecimal digits.)
 
 =item B<-A[I<module>][=I<assertions>]>
+X<-A>
 
 Activates the assertions given after the equal sign as a comma-separated
 list of assertion names or regular expressions. If no assertion name
@@ -269,6 +274,7 @@ its name between the switch and the equal sign.
 See L<assertions> and L<assertions::activate>.
 
 =item B<-a>
+X<-a> X<autosplit>
 
 turns on autosplit mode when used with a B<-n> or B<-p>.  An implicit
 split command to the @F array is done as the first thing inside the
@@ -286,6 +292,7 @@ is equivalent to
 An alternate delimiter may be specified using B<-F>.
 
 =item B<-C [I<number/list>]>
+X<-C>
 
 The C<-C> flag controls some Unicode of the Perl Unicode features.
 
@@ -341,6 +348,7 @@ This feature was practically unused, however, and the command line
 switch was therefore "recycled".)
 
 =item B<-c>
+X<-c>
 
 causes Perl to check the syntax of the program and then exit without
 executing it.  Actually, it I<will> execute C<BEGIN>, C<CHECK>, and
@@ -349,6 +357,7 @@ execution of your program.  C<INIT> and C<END> blocks, however, will
 be skipped.
 
 =item B<-d>
+X<-d> X<-dt>
 
 =item B<-dt>
 
@@ -357,6 +366,7 @@ If B<t> is specified, it indicates to the debugger that threads
 will be used in the code being debugged.
 
 =item B<-d:>I<foo[=bar,baz]>
+X<-d> X<-dt>
 
 =item B<-dt:>I<foo[=bar,baz]>
 
@@ -371,6 +381,7 @@ will be used in the code being debugged.
 See L<perldebug>.
 
 =item B<-D>I<letters>
+X<-D> X<DEBUGGING> X<-DDEBUGGING>
 
 =item B<-D>I<number>
 
@@ -430,6 +441,7 @@ you can't use Perl's B<-D> switch.  Instead do this
 See L<perldebug> for details and variations.
 
 =item B<-e> I<commandline>
+X<-e>
 
 may be used to enter one line of program.  If B<-e> is given, Perl
 will not look for a filename in the argument list.  Multiple B<-e>
@@ -437,6 +449,7 @@ commands may be given to build up a multi-line script.  Make sure
 to use semicolons where you would in a normal program.
 
 =item B<-f>
+X<-f>
 
 Disable executing F<$Config{siteperl}/sitecustomize.pl> at
 startup.
@@ -448,16 +461,19 @@ instance be used to add entries to the @INC array to make perl find
 modules in non-standard locations.
 
 =item B<-F>I<pattern>
+X<-F>
 
 specifies the pattern to split on if B<-a> is also in effect.  The
 pattern may be surrounded by C<//>, C<"">, or C<''>, otherwise it will be
 put in single quotes. You can't use literal whitespace in the pattern.
 
 =item B<-h>
+X<-h>
 
 prints a summary of the options.
 
 =item B<-i>[I<extension>]
+X<-i> X<in-place>
 
 specifies that files processed by the C<E<lt>E<gt>> construct are to be
 edited in-place.  It does this by renaming the input file, opening the
@@ -569,6 +585,7 @@ files are given on the command line.  In this case, no backup is made
 proceeds from STDIN to STDOUT as might be expected.
 
 =item B<-I>I<directory>
+X<-I> X<@INC>
 
 Directories specified by B<-I> are prepended to the search path for
 modules (C<@INC>), and also tells the C preprocessor where to search for
@@ -576,6 +593,7 @@ include files.  The C preprocessor is invoked with B<-P>; by default it
 searches /usr/include and /usr/lib/perl.
 
 =item B<-l>[I<octnum>]
+X<-l> X<$/> X<$\>
 
 enables automatic line-ending processing.  It has two separate
 effects.  First, it automatically chomps C<$/> (the input record
@@ -596,6 +614,7 @@ separator if the B<-l> switch is followed by a B<-0> switch:
 This sets C<$\> to newline and then sets C<$/> to the null character.
 
 =item B<-m>[B<->]I<module>
+X<-m> X<-M>
 
 =item B<-M>[B<->]I<module>
 
@@ -625,6 +644,7 @@ A consequence of this is that B<-MFoo=number> never does a version check
 could happen for example if Foo inherits from Exporter.)
 
 =item B<-n>
+X<-n>
 
 causes Perl to assume the following loop around your program, which
 makes it iterate over filename arguments somewhat like B<sed -n> or
@@ -653,6 +673,7 @@ C<BEGIN> and C<END> blocks may be used to capture control before or after
 the implicit program loop, just as in B<awk>.
 
 =item B<-p>
+X<-p>
 
 causes Perl to assume the following loop around your program, which
 makes it iterate over filename arguments somewhat like B<sed>:
@@ -675,6 +696,7 @@ C<BEGIN> and C<END> blocks may be used to capture control before or after
 the implicit loop, just as in B<awk>.
 
 =item B<-P>
+X<-P>
 
 B<NOTE: Use of -P is strongly discouraged because of its inherent
 problems, including poor portability.>
@@ -740,6 +762,7 @@ The C<-x> does not work with C<-P>.
 =back
 
 =item B<-s>
+X<-s>
 
 enables rudimentary switch parsing for switches on the command
 line after the program name but before any filename arguments (or before
@@ -757,6 +780,7 @@ with C<strict refs>.  Also, when using this option on a script with
 warnings enabled you may get a lot of spurious "used only once" warnings.
 
 =item B<-S>
+X<-S>
 
 makes Perl use the PATH environment variable to search for the
 program (unless the name of the program contains directory separators).
@@ -809,6 +833,7 @@ before being searched for on the PATH.  On Unix platforms, the
 program will be searched for strictly on the PATH.
 
 =item B<-t>
+X<-t>
 
 Like B<-T>, but taint checks will issue warnings rather than fatal
 errors.  These warnings can be controlled normally with C<no warnings
@@ -820,6 +845,7 @@ for real production code and for new secure code written from scratch
 always use the real B<-T>.
 
 =item B<-T>
+X<-T>
 
 forces "taint" checks to be turned on so you can test them.  Ordinarily
 these checks are done only when running setuid or setgid.  It's a
@@ -832,6 +858,7 @@ on the command line or in the #! line for systems which support
 that construct.
 
 =item B<-u>
+X<-u>
 
 This obsolete switch causes Perl to dump core after compiling your
 program.  You can then in theory take this core dump and turn it
@@ -848,6 +875,7 @@ generator backends to the compiler.  See L<B> and L<B::Bytecode>
 for details.
 
 =item B<-U>
+X<-U>
 
 allows Perl to do unsafe operations.  Currently the only "unsafe"
 operations are the unlinking of directories while running as superuser,
@@ -857,10 +885,12 @@ be used along with this option to actually I<generate> the
 taint-check warnings.
 
 =item B<-v>
+X<-v>
 
 prints the version and patchlevel of your perl executable.
 
 =item B<-V>
+X<-V>
 
 prints summary of the major perl configuration values and the current
 values of @INC.
@@ -906,6 +936,7 @@ below, the PERL_API params are returned in alphabetical order.
     building_on 'linux' '5' '1' '9' now
 
 =item B<-w>
+X<-w>
 
 prints warnings about dubious constructs, such as variable names
 that are mentioned only once and scalar variables that are used
@@ -923,16 +954,19 @@ facility is also available if you want to manipulate entire classes
 of warnings; see L<warnings> or L<perllexwarn>.
 
 =item B<-W>
+X<-W>
 
 Enables all warnings regardless of C<no warnings> or C<$^W>.
 See L<perllexwarn>.
 
 =item B<-X>
+X<-X>
 
 Disables all warnings regardless of C<use warnings> or C<$^W>.
 See L<perllexwarn>.
 
 =item B<-x>
+X<-x>
 
 =item B<-x> I<directory>
 
@@ -950,23 +984,28 @@ if desired).
 =back
 
 =head1 ENVIRONMENT
+X<perl, environment variables>
 
 =over 12
 
 =item HOME
+X<HOME>
 
 Used if chdir has no argument.
 
 =item LOGDIR
+X<LOGDIR>
 
 Used if chdir has no argument and HOME is not set.
 
 =item PATH
+X<PATH>
 
 Used in executing subprocesses, and in finding the program if B<-S> is
 used.
 
 =item PERL5LIB
+X<PERL5LIB>
 
 A list of directories in which to look for Perl library
 files before looking in the standard library and the current
@@ -983,6 +1022,7 @@ The program should instead say:
     use lib "/my/directory";
 
 =item PERL5OPT
+X<PERL5OPT>
 
 Command-line options (switches).  Switches in this variable are taken
 as if they were on every Perl command line.  Only the B<-[CDIMUdmtwA]>
@@ -992,6 +1032,7 @@ variable is ignored.  If PERL5OPT begins with B<-T>, tainting will be
 enabled, and any subsequent options ignored.
 
 =item PERLIO
+X<PERLIO>
 
 A space (or colon) separated list of PerlIO layers. If perl is built
 to use PerlIO system for IO (the default) these layers effect perl's IO.
@@ -1014,12 +1055,14 @@ variable are briefly summarised below. For more details see L<PerlIO>.
 =over 8
 
 =item :bytes
+X<:bytes>
 
 A pseudolayer that turns I<off> the C<:utf8> flag for the layer below.
 Unlikely to be useful on its own in the global PERLIO environment variable.
 You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
 
 =item :crlf
+X<:crlf>
 
 A layer which does CRLF to "\n" translation distinguishing "text" and
 "binary" files in the manner of MS-DOS and similar operating systems.
@@ -1027,23 +1070,27 @@ A layer which does CRLF to "\n" translation distinguishing "text" and
 as being an end-of-file marker.)
 
 =item :mmap
+X<:mmap>
 
 A layer which implements "reading" of files by using C<mmap()> to
 make (whole) file appear in the process's address space, and then
 using that as PerlIO's "buffer".
 
 =item :perlio
+X<: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 C<:unix>).
 
 =item :pop
+X<:pop>
 
 An experimental pseudolayer that removes the topmost layer.
 Use with the same care as is reserved for nitroglycerin.
 
 =item :raw
+X<:raw>
 
 A pseudolayer that manipulates other layers.  Applying the C<:raw>
 layer is equivalent to calling C<binmode($fh)>.  It makes the stream
@@ -1055,6 +1102,7 @@ just the inverse of C<:crlf> - other layers which would affect the
 binary nature of the stream are also removed or disabled.
 
 =item :stdio
+X<:stdio>
 
 This layer provides PerlIO interface by wrapping system's ANSI C "stdio"
 library calls. The layer provides both buffering and IO.
@@ -1063,10 +1111,12 @@ is platforms normal behaviour. You will need a C<:crlf> layer above it
 to do that.
 
 =item :unix
+X<:unix>
 
 Low level layer which calls C<read>, C<write> and C<lseek> etc.
 
 =item :utf8
+X<:utf8>
 
 A pseudolayer that turns on a flag on the layer below to tell perl
 that output should be in utf8 and that input should be regarded as
@@ -1075,6 +1125,7 @@ variable to make UTF-8 the default. (To turn off that behaviour
 use C<:bytes> layer.)
 
 =item :win32
+X<:win32>
 
 On Win32 platforms this I<experimental> layer uses native "handle" IO
 rather than unix-like numeric file descriptor layer. Known to be
@@ -1102,6 +1153,7 @@ C<win32> layer which is expected to be enhanced and should eventually be
 the default under Win32.
 
 =item PERLIO_DEBUG
+X<PERLIO_DEBUG>
 
 If set to the name of a file or device then certain operations of PerlIO
 sub-system will be logged to that file (opened as append). Typical uses
@@ -1118,23 +1170,27 @@ This functionality is disabled for setuid scripts and for scripts run
 with B<-T>.
 
 =item PERLLIB
+X<PERLLIB>
 
 A list of directories in which to look for Perl library
 files before looking in the standard library and the current directory.
 If PERL5LIB is defined, PERLLIB is not used.
 
 =item PERL5DB
+X<PERL5DB>
 
 The command used to load the debugger code.  The default is:
 
        BEGIN { require 'perl5db.pl' }
 
 =item PERL5DB_THREADED
+X<PERL5DB_THREADED>
 
 If set to a true value, indicates to the debugger that the code being
 debugged uses threads.
 
 =item PERL5SHELL (specific to the Win32 port)
+X<PERL5SHELL>
 
 May be set to an alternative shell that perl must use internally for
 executing "backtick" commands or system().  Default is C<cmd.exe /x/d/c>
@@ -1150,6 +1206,7 @@ interfere with the proper functioning of other programs (which usually
 look in COMSPEC to find a shell fit for interactive use).
 
 =item PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
+X<PERL_ALLOW_NON_IFS_LSP>
 
 Set to 1 to allow the use of non-IFS compatible LSP's.
 Perl normally searches for an IFS-compatible LSP because this is required
@@ -1164,6 +1221,7 @@ Guardian's LSP actually plays some other games which allow applications
 requiring IFS compatibility to work).
 
 =item PERL_DEBUG_MSTATS
+X<PERL_DEBUG_MSTATS>
 
 Relevant only if perl is compiled with the malloc included with the perl
 distribution (that is, if C<perl -V:d_mymalloc> is 'define').
@@ -1172,12 +1230,14 @@ to an integer greater than one, also causes memory statistics to be dumped
 after compilation.
 
 =item PERL_DESTRUCT_LEVEL
+X<PERL_DESTRUCT_LEVEL>
 
 Relevant only if your perl executable was built with B<-DDEBUGGING>,
 this controls the behavior of global destruction of objects and other
 references.  See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
 
 =item PERL_DL_NONLAZY
+X<PERL_DL_NONLAZY>
 
 Set to one to have perl resolve B<all> undefined symbols when it loads
 a dynamic library.  The default behaviour is to resolve symbols when
@@ -1186,11 +1246,13 @@ extensions as it ensures that you get an error on misspelled function
 names even if the test suite doesn't call it.
 
 =item PERL_ENCODING
+X<PERL_ENCODING>
 
 If using the C<encoding> pragma without an explicit encoding name, the
 PERL_ENCODING environment variable is consulted for an encoding name.
 
 =item PERL_HASH_SEED
+X<PERL_HASH_SEED>
 
 (Since Perl 5.8.1.)  Used to randomise Perl's internal hash function.
 To emulate the pre-5.8.1 behaviour, set to an integer (zero means
@@ -1216,6 +1278,7 @@ See L<perlsec/"Algorithmic Complexity Attacks"> and
 L</PERL_HASH_SEED_DEBUG> for more information.
 
 =item PERL_HASH_SEED_DEBUG
+X<PERL_HASH_SEED_DEBUG>
 
 (Since Perl 5.8.1.)  Set to one to display (to STDERR) the value of
 the hash seed at the beginning of execution.  This, combined with
@@ -1229,6 +1292,7 @@ B<Do not disclose the hash seed> to people who don't need to know it.
 See also hash_seed() of L<Hash::Util>.
 
 =item PERL_ROOT (specific to the VMS port)
+X<PERL_ROOT>
 
 A translation concealed rooted logical name that contains perl and the
 logical device for the @INC path on VMS only.  Other logical names that
@@ -1237,6 +1301,7 @@ SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in
 L<perlvms> and in F<README.vms> in the Perl source distribution.
 
 =item PERL_SIGNALS
+X<PERL_SIGNALS>
 
 In Perls 5.8.1 and later.  If set to C<unsafe> the pre-Perl-5.8.0
 signals behaviour (immediate but unsafe) is restored.  If set to
@@ -1244,6 +1309,7 @@ C<safe> the safe (or deferred) signals are used.
 See L<perlipc/"Deferred Signals (Safe Signals)">.
 
 =item PERL_UNICODE
+X<PERL_UNICODE>
 
 Equivalent to the B<-C> command-line switch.  Note that this is not
 a boolean variable-- setting this to C<"1"> is not the right way to
@@ -1253,6 +1319,7 @@ your shell before starting Perl).  See the description of the C<-C>
 switch for more information.
 
 =item SYS$LOGIN (specific to the VMS port)
+X<SYS$LOGIN>
 
 Used if chdir has no argument and HOME and LOGDIR are not set.
 
index 0839f1b..fbf27cd 100644 (file)
@@ -1,10 +1,12 @@
 =head1 NAME
+X<subroutine> X<function>
 
 perlsub - Perl subroutines
 
 =head1 SYNOPSIS
 
 To declare subroutines:
+X<subroutine, declaration> X<sub>
 
     sub NAME;                    # A "forward" declaration.
     sub NAME(PROTO);             #  ditto, but with prototypes
@@ -17,6 +19,7 @@ To declare subroutines:
     sub NAME(PROTO) : ATTRS BLOCK #  with prototypes and attributes
 
 To define an anonymous subroutine at runtime:
+X<subroutine, anonymous>
 
     $subref = sub BLOCK;                # no proto
     $subref = sub (PROTO) BLOCK;        # with proto
@@ -24,10 +27,12 @@ To define an anonymous subroutine at runtime:
     $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
 
 To import subroutines:
+X<import>
 
     use MODULE qw(NAME1 NAME2 NAME3);
 
 To call subroutines:
+X<subroutine, call> X<call>
 
     NAME(LIST);           # & is optional with parentheses.
     NAME LIST;    # Parentheses optional if predeclared/imported.
@@ -52,6 +57,7 @@ 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.)
+X<subroutine, parameter> X<parameter>
 
 Any arguments passed in show up in the array C<@_>.  Therefore, if
 you called a function with two arguments, those would be stored in
@@ -65,6 +71,7 @@ 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 C<@_> removes that aliasing, and does
 not update any arguments.
+X<subroutine, argument> X<argument> X<@_>
 
 The return value of a subroutine is the value of the last expression
 evaluated by that sub, or the empty list in the case of an empty sub.
@@ -76,6 +83,7 @@ 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.
+X<subroutine, return value> X<return value> X<return>
 
 Perl does not have named formal parameters.  In practice all you
 do is assign to a C<my()> list of these.  Variables that aren't
@@ -84,6 +92,7 @@ on creating private variables, see L<"Private Variables via my()">
 and L<"Temporary Values via local()">.  To create protected
 environments for a set of functions in a separate package (and
 probably a separate file), see L<perlmod/"Packages">.
+X<formal parameter> X<parameter, formal>
 
 Example:
 
@@ -130,6 +139,7 @@ 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 C<@_> and change
 its caller's values.
+X<call-by-reference> X<call-by-value>
 
     upcase_in($v1, $v2);  # this changes $v1 and $v2
     sub upcase_in {
@@ -139,6 +149,7 @@ its caller's values.
 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:
+X<call-by-reference> X<call-by-value>
 
     upcase_in("frederick");
 
@@ -182,12 +193,14 @@ want to do an indirect subroutine call with a subroutine name or
 reference using the C<&$subref()> or C<&{$subref}()> constructs,
 although the C<< $subref->() >> notation solves that problem.
 See L<perlref> for more about all that.
+X<&>
 
 Subroutines may be called recursively.  If a subroutine is called
 using the C<&> form, the argument list is optional, and if omitted,
 no C<@_> array is set up for the subroutine: the C<@_> array at the
 time of the call is visible to subroutine instead.  This is an
 efficiency mechanism that new users may wish to avoid.
+X<recursion>
 
     &foo(1,2,3);       # pass three arguments
     foo(1,2,3);                # the same
@@ -202,6 +215,7 @@ Not only does the C<&> 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 L<Prototypes> below.
+X<&>
 
 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
@@ -216,6 +230,8 @@ than one in a package, and which you can B<not> call explicitly.  See
 L<perlmod/"BEGIN, CHECK, INIT and END">
 
 =head2 Private Variables via my()
+X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>
+X<lexical scope> X<attributes, my>
 
 Synopsis:
 
@@ -243,6 +259,7 @@ variables declared with C<my> 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.
+X<local>
 
 This doesn't mean that a C<my> variable declared in a statically
 enclosing lexical scope would be invisible.  Only dynamic scopes
@@ -256,6 +273,7 @@ occurred at the same scope, presumably file scope.
 An C<eval()>, 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 C<eval()> itself.  See L<perlref>.
+X<eval, scope of>
 
 The parameter list to my() may be assigned to if desired, which allows you
 to initialize your variables.  (If no initializer is given for a
@@ -338,6 +356,7 @@ in the manner of C<local>.  However, if the index variable is
 prefixed with the keyword C<my>, or if there is already a lexical
 by that name in scope, then a new lexical is created instead.  Thus
 in the loop
+X<foreach> X<for>
 
     for my $i (1, 2, 3) {
         some_function();
@@ -345,6 +364,7 @@ in the loop
 
 the scope of $i extends to the end of the loop, but not beyond it,
 rendering the value of $i inaccessible within C<some_function()>.
+X<foreach> X<for>
 
 Some users may wish to encourage the use of lexically scoped variables.
 As an aid to catching implicit uses to package variables,
@@ -409,6 +429,7 @@ L<perlref/"Function Templates"> for something of a work-around to
 this.
 
 =head2 Persistent Private Variables
+X<static> X<variable, persistent> X<variable, static> X<closure>
 
 Just because a lexical variable is lexically (also called statically)
 scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that
@@ -465,6 +486,8 @@ from outside that file.  This strategy is sometimes used in modules
 to create private variables that the whole module can see.
 
 =head2 Temporary Values via local()
+X<local> X<scope, dynamic> X<dynamic scope> X<variable, local>
+X<variable, temporary>
 
 B<WARNING>: In general, you should be using C<my> instead of C<local>, because
 it's faster and safer.  Exceptions to this include the global punctuation
@@ -520,6 +543,7 @@ through a loop.  Consequently, it's more efficient to localize your
 variables outside the loop.
 
 =head3 Grammatical note on local()
+X<local, context>
 
 A C<local> is simply a modifier on an lvalue expression.  When you assign to
 a C<local>ized variable, the C<local> doesn't change whether its list is viewed
@@ -535,6 +559,7 @@ both supply a list context to the right-hand side, while
 supplies a scalar context.
 
 =head3 Localization of special variables
+X<local, special variable>
 
 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
@@ -570,8 +595,10 @@ code that relies on any particular behaviour of localising tied arrays
 or hashes (localising individual elements is still okay).
 See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more
 details.
+X<local, tie>
 
 =head3 Localization of globs
+X<local, glob> X<glob>
 
 The construct
 
@@ -593,6 +620,7 @@ As of perl 5.9.1, you can also use the lexical form of C<$_> (declaring it
 with C<my $_>), which avoids completely this problem.
 
 =head3 Localization of elements of composite types
+X<local, composite type element> X<local, array element> X<local, hash element>
 
 It's also worth taking a moment to explain what happens when you
 C<local>ize a member of a composite type (i.e. an array or hash element).
@@ -635,6 +663,7 @@ The behavior of local() on non-existent members of composite
 types is subject to change in future.
 
 =head2 Lvalue subroutines
+X<lvalue> X<subroutine, lvalue>
 
 B<WARNING>: Lvalue subroutines are still experimental and the
 implementation may change in future versions of Perl.
@@ -704,6 +733,7 @@ subroutine never gets that chance.  Consider;
 =back
 
 =head2 Passing Symbol Table Entries (typeglobs)
+X<typeglob> X<*>
 
 B<WARNING>: The mechanism described in this section was originally
 the only way to simulate pass-by-reference in older versions of
@@ -746,6 +776,7 @@ the individual arrays.  For more on typeglobs, see
 L<perldata/"Typeglobs and Filehandles">.
 
 =head2 When to Still Use local()
+X<local> X<variable, local>
 
 Despite the existence of C<my>, there are still three places where the
 C<local> operator still shines.  In fact, in these three places, you
@@ -823,6 +854,7 @@ this operation could on occasion misbehave.
 =back
 
 =head2 Pass by Reference
+X<pass by reference> X<pass-by-reference> X<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
@@ -936,6 +968,7 @@ Notice to pass back just the bare *FH, not its reference.
     }
 
 =head2 Prototypes
+X<prototype> X<subroutine, prototype>
 
 Perl supports a very limited kind of compile-time argument checking
 using function prototyping.  If you declare
@@ -1036,6 +1069,7 @@ without a prototype.
 
 The interesting thing about C<&> is that you can generate new syntax with it,
 provided it's in the initial position:
+X<&>
 
     sub try (&@) {
        my($try,$catch) = @_;
@@ -1060,6 +1094,7 @@ scoped, those anonymous subroutines can act like closures... (Gee,
 is this sounding a little Lispish?  (Never mind.))))
 
 And here's a reimplementation of the Perl C<grep> operator:
+X<grep>
 
     sub mygrep (&@) {
        my $code = shift;
@@ -1113,6 +1148,7 @@ This is all very powerful, of course, and should be used only in moderation
 to make the world a better place.
 
 =head2 Constant Functions
+X<constant>
 
 Functions with a prototype of C<()> are potential candidates for
 inlining.  If the result after optimization and constant folding
@@ -1168,6 +1204,7 @@ inlining mechanism in some other way, such as
     }
 
 =head2 Overriding Built-in Functions
+X<built-in> X<override> X<CORE> X<CORE::GLOBAL>
 
 Many built-in functions may be overridden, though this should be tried
 only occasionally and for good reason.  Typically this might be
@@ -1290,6 +1327,7 @@ the equivalent I/O operator C<< <FILEHANDLE> >>.
 Finally, some built-ins (e.g. C<exists> or C<grep>) can't be overridden.
 
 =head2 Autoloading
+X<autoloading> X<AUTOLOAD>
 
 If you call a subroutine that is undefined, you would ordinarily
 get an immediate, fatal error complaining that the subroutine doesn't
@@ -1341,6 +1379,7 @@ SelfLoader modules in L<SelfLoader>, and the document on adding C
 functions to Perl code in L<perlxs>.
 
 =head2 Subroutine Attributes
+X<attribute> X<subroutine, attribute> X<attrs>
 
 A subroutine declaration or definition may have a list of attributes
 associated with it.  If such an attribute list is present, it is
index 5d25a77..c819b94 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<syntax>
 
 perlsyn - Perl syntax
 
@@ -27,6 +28,7 @@ you will see familiar pieces in Perl.  They often work the same, but
 see L<perltrap> for information about how they differ.
 
 =head2 Declarations
+X<declaration> X<undef> X<undefined> X<uninitialized>
 
 The only things you need to declare in Perl are report formats and
 subroutines (and sometimes not even subroutines).  A variable holds
@@ -63,6 +65,7 @@ as the my if you expect to be able to access those private variables.
 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 C<sub name>, thus:
+X<subroutine, declaration>
 
     sub myname;
     $me = myname $0            or die "can't get myname";
@@ -84,12 +87,14 @@ statements as if it were an ordinary statement.  That means it actually
 has both compile-time and run-time effects.
 
 =head2 Comments
+X<comment> X<#>
 
 Text from a C<"#"> character until the end of the line is a comment,
 and is ignored.  Exceptions include C<"#"> inside a string or regular
 expression.
 
 =head2 Simple Statements
+X<statement> X<semicolon> X<expression> X<;>
 
 The only kind of simple statement is an expression evaluated for its
 side effects.  Every simple statement must be terminated with a
@@ -102,6 +107,7 @@ TERMs in an expression), and thus need an explicit termination if used
 as the last item in a statement.
 
 =head2 Truth and Falsehood
+X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
 
 The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and
 C<undef> are all false in a boolean context. All other values are true.
@@ -110,6 +116,8 @@ When evaluated as a string it is treated as C<''>, but as a number, it
 is treated as 0.
 
 =head2 Statement Modifiers
+X<statement modifier> X<modifier> X<if> X<unless> X<while>
+X<until> X<foreach> X<for>
 
 Any simple statement may optionally be followed by a I<SINGLE> modifier,
 just before the terminating semicolon (or block ending).  The possible
@@ -160,6 +168,7 @@ later will I<NOT> work in this construct, because modifiers don't take
 loop labels.  Sorry.  You can always put another block inside of it
 (for C<next>) or around it (for C<last>) to do that sort of thing.
 For C<next>, just double the braces:
+X<next> X<last> X<redo>
 
     do {{
        next if $x == $y;
@@ -167,6 +176,7 @@ For C<next>, just double the braces:
     }} until $x++ > $z;
 
 For C<last>, you have to be more elaborate:
+X<last>
 
     LOOP: { 
            do {
@@ -181,8 +191,11 @@ B<undefined>.  The value of the C<my> variable may be C<undef>, 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.
+X<my>
 
 =head2 Compound Statements
+X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
+X<{> X<}> X<if> X<unless> X<while> X<until> X<foreach> X<for> X<continue>
 
 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
@@ -242,6 +255,7 @@ increment a loop variable, even when the loop has been continued via
 the C<next> statement.
 
 =head2 Loop Control
+X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
 
 The C<next> command starts the next iteration of the loop:
 
@@ -323,6 +337,7 @@ The form C<while/if BLOCK BLOCK>, available in Perl 4, is no longer
 available.   Replace any occurrence of C<if BLOCK> by C<if (do BLOCK)>.
 
 =head2 For Loops
+X<for> X<foreach>
 
 Perl's C-style C<for> loop works like the corresponding C<while> loop;
 that means that this:
@@ -344,12 +359,14 @@ There is one minor difference: if variables are declared with C<my>
 in the initialization section of the C<for>, the lexical scope of
 those variables is exactly the C<for> loop (the body of the loop
 and the control sections).
+X<my>
 
 Besides the normal array index looping, C<for> 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.
+X<eof> X<end-of-file> X<end of file>
 
     $on_a_tty = -t STDIN && -t STDOUT;
     sub prompt { print "yes? " if $on_a_tty }
@@ -360,12 +377,14 @@ hang.
 Using C<readline> (or the operator form, C<< <EXPR> >>) as the
 conditional of a C<for> loop is shorthand for the following.  This
 behaviour is the same as a C<while> loop conditional.
+X<readline> X<< <> >>
 
     for ( prompt(); defined( $_ = <STDIN> ); prompt() ) {
         # do something
     }
 
 =head2 Foreach Loops
+X<for> X<foreach>
 
 The C<foreach> loop iterates over a normal list value and sets the
 variable VAR to be each element of the list in turn.  If the variable
@@ -376,21 +395,25 @@ the loop.  If the variable was previously declared with C<my>, it uses
 that variable instead of the global one, but it's still localized to
 the loop.  This implicit localisation occurs I<only> in a C<foreach>
 loop.
+X<my> X<local>
 
 The C<foreach> keyword is actually a synonym for the C<for> keyword, so
 you can use C<foreach> for readability or C<for> for brevity.  (Or because
 the Bourne shell is more familiar to you than I<csh>, so writing C<for>
 comes more naturally.)  If VAR is omitted, C<$_> is set to each value.
+X<$_>
 
 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 C<foreach> loop index variable is an implicit alias for each item
 in the list that you're looping over.
+X<alias>
 
 If any part of LIST is an array, C<foreach> will get very confused if
 you add or remove elements within the loop body, for example with
 C<splice>.   So don't do that.
+X<splice>
 
 C<foreach> probably won't do what you expect if VAR is a tied or other
 special variable.   Don't do that either.
@@ -444,6 +467,7 @@ Perl executes a C<foreach> statement more rapidly than it would the
 equivalent C<for> loop.
 
 =head2 Basic BLOCKs and Switch Statements
+X<switch> X<block> X<case>
 
 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
@@ -591,6 +615,7 @@ You might also consider writing a hash of subroutine references
 instead of synthesizing a C<switch> statement.
 
 =head2 Goto
+X<goto>
 
 Although not for the faint of heart, Perl does support a C<goto>
 statement.  There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
@@ -626,6 +651,7 @@ resorting to a C<goto>.  For certain applications, the catch and throw pair of
 C<eval{}> and die() for exception processing can also be a prudent approach.
 
 =head2 PODs: Embedded Documentation
+X<POD> X<documentation>
 
 Perl has a mechanism for intermixing documentation with source code.
 While it's expecting the beginning of a new statement, if the compiler
@@ -673,6 +699,7 @@ One may also use pod directives to quickly comment out a section
 of code.
 
 =head2 Plain Old Comments (Not!)
+X<comment> X<line> X<#> X<preprocessor> X<eval>
 
 Perl can process line directives, much like the C preprocessor.  Using
 this, one can control Perl's idea of filenames and line numbers in
index b643576..b4c2baf 100644 (file)
@@ -1,4 +1,5 @@
 =head1 NAME
+X<tie>
 
 perltie - how to hide an object class in a simple variable
 
@@ -46,6 +47,7 @@ Unlike dbmopen(), the tie() function will not C<use> or C<require> a module
 for you--you need to do that explicitly yourself.
 
 =head2 Tying Scalars
+X<scalar, tying>
 
 A class implementing a tied scalar should define the following methods:
 TIESCALAR, FETCH, STORE, and possibly UNTIE and/or DESTROY.
@@ -74,6 +76,7 @@ calls.  Here's the preamble of the class.
 =over 4
 
 =item TIESCALAR classname, LIST
+X<TIESCALAR>
 
 This is the constructor for the class.  That means it is
 expected to return a blessed reference to a new scalar
@@ -102,6 +105,7 @@ other classes may well not wish to be so forgiving.  It checks the global
 variable C<$^W> to see whether to emit a bit of noise anyway.
 
 =item FETCH this
+X<FETCH>
 
 This method will be triggered every time the tied variable is accessed
 (read).  It takes no arguments beyond its self reference, which is the
@@ -126,6 +130,7 @@ fails--there's no place for us to return an error otherwise, and it's
 probably the right thing to do.
 
 =item STORE this, value
+X<STORE>
 
 This method will be triggered every time the tied variable is set
 (assigned).  Beyond its self reference, it also expects one (and only one)
@@ -159,12 +164,14 @@ assigned value is implemented with FETCH.
     }
 
 =item UNTIE this
+X<UNTIE>
 
 This method will be triggered when the C<untie> occurs. This can be useful
 if the class needs to know when no further calls will be made. (Except DESTROY
 of course.) See L<The C<untie> Gotcha> below for more details.
 
 =item DESTROY this
+X<DESTROY>
 
 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
@@ -185,6 +192,7 @@ of completeness, robustness, and general aesthetics.  Simpler
 TIESCALAR classes are certainly possible.
 
 =head2 Tying Arrays
+X<array, tying>
 
 A class implementing a tied ordinary array should define the following
 methods: TIEARRAY, FETCH, STORE, FETCHSIZE, STORESIZE and perhaps UNTIE and/or DESTROY.
@@ -220,6 +228,7 @@ The preamble code for the class is as follows:
 =over 4
 
 =item TIEARRAY classname, LIST
+X<TIEARRAY>
 
 This is the constructor for the class.  That means it is expected to
 return a blessed reference through which the new array (probably an
@@ -246,6 +255,7 @@ This just goes to show you that you should respect an object's privacy.
     }
 
 =item FETCH this, index
+X<FETCH>
 
 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
@@ -270,6 +280,7 @@ several tied types, in practice this becomes cumbersome, and it's easiest
 to keep them at simply one tie type per class.
 
 =item STORE this, index, value
+X<STORE>
 
 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
@@ -294,6 +305,7 @@ spaces so we have a little more work to do here:
 Negative indexes are treated the same as with FETCH.
 
 =item FETCHSIZE this
+X<FETCHSIZE>
 
 Returns the total number of items in the tied array associated with
 object I<this>. (Equivalent to C<scalar(@array)>).  For example:
@@ -304,6 +316,7 @@ object I<this>. (Equivalent to C<scalar(@array)>).  For example:
     }
 
 =item STORESIZE this, count
+X<STORESIZE>
 
 Sets the total number of items in the tied array associated with
 object I<this> to be I<count>. If this makes the array larger then
@@ -329,6 +342,7 @@ C<$self-E<gt>{ELEMSIZE}> number of spaces.  Observe:
     }
 
 =item EXTEND this, count
+X<EXTEND>
 
 Informative call that array is likely to grow to have I<count> entries.
 Can be used to optimize allocation. This method need do nothing.
@@ -344,6 +358,7 @@ as needed:
     }
 
 =item EXISTS this, key
+X<EXISTS>
 
 Verify that the element at index I<key> exists in the tied array I<this>.
 
@@ -359,6 +374,7 @@ C<$self-E<gt>{ELEMSIZE}> spaces only, it does not exist:
     }
 
 =item DELETE this, key
+X<DELETE>
 
 Delete the element at index I<key> from the tied array I<this>.
 
@@ -371,6 +387,7 @@ In our example, a deleted item is C<$self-E<gt>{ELEMSIZE}> spaces:
     }
 
 =item CLEAR this
+X<CLEAR>
 
 Clear (remove, delete, ...) all values from the tied array associated with
 object I<this>.  For example:
@@ -381,6 +398,7 @@ object I<this>.  For example:
     }
 
 =item PUSH this, LIST 
+X<PUSH>
 
 Append elements of I<LIST> to the array.  For example:
 
@@ -393,6 +411,7 @@ Append elements of I<LIST> to the array.  For example:
     }   
 
 =item POP this
+X<POP>
 
 Remove last element of the array and return it.  For example:
 
@@ -402,6 +421,7 @@ Remove last element of the array and return it.  For example:
     }
 
 =item SHIFT this
+X<SHIFT>
 
 Remove the first element of the array (shifting other elements down)
 and return it.  For example:
@@ -412,6 +432,7 @@ and return it.  For example:
     }
 
 =item UNSHIFT this, LIST 
+X<UNSHIFT>
 
 Insert LIST elements at the beginning of the array, moving existing elements
 up to make room.  For example:
@@ -427,6 +448,7 @@ up to make room.  For example:
     }
 
 =item SPLICE this, offset, length, LIST
+X<SPLICE>
 
 Perform the equivalent of C<splice> on the array. 
 
@@ -454,10 +476,12 @@ In our example, we'll use a little shortcut if there is a I<LIST>:
     }
 
 =item UNTIE this
+X<UNTIE>
 
 Will be called when C<untie> happens. (See L<The C<untie> Gotcha> below.)
 
 =item DESTROY this
+X<DESTROY>
 
 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
@@ -467,6 +491,7 @@ just leave it out.
 =back
 
 =head2 Tying Hashes
+X<hash, tying>
 
 Hashes were the first Perl data type to be tied (see dbmopen()).  A class
 implementing a tied hash should define the following methods: TIEHASH is
@@ -552,6 +577,7 @@ Here are the methods for the DotFiles tied hash.
 =over 4
 
 =item TIEHASH classname, LIST
+X<TIEHASH>
 
 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
@@ -592,6 +618,7 @@ in question.  Otherwise, because we didn't chdir() there, it would
 have been testing the wrong file.
 
 =item FETCH this, key
+X<FETCH>
 
 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
@@ -624,6 +651,7 @@ more efficient).  Of course, because dot files are a Unixy concept, we're
 not that concerned.
 
 =item STORE this, key, value
+X<STORE>
 
 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
@@ -671,6 +699,7 @@ The clobber method is simply:
     }
 
 =item DELETE this, key
+X<DELETE>
 
 This method is triggered when we remove an element from the hash,
 typically by using the delete() function.  Again, we'll
@@ -697,6 +726,7 @@ In this example, we have chosen instead to return a value which tells
 the caller whether the file was successfully deleted.
 
 =item CLEAR this
+X<CLEAR>
 
 This method is triggered when the whole hash is to be cleared, usually by
 assigning the empty list to it.
@@ -717,6 +747,7 @@ dangerous thing that they'll have to set CLOBBER to something higher than
     }
 
 =item EXISTS this, key
+X<EXISTS>
 
 This method is triggered when the user uses the exists() function
 on a particular hash.  In our example, we'll look at the C<{LIST}>
@@ -730,6 +761,7 @@ hash element for this:
     }
 
 =item FIRSTKEY this
+X<FIRSTKEY>
 
 This method will be triggered when the user is going
 to iterate through the hash, such as via a keys() or each()
@@ -743,6 +775,7 @@ call.
     }
 
 =item NEXTKEY this, lastkey
+X<NEXTKEY>
 
 This method gets triggered during a keys() or each() iteration.  It has a
 second argument which is the last key that had been accessed.  This is
@@ -759,6 +792,7 @@ thing, but we'll have to go through the LIST field indirectly.
     }
 
 =item SCALAR this
+X<SCALAR>
 
 This is called when the hash is evaluated in scalar context. In order
 to mimic the behaviour of untied hashes, this method should return a
@@ -784,10 +818,12 @@ referenced by C<$self-E<gt>{LIST}>:
     }
 
 =item UNTIE this
+X<UNTIE>
 
 This is called when C<untie> occurs.  See L<The C<untie> Gotcha> below.
 
 =item DESTROY this
+X<DESTROY>
 
 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
@@ -812,6 +848,7 @@ each() function to iterate over such.  Example:
     untie(%HIST);
 
 =head2 Tying FileHandles
+X<filehandle, tying>
 
 This is partially implemented now.
 
@@ -839,6 +876,7 @@ In our example we're going to create a shouting handle.
 =over 4
 
 =item TIEHANDLE classname, LIST
+X<TIEHANDLE>
 
 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
@@ -847,6 +885,7 @@ hold some internal information.
     sub TIEHANDLE { print "<shout>\n"; my $i; bless \$i, shift }
 
 =item WRITE this, LIST
+X<WRITE>
 
 This method will be called when the handle is written to via the
 C<syswrite> function.
@@ -858,6 +897,7 @@ C<syswrite> function.
     }
 
 =item PRINT this, LIST
+X<PRINT>
 
 This method will be triggered every time the tied handle is printed to
 with the C<print()> function.
@@ -867,6 +907,7 @@ the print function.
     sub PRINT { $r = shift; $$r++; print join($,,map(uc($_),@_)),$\ }
 
 =item PRINTF this, LIST
+X<PRINTF>
 
 This method will be triggered every time the tied handle is printed to
 with the C<printf()> function.
@@ -880,6 +921,7 @@ passed to the printf function.
     }
 
 =item READ this, LIST
+X<READ>
 
 This method will be called when the handle is read from via the C<read>
 or C<sysread> functions.
@@ -894,6 +936,7 @@ or C<sysread> functions.
     }
 
 =item READLINE this
+X<READLINE>
 
 This method will be called when the handle is read from via <HANDLE>.
 The method should return undef when there is no more data.
@@ -901,12 +944,14 @@ The method should return undef when there is no more data.
     sub READLINE { $r = shift; "READLINE called $$r times\n"; }
 
 =item GETC this
+X<GETC>
 
 This method will be called when the C<getc> function is called.
 
     sub GETC { print "Don't GETC, Get Perl"; return "a"; }
 
 =item CLOSE this
+X<CLOSE>
 
 This method will be called when the handle is closed via the C<close>
 function.
@@ -914,12 +959,14 @@ function.
     sub CLOSE { print "CLOSE called.\n" }
 
 =item UNTIE this
+X<UNTIE>
 
 As with the other types of ties, this method will be called when C<untie> happens.
 It may be appropriate to "auto CLOSE" when this occurs.  See
 L<The C<untie> Gotcha> below.
 
 =item DESTROY this
+X<DESTROY>
 
 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
@@ -938,11 +985,13 @@ Here's how to use our little example:
     print <FOO>;
 
 =head2 UNTIE this
+X<UNTIE>
 
 You can define for all tie types an UNTIE method that will be called
 at untie().  See L<The C<untie> Gotcha> below.
 
 =head2 The C<untie> Gotcha
+X<untie>
 
 If you intend making use of the object returned from either tie() or
 tied(), and if the tie's target class defines a destructor, there is a