xref: /openbsd/gnu/usr.bin/perl/cpan/podlators/docs/docknot.yaml (revision f2a19305)

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