view release on metacpan or  search on metacpan

Pod/Hlp.pm  view on Meta::CPAN

Also:

    perl pod2hlb

=head1 DESCRIPTION

Pod::Hlp is a module that can convert documentation in the POD format
(such as can be found throughout the Perl distribution) into formatted 
VMS C<*.HLP> files.  Such files can be inserted into an .HLB library 
through the C<LIBRARY/HELP/REPLACE> system call, or via the use of the 
C<pod2hlb> script supplied with the kit.  A separate F<pod2hlp> program 
is included that is primarily a wrapper for Pod::Hlp.

The single function C<pod2hlp()> can take one, two, or three arguments. 
The first should be the name of a file to read the pod from, or "<&STDIN" 
to read from STDIN.   A second argument, if provided, should be an 
integer indicating the help header level of the file as a whole where 
C<'1'> is the default.  A third argument, if provided, should be a 
filehandle glob where output should be sent.

=head1 AUTHOR

Peter Prymmer E<lt>pvhp@best.comE<gt>

based heavily on Pod::Text by:

Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>

=head1 TODO

Cleanup work.  VT escapes should be substituted for the 
Term::Cap ones.  The input and output locations need to be more 
flexible.

=cut

require Exporter;
@ISA = Exporter;
#@EXPORT = qw(pod2text);

$UNDL = "\x1b[4m";
$INV = "\x1b[7m";
$BOLD = "\x1b[1m";
$NORM = "\x1b[0m";

@head1_freq_patterns            # =head1 patterns which need not be index'ed
    = ("AUTHOR","BUGS","DATE","DESCRIPTION","DIAGNOSTICS",
       "ENVIRONMENT","EXAMPLES","FILES","INTRODUCTION","NAME","NOTE",
       "SEE ALSO","SYNOPSIS","WARNING");

sub pod2hlp {
local($file,$hlp_level,*OUTPUT) = @_;
$hlp_level = '1' if @_<2;
$head1_level = $hlp_level + 1;
$head2_level = $head1_level + 1;
$last_cmd = $hlp_level;
*OUTPUT = *STDOUT if @_<3;

$SCREEN = 72;

$/ = "";

$FANCY = 0;

$cutting = 1;
$DEF_INDENT = 4;
$indent = $DEF_INDENT;
$needspace = 0;

open(IN, $file) || die "Couldn't open $file: $!";

POD_DIRECTIVE: while (<IN>) {
    if ($cutting) {
	next unless /^=/;
	$cutting = 0;
    }
    1 while s{^(.*?)(\t+)(.*)$}{
	$1
	. (' ' x (length($2) * 8 - length($1) % 8))
	. $3
    }me;
    # Translate verbatim paragraph
    if (/^\s/) {
	$needspace = 1;
	output($_);
	next;
    }

sub prepare_for_output {

    s/\s*$/\n/;
    &init_noremap;

    # need to hide E<> first; they're processed in clear_noremap
    s/(E<[^<>]+>)/noremap($1)/ge;
    $maxnest = 10;
    while ($maxnest-- && /[A-Z]</) {
	unless ($FANCY) {
	    s/C<(.*?)>/`$1'/g;
	} else {
	    s/C<(.*?)>/noremap("E<lchevron>${1}E<rchevron>")/ge;
	}
        # s/[IF]<(.*?)>/italic($1)/ge;
        s/I<(.*?)>/*$1*/g;
        # s/[CB]<(.*?)>/bold($1)/ge;
	s/X<.*?>//g;
	# LREF: a manpage(3f)
	m:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:;
	if (defined($2)) {
	    s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the $1$2 help page:g;
	}
	else {
	    s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the $1 help page:g;
	}
	# LREF: an =item on another manpage
	s{
	    L<
		([^/]+)
		/
		(
		    [:\w]+