ANNOUCE: podify -- Configuration files and POD

[Andrew Ford <an...@icarus.demon.co.uk>]

I announced on the mod_perl mailing list a short script for using
Perl's POD documentation format for documenting Apache configuration
files (and more).

Andrew

------- Start of forwarded message -------
Date: Mon, 17 Aug 1998 10:36:09 +0100
From: Andrew Ford <an...@icarus.demon.co.uk>
To: modperl@apache.org
Subject: Configuration files and POD -- podify
Reply-to: Andrew Ford <A....@ford-mason.co.uk>

Inspired by the idea of embedding documentation in Apache
configuration files with the mod_perl =pod directive, I wrote a simple
script that removes leading comment characters from comment lines and
indents non-comment lines, allowing you to embed POD not only in
Apache configuration files but other configuration files for the likes
of Samba, inetd, crontab files, and even shell scripts!

You convert your POD-in-comments documented file with:

	expand file | podify | pod2html >file.html

(using expand to expand tabs to spaces).


The script is at:

	http://www.ford-mason.co.uk/resources/

Enjoy.

Andrew




Here is the manual page:


NAME
    podify - turn commented file into POD

SYNOPSIS
        podify [--comment-re=string] [--leading-spaces=number] [--verbatim-indent=number]

DESCRIPTION
    podify preprocesses non-perl files to extract POD hidden in comments and turn non-comment
    lines into verbatim text. It can be used to document configuration files such as those of the
    Apache web server, crontab files, or even shell scripts!

    You can even use podify on C++ or Java code by setting --comment-re='\s*//'

OPTIONS
    podify takes the following options:

    --comment-re=string
        A regular expression that matches the start of a comment line (defaults to "#"). This is
        pasted into another regular expression used to match each line, which is anchored at the
        start of the line so it should not start with "^". If you have documentation in indented
        comments you may want to specify something like:

            --comment-re='\s*#'

    --leading-spaces=number
        The number of leading spaces to strip after the comment pattern (defaults to 1). POD uses
        leading space to indicate that a line should be treated as verbatim text. podify deletes
        exactly the number of spaces specified here following the comment indicator from comment
        lines (lines consisting of just a comment indicator and space characters are converted to
        empty lines).

    --verbatim-indent=number
        The number of spaces to indent non-comment lines (defaults to 4).

EXAMPLE
    The following Apache configuration file is documented with POD in comments:

        # =head1 NAME
        #
        # httpd.conf - Apache HTTP server configuration file
        #
        # =head1 DESCRIPTION
        #
        # This is the main server configuration file. See URL http://www.apache.org/
        # for instructions.
        #
        # Do NOT simply read the instructions in here without understanding
        # what they do, if you are unsure consult the online docs. You have been
        # warned.  

        # Originally by Rob McCool

        # =head1 DETAILS
        #
        # ServerType is either inetd, or standalone.

        ServerType standalone

        # If you are running from inetd, go to "ServerAdmin".

        # Port: The port the standalone listens to. For ports < 1023, you will
        # need httpd to be run as root initially.

        Port 8080

        # HostnameLookups: Log the names of clients or just their IP numbers
        #   e.g.   www.apache.org (on) or 204.62.129.132 (off)
        # The default is off because it'd be overall better for the net if people
        # had to knowingly turn this feature on.

        HostnameLookups off

    Processing with `podify <httpd.conf | pod2text' gives:

        NAME
            httpd.conf - Apache HTTP server configuration file

        DESCRIPTION
            This is the main server configuration file. See URL
            http://www.apache.org/ for instructions.

            Do NOT simply read the instructions in here without understanding what
            they do, if you are unsure consult the online docs. You have been
            warned.

            Originally by Rob McCool

        DETAILS
            ServerType is either inetd, or standalone.

                ServerType standalone

            If you are running from inetd, go to "ServerAdmin".

            Port: The port the standalone listens to. For ports < 1023, you will
            need httpd to be run as root initially.

                Port 8080

            HostnameLookups: Log the names of clients or just their IP numbers e.g.
            www.apache.org (on) or 204.62.129.132 (off) The default is off because
            it'd be overall better for the net if people had to knowingly turn this
            feature on.

                HostnameLookups off

BUGS
    podify does not handle tab characters well. You are advised to untabify your files before
    filtering through podify, see expand(1).

AUTHOR
    Andrew Ford <A....@ford-mason.co.uk>

SEE ALSO
    perlpod(1), pod2text(1), pod2html(1), pod2latex(1), expand(1)

COPYRIGHT
    This program is distributed under the GNU General Purblic License or the Perl Artistic
    License.