Pod::Index(3pm)

✨ NAME ✨

Pod::Index — index and search PODs using X<> entries. (Yep bestie, this is the Pod::Index(3pm) page, coming at you straight from the User Contributed Perl Documentation corner of the internet 🫶)

---

🌸 SYNOPSIS 🌸

### to create an index:
use Pod::Index::Builder;

my $p = Pod::Index::Builder->new;
for my $file (@ARGV) {
    $p->parse_from_file($file);
}

$p->print_index("index.txt");

### to search for a keyword in the index:
use Pod::Index::Search;

my $q = Pod::Index::Search->new(
    filename => 'index.txt',
);

my @results = $q->search('getprotobyname');

for my $r (@results) {
    printf "%s\t%s\n", $r->podname, $r->line;
    print $r->pod;
}

---

🦋 DESCRIPTION 🦋

So the Pod-Index distribution ships a whole little squad of modules for indexing and searching POD that's been properly marked up with X<> POD codes. It's giving ✨organized✨.

And here's the tea: Pod::Index, as a module, does nothing. Nothing!! It's the group chat that never sends a message. Literally all the actual work is done by Pod::Index::Builder, Pod::Index::Search, and the other helper modules. They're the main characters here 💅.

This document? It's the vibes doc. It talks about some of the general issues with POD indexing — specifically, the recommended conventions for how you use X<> codes. iykyk.

---

🌈 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 building indexes. It always renders as empty-string. Example: "X<absolutizing relative URLs>"

Not me being the most ignored formatting code in the whole language and still being iconic 😭

---

👑 CONVENTIONS FOR THE USE OF X<> CODES 👑

💅 Placement of the X<> entries

First, a definition, bestie — gotta set the scene. 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:

1. If the X<> is at the end of a textblock, the scope is that paragraph and zero or more verbatim paragraphs immediately following it.
2. 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". Slay, scope boundaries 🌸

3. Other command paragraphs, such as =back, =over, =begin, =end, and =for should not be used for attaching X<> entries. Just don't do it, babe 🚫

🎀 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>. One operator. Singular. Periodt 💅
• 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. Commas = the og filing system 📁✨
• 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. Duplicates? Not a crime. Not even a misdemeanor 🫶

---

⭐ VERSION ⭐

0.14

---

🔥 SEE ALSO 🔥

Pod::Index::Builder, Pod::Index::Search, Pod::Index::Entry, perlpod — go read the whole friend group, they all ate 💖

---

🧚 AUTHOR 🧚

Ivan Tubert-Brohman <itub@cpan.org>

---

🌟 COPYRIGHT 🌟

Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

okay that's the whole page, you're officially indexed 📇✨ — this was perl v5.30.0, dated 2020-05-17, signing off from the Pod::Index(3pm) era, love u, bye 🎀💜