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 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 <[email protected]>






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.