/ 
App-FuguWeb-0.1.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.

METHODS

path, name, section

The source, the manual name, and its section.

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.

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>