NAME

Getopt::Gen::cmdline_pod.pm - built-in template for generating plain old documentation.

SYNOPSIS

use Getopt::Gen::cmdline_pod;

$og = Getopt::Gen::cmdline_pod->new(%args);
$og->parse($options_file);
$og->fill_in(%extra_text_template_fill_in_args);

DESCRIPTION

Generate pod documentation from option specifications.

METHODS

Most are inherited from Getopt::Gen.

  • fill_in(%args)

    Just like the Getopt::Gen method, except you do not need to specify 'TYPE' or 'SOURCE' parameters.

BUGS

Probably many.

ACKNOWLEDGEMENTS

perl by Larry Wall.

'gengetopt' was originally written by Roberto Arturo Tena Sanchez, and it is currently maintained by Lorenzo Bettini.

AUTHOR

Bryan Jurish <moocow@cpan.org>

SEE ALSO

perl(1). Getopt::Gen(3pm). Getopt::Gen::cmdline_c(3pm). Getopt::Gen::cmdline_h(3pm). Text::Template(3pm).

NAME

[@ (defined($og{USER}{program}) ? $og{USER}{program} : (defined($og{package}) ? $og{package} : '?')) @] - [@$og{purpose}@]

[@ $OUT = ''; if (defined($og{USER}{program_version}) || defined($og{version})) { $OUT .= "=head1 VERSION\n\n"; if (defined($og{USER}{program})) { $OUT .= $og{USER}{program}.' '; if (defined($og{USER}{program_version})) { $OUT .= $og{USER}{program_version}.' '; } } else { $OUT .= (defined($og{package}) ? ($og{package}.' '.(defined($og{version}) ? ($og{version}) : '')) : ''); } } @]

SYNOPSIS

[@ $OUT .= (defined($og{USER}{program}) ? $og{USER}{program} : (defined($og{package}) ? $og{package} : '?')); $OUT .= ' [OPTIONS]' if (@{$og{optl}}); if ($og{unnamed}) { if (@{$og{args}}) { $OUT .= join("", map { " $_->{name}" } @{$og{args}}); } else { $OUT .= " FILE(s)..."; } }

@] [@ #// -- summary: argument descriptions if ($og{unnamed} && @{$og{args}}) { my ($arg,$maxarglen); #// -- get argument field-lengths foreach $arg (@{$og{args}}) { $maxarglen = length($arg->{name}) if (!defined($maxarglen) || $maxarglen < length($arg)); } $OUT .= join("\n ", "", q{Arguments:}, map { sprintf(" %-${maxarglen}s %s", $_->{name}, $_->{descr}) } @{$og{args}}); }

    #// -- summary: option descriptions
    if (@{$og{optl}}) {
      #// -- get option field-lengths
      my ($optid,$opt,$maxshortlen,$maxlonglen,$oshortlen,$olonglen);
      my ($short,$long,$descr);
      foreach $opt (values(%{$og{opth}})) {
	$oshortlen = defined($opt->{short}) ? 2 : 0;
	$olonglen = defined($opt->{long}) ? 2+length($opt->{long}) : 0;
	if ($opt->{arg}) {
	  $oshortlen += length($opt->{arg});
	  $olonglen += 1+length($opt->{arg});
	}
	$maxshortlen = $oshortlen
	  if (!defined($maxshortlen) || $maxshortlen < $oshortlen);
	$maxlonglen = $olonglen
	  if (!defined($maxlonglen) || $maxlonglen < $olonglen);
      }
      #// -- print option summary
      my $group = '';
      foreach $optid (@{$og{optl}}) {
	$opt = $og{opth}{$optid};
	if ($opt->{group} ne $group) {
          #// -- print group header
	  $group = $opt->{group};
	  $OUT .= "\n\n $group";
	}
        #// -- print option
	$short = $long = $descr = '';
	if (defined($opt->{short}) && $opt->{short} ne '-') {
	  $short = "-$opt->{short}";
	  $short .= $opt->{arg} if (defined($opt->{arg}));
	}
	if (defined($opt->{long}) && $opt->{long} ne '-') {
	  $long = $opt->{long};
	  $long = '--'.$long;
	  $long .= '='.$opt->{arg} if (defined($opt->{arg}));
	}
	next if ($short eq '' && !$og{longhelp});
	$OUT .= ("\n    "
		 .sprintf("%-${maxshortlen}s", $short)
		 .($og{longhelp} ? sprintf("  %-${maxlonglen}s", $long) : '')
		 .'  '.$opt->{descr});
      }
    }
@]

DESCRIPTION

[@ $og{purpose} ? $og{purpose} : '' @]

[@ defined($og{USER}{details}) ? $og{USER}{details} : '' @]

CONFIGURATION FILES

Configuration files are expected to contain lines of the form:

LONG_OPTION_NAME    OPTION_VALUE

where LONG_OPTION_NAME is the long name of some option, without the leading '--', and OPTION_VALUE is the value for that option, if any. Fields are whitespace-separated. Blank lines and comments (lines beginning with '#') are ignored.

); if (@{$og{rcfiles}}) { $OUT .= ("The following configuration files are read by default:\n" ."\n" ."=over 4\n\n" .join('', map { "=item * $_\n\n" } @{$og{rcfiles}}) ."=back\n\n"); } else { $OUT .= "No configuration files are read by default.\n\n"; } } $OUT = "=pod\n\n$OUT\n\n=cut\n\n" if ($OUT); @]

############################################################### # Addenda ###############################################################

ADDENDA

[@ defined($og{USER}{addenda}) ? $og{USER}{addenda} : ''; @]

About this Document

Documentation file auto-generated by [@$og{name}@] version [@$OptGenVersion@] using Getopt::Gen version [@ $Getopt::Gen::VERSION @]. [@ my $ts='Translation was initiated'; if ($og{want_timestamp}) { my $d=`date`; $d=~s/\s*$//s; $ts.=" on $d"; } $ts; @] as:

optgen.perl [@ $CMDLINE_OPTIONS @]

BUGS AND LIMITATIONS

[@ defined($og{USER}{bugs}) ? $og{USER}{bugs} : "Unknown." @]

ACKNOWLEDGEMENTS

[@ defined($og{USER}{acknowledge}) ? $og{USER}{acknowledge} : 'Perl by Larry Wall.

Getopt::Gen by Bryan Jurish.'; @]

AUTHOR

[@ (defined($og{USER}{author}) ? podify($og{USER}{author}) : 'A. U. Thor, <a.u.thor@a.galaxy.far.far.away>'); @]

SEE ALSO

[@ (defined($og{USER}{seealso}) ? $og{USER}{seealso} : 'perl, Getopt::Gen.'); @]