FuguWeb
App::FuguWeb::Manual(3p) Perl Library Manual App::FuguWeb::Manual(3p)

App::FuguWeb::Manual - one manual source, and what the site asks of it

    use App::FuguWeb::Manual;
    my $manual = App::FuguWeb::Manual->from_mdoc('man/fugu/Daemon.3p',
        $group);
    $manual->name;              # Fugu::Daemon
    $manual->section;           # 3p
    $manual->page;              # Fugu::Daemon.3p.html
    $manual->staged_name;       # Fugu::Daemon.3p
    $manual->description;       # read from the source

A manual is an mdoc(7) page or a POD sidecar. The class answers the five questions that the build and the index ask about one: where it is, what it is called, which section it belongs to, which page it becomes, and what it is for.

The class never retypes a description. The source page is the only copy, and "description" reads it.

App::FuguWeb::Config::Group builds these objects. A caller normally asks a group for its manuals instead of constructing one.

    App::FuguWeb::Manual->from_mdoc($path, $group)

One mdoc source. The file extension gives the section, and the group namespace prefixes the name, so man/fugu/Daemon.3p is the source of Fugu::Daemon(3p).

    App::FuguWeb::Manual->from_pod($path, $group, $module_root)

One POD sidecar. The section is always "3p". The name is the path below $module_root, with the separators turned into the Perl ones, so lib/App/OpenHAP/Tasmota/Heater.pod is the source of App::OpenHAP::Tasmota::Heater(3p).

$path and $module_root must be paths of the same kind: both absolute, or both relative to the same directory.

    $manual->translated($path, $code)

The manual of one language whose source is the namesake of this one. The copy keeps the name, the section and the page, because a page name must not change with the language. It reads its description from its own source.

The source, the manual name, its section, and the language of the source. A manual of a constructor holds "en", and a translated manual holds the code of its language.

Whether the source is a POD sidecar. A sidecar goes through "pod2man" first; an mdoc source does not.

The name of the page in the output directory: "<name>.<section>.html".

The name that the mdoc staging directory needs: "<name>.<section>".

"mandoc" reads a ".Xr" target as a local link only when a file named "%N.%S" sits in its working directory. That is why man/fugu/Daemon.3p stages as Fugu::Daemon.3p and not under its own file name.

The one-line description, read from the source.

An mdoc page gives the argument of its first ".Nd" macro. A POD sidecar gives the text after "Module -" on the first non-blank line below "=head1 NAME". The method returns "undef" when the source carries neither, and reads the file once.

App::FuguWeb, App::FuguWeb::Config, App::FuguWeb::Index, mandoc(1)

Dick Olsson <hi@senzilla.io>

2026-10-21 OpenBSD