1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
# Package metadata for podlators.
#
# This file contains configuration for DocKnot used to generate
# documentation files (like README.md) and web pages. Other documentation
# in this package is generated automatically from these files as part of
# the release process. For more information, see DocKnot's documentation.
#
# DocKnot is available from <https://www.eyrie.org/~eagle/software/docknot/>.
#
# Copyright 1999-2010, 2012-2022 Russ Allbery <rra@cpan.org>
#
# SPDX-License-Identifier: MIT
format: v1
name: podlators
maintainer: Russ Allbery <rra@cpan.org>
version: '5.01'
synopsis: format POD source into various output formats
license:
name: Perl
copyrights:
- holder: Russ Allbery <rra@cpan.org>
years: 1999-2010, 2012-2022
build:
type: ExtUtils::MakeMaker
distribution:
cpan: podlators
section: perl
tarname: podlators
version: podlators
support:
email: rra@cpan.org
github: rra/podlators
web: https://www.eyrie.org/~eagle/software/podlators/
vcs:
browse: https://git.eyrie.org/?p=perl/podlators.git
github: rra/podlators
openhub: https://www.openhub.net/p/podlators
status:
workflow: build
type: Git
url: https://git.eyrie.org/git/perl/podlators.git
quote:
author: Robert Fripp
text: |
We move from making unnecessary efforts, the exertions of force, to making
necessary efforts: the direction of effortlessness. In this the prime
maxim is: honor necessity, honor sufficiency.
work: '"The Road to Graceland"'
docs:
api:
- name: pod-man
title: Pod::Man
- name: pod-text
title: Pod::Text
- name: pod-text-color
title: Pod::Text::Color
- name: pod-text-overstrike
title: Pod::Text::Overstrike
- name: pod-text-termcap
title: Pod::Text::Termcap
developer:
- name: todo
title: To-do list
user:
- name: perlpodstyle
title: POD style guide
- name: pod2man
title: pod2man documentation
- name: pod2text
title: pod2text documentation
- name: thanks
title: Thanks and credits
blurb: |
podlators contains Pod::Man and Pod::Text modules which convert POD input to
*roff source output, suitable for man pages, or plain text. It also
includes several subclasses of Pod::Text for formatted output to terminals
with various capabilities. It is the source package for the Pod::Man and
Pod::Text modules included with Perl.
description: |
POD is the Plain Old Documentation format, the documentation language used
for all of Perl's documentation. I learned it to document Perl modules,
started using it for Perl scripts as well, and discovered it was the most
convenient way I've found to write program documentation. It's extremely
simple, well-designed for writing Unix manual pages (and I'm a
traditionalist who thinks that any program should have a regular manual
page), and easily readable in the raw format by humans.
The translators into text and nroff (for manual pages) included in the Perl
distribution had various bugs, however, and used their own ad hoc parsers,
so when I started running into those bugs and when a new generic parser
(Pod::Parser) was written, I decided to rewrite the two translators that I
use the most and fix the bugs that were bothering me. This package is the
result.
podlators contains two main modules, Pod::Man and Pod::Text. The former
converts POD into nroff/troff source and the latter into plain text (with
various options controlling some of the formatting). There are also several
subclasses of Pod::Text for generating slightly formatted text using color
or other terminal control escapes, and a general utility module,
Pod::ParseLink, for parsing the POD `L<>` formatting sequences. Also
included in this package are the `pod2text` and `pod2man` driver scripts.
Both Pod::Text and Pod::Man provide a variety of options for fine-tuning
their output. Pod::Man also tries to massage input text where appropriate
to produce better output when run through nroff or troff, such as
distinguishing between different types of hyphens.
As of Perl 5.6.0, my implementation was included in Perl core, and each
release of Perl will have the at-the-time most current version of podlators
included. You therefore only need to install this package yourself if you
need a newer version than came with Perl (to get some bug fixes, for
example).
requirements: |
This module requires Perl 5.10 or later and Pod::Simple 3.26 or later.
(Pod::Simple 3.26 was included in Perl 5.17.10.)
The troff/nroff generated by Pod::Man should be compatible with any troff or
nroff implementation with the `-man` macro set, including mandoc. It is
primarily tested by me under GNU groff, but Perl users send bug reports for
a wide variety of implementations and Pod::Man is used to generate all of
Perl's own manual pages, so hopefully most of the bugs have been weeded out.
test:
lancaster: true
suffix: |
The following additional Perl modules will be used by the test suite if
present:
* Test::CPAN::Changes (part of CPAN-Changes)
* Test::MinimumVersion
* Test::Pod
* Test::Spelling
* Test::Strict
* Test::Synopsis
All are available on CPAN. Those tests will be skipped if the modules are
not available.
|
