/ 
App-FuguWeb-0.11.0
/ App::FuguWeb::Manual

NAME

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

SYNOPSIS

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

DESCRIPTION

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.

CONSTRUCTORS

from_mdoc

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).

from_pod

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.

translated

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

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.

METHODS

path, name, section, lang

The source, the manual name, its section, and the tag of the language of the source. A manual of a constructor holds the default language of its group, and a translated manual holds the tag of its language.

is_pod

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

page

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

staged_name

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.

description

The one-line description, read from the source, as characters.

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.

SEE ALSO

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

AUTHOR

Dick Olsson <hi@senzilla.io>