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