#!/usr/bin/perl
#
# podify - preprocess configuration-style files to pod
#
# Copyright (C) 1998, Ford & Mason Ltd.  All rights reserved.
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of either:
#
# a) the GNU General Public License as published by the Free
#    Software Foundation; either version 1, or (at your option) any
#    later version, or
#
# b) the "Artistic License" which comes with the Perl distribution.
#
# $Id: podify,v 1.2 1998/11/24 21:16:19 andrew Exp $
#


use strict;
use Getopt::Long;

my $comment_re      = "#";
my $leading_spaces  = 1;
my $verbatim_indent = 4;
my $help;

GetOptions("comment-re=s"       => \$comment_re,
	   "leading-spaces=i"   => \$leading_spaces,
	   "verbatim-indent=i"  => \$verbatim_indent,
	   "help"               => \$help)
  or usage();

usage() if $help;


$leading_spaces  = " " x $leading_spaces;
$verbatim_indent = " " x $verbatim_indent;

while (<>) {
    chop;
    $_ = $verbatim_indent . $_ unless s/^(?:\s*$|$comment_re(?:\s*$|$leading_spaces))//;
    print "$_\n";
}
exit;

sub usage {
    die <<EOS;
Usage: $0 options <file
Options are:
	--comment-re=string     (default "#")
	--leading-spaces=number (default 1)
	--verbatim-indent       (default 4)
EOS
}


__END__

=head1 NAME

podify - turn commented file into POD

=head1 SYNOPSIS

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

=head1 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*//'


=head1 OPTIONS

podify takes the following options:

=over 4

=item --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*#'



=item --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).


=item --verbatim-indent=number

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

=back

=head1 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 C<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


=head1 BUGS

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


=head1 AUTHOR

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

=head1 SEE ALSO

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

=head1 COPYRIGHT

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

=cut