From PerlNet

Contents 1 Background 2 Conventions for the use of X<> codes 2.1 Placement of the X<> entries 2.2 Content of the X<> entry

Background

The little-known (or at least little-used) X<> formatting code is described in perlpod:

 "X<topic name>" -- an index entry
   This is ignored by most formatters, but some may use it for build-
   ing indexes.  It always renders as empty-string.  Example: "X<abso-
   lutizing relative URLs>"

Conventions for the use of X<> codes

Placement of the X<> entries

First, a definition. By "scope", I mean the part of the document that is deemed relevant to an index entry, and that may be extracted and shown in isolation by a processing or display tool. For example, perldoc -f considers the scope of a function to end at the beginning of the next =item, or at the end of the enclosing =over.

The X<> entries should be added at the end of a command or textblock paragraph (verbatim paragraphs are excluded). The scope of the index entry starts at the beginning of the paragraph to which it was attached; the end of the scope depends on the command type:

• if the X<> is at the end of a textblock, the scope is that paragraph and zero or more verbatim paragraphs immediately following it.
• if the X<> is at the end of a command paragraph, it depends on the type of command:

=head1, head2, etc.

The scope ends right before the next heading with equal or higher level. That is, a =head1 ends at the next =head1, and a =head2 ends at the next =head2 or =head1.

=item

The scope ends right before the next =item, or the =back

that terminates the containing list. Note: "empty" items are not counted for terminating scopes, to allow for cases where multiple =items head a block of text. For example,

   =item function
   X<function>
   X<otherfunction>
   
   =item otherfunction
   
   C<function> and C<otherfunction> do the same thing,
   even if they    have different names...
   
   =item lemonade

Here the scope of the X<function> and X<otherfunction> entries starts with "=item function", and ends right before "=item lemonade".

• other command paragraphs, such as =back, =over, =begin, =end, and =for

should not be used for attaching X<> entries.

Content of the X<> entry

• It should contain plain text without further formatting codes (with the possible exception of E<>).
• It should be in lowercase, unless caps are required due to case-sensitivity or correctness.
• Non-word characters are allowed, so one can list things like operators and special variables.
• Use of synonyms is encouraged, to make things easier to find.
• To be consistent, words should be normalized to the singular whenever possible. For example, use X<operator> instead of X<operators>.
• The use of a comma in an index entry has a special meaning: it separates levels of hierarchy (or namespaces), as a way of classifying entries in more specific ways. For example, "X<operator, logical>", or "X<operator, logical, xor>". This information may be used by processing programs to arrange the entries, or for listing results when a user searches for a namespace that contains several entries.
• There's no limitation as to the number of times that a given entry can appear in a document or collection of documents. That is, it is not an error to have X<whatever> appear twice in the same file.