From: Hallvard B Furuseth <h.b.furuseth@usit.uio.no>
Date: Wed, 26 Mar 1997 18:29:14 +0000 (+0100)
Subject: Re: Pod problems & fixes
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=f2506fb2d1c024863b597c56c929ef07b6369d7c;p=p5sagit%2Fp5-mst-13.2.git

Re: Pod problems & fixes

> Couldn't we please just make it program options?

Right.  Well, here is a simple version.  The output of
	perl -d -MPod::Text -e 'pod2text(@ARGV)' -- -a -72 INSTALL
follows, then the Text.pm patch.  What say?

Needs a few details - like L<> output, but that can wait until the
relevant people say yes/no.

    =head1 foo  ->  ==== foo ====
    =head2 foo  ->  ==   foo   ==
    =item  foo  ->  :    foo             (i.e. s/^  /: /, so a search
                                          for /^:/ finds next =item)

    B<foo>      ->     ``foo''           (was unquoted)
    C<foo>      ->     ``foo''           (was `foo')
    F<foo>      ->      "foo"            (was unquoted)
    I<foo>      ->      *foo*
    L<foo>      -> the section on "foo"  (details here must be fixed.
					  Later.)

The =items look a little strange, but OK.  Anyone got a better
suggestion?  But remember:

> From: Andy Dougherty <doughera@fractal.phys.lafayette.edu>
>
> Mostly, they can just use /^=/ in their favorite pager and find their way
> around the file.  If we remove the =head and =item markers, this sense of
> where you are in the whole file gets lost.  So I'm not going to do that.

BTW, is it a point to have just one string to search for?  If so, s/^:/=/.

Indentation: Have not checked exactly, but apparently =head* sets indent
to 4, =item adds 4.  Some verbatim paragraphs get too indented.  One fix
might be *not* to indent things under =head* that are not =items,
another would be to edit INSTALL a bit.

Also did

    s/B<(Note:?|before|not)>/I<$1>/gi;	# correct, I think

    s/B<(ARCH|VERSION)>/$1/g;	# looked a bit silly in ``quotes'',
				# and after all they are already
				# in uppercase.

p5p-msgid: 199703261829.TAA17015@bombur2.uio.no
---

diff --git a/lib/Pod/Text.pm b/lib/Pod/Text.pm
index 6906e63..bc3ccd6 100644
--- a/lib/Pod/Text.pm
+++ b/lib/Pod/Text.pm
@@ -12,7 +12,7 @@ Pod::Text - convert POD data to formatted ASCII text
 
 Also:
 
-	pod2text < input.pod
+	pod2text [B<-a>] [B<->I<width>] < input.pod
 
 =head1 DESCRIPTION
 
@@ -25,7 +25,9 @@ will be used to simulate bold and underlined text.
 A separate F<pod2text> program is included that is primarily a wrapper for
 Pod::Text.
 
-The single function C<pod2text()> can take one or two arguments. The first
+The single function C<pod2text()> can take the optional options B<-a>
+for an alternative output format, then a B<->I<width> option with the
+max terminal width, followed by one or two arguments. The first
 should be the name of a file to read the pod from, or "E<lt>&STDIN" to read from
 STDIN. A second argument, if provided, should be a filehandle glob where
 output should be sent.
@@ -48,10 +50,12 @@ require Exporter;
 @EXPORT = qw(pod2text);
 
 use vars qw($VERSION);
-$VERSION = "1.0202";
+$VERSION = "1.0203";
 
 $termcap=0;
 
+$opt_alt_format = 0;
+
 #$use_format=1;
 
 $UNDL = "\x1b[4m";
@@ -60,8 +64,7 @@ $BOLD = "\x1b[1m";
 $NORM = "\x1b[0m";
 
 sub pod2text {
-local($file,*OUTPUT) = @_;
-*OUTPUT = *STDOUT if @_<2;
+shift if $opt_alt_format = ($_[0] eq '-a');
 
 if($termcap and !$setuptermcap) {
 	$setuptermcap=1;
@@ -79,6 +82,13 @@ $SCREEN = ($_[0] =~ /^-(\d+)/ && (shift, $1))
        || (`stty -a 2>/dev/null` =~ /(\d+) columns/)[0]
        || 72;
 
+@_ = ("<&STDIN") unless @_;
+local($file,*OUTPUT) = @_;
+*OUTPUT = *STDOUT if @_<2;
+
+local $: = $:;
+$: = " \n" if $opt_alt_format;	# Do not break ``-L/lib/'' into ``- L/lib/''.
+
 $/ = "";
 
 $FANCY = 0;
@@ -142,7 +152,12 @@ sub prepare_for_output {
     $maxnest = 10;
     while ($maxnest-- && /[A-Z]</) {
 	unless ($FANCY) {
-	    s/C<(.*?)>/`$1'/sg;
+	    if ($opt_alt_format) {
+		s/[BC]<(.*?)>/``$1''/sg;
+		s/F<(.*?)>/"$1"/sg;
+	    } else {
+		s/C<(.*?)>/`$1'/sg;
+	    }
 	} else {
 	    s/C<(.*?)>/noremap("E<lchevron>${1}E<rchevron>")/sge;
 	}
@@ -215,8 +230,13 @@ sub prepare_for_output {
 	}
 	elsif ($Cmd eq 'head1') {
 	    makespace();
+	    if ($opt_alt_format) {
+		print OUTPUT "\n";
+		s/^(.+?)[ \t]*$/==== $1 ====/;
+	    }
 	    print OUTPUT;
 	    # print OUTPUT uc($_);
+	    $needspace = $opt_alt_format;
 	}
 	elsif ($Cmd eq 'head2') {
 	    makespace();
@@ -224,7 +244,13 @@ sub prepare_for_output {
 	    #print ' ' x $DEF_INDENT, $_;
 	    # print "\xA7";
 	    s/(\w)/\xA7 $1/ if $FANCY;
-	    print OUTPUT ' ' x ($DEF_INDENT/2), $_, "\n";
+	    if ($opt_alt_format) {
+		s/^(.+?)[ \t]*$/==   $1   ==/;
+		print OUTPUT "\n", $_;
+	    } else {
+		print OUTPUT ' ' x ($DEF_INDENT/2), $_, "\n";
+	    }
+	    $needspace = $opt_alt_format;
 	}
 	elsif ($Cmd eq 'over') {
 	    push(@indent,$indent);
@@ -252,7 +278,7 @@ sub prepare_for_output {
 		    IP_output($paratag, $_);
 		} else {
 		    local($indent) = $indent[$#index - 1] || $DEF_INDENT;
-		    output($_);
+		    output($_, 0);
 		}
 	    }
 	}
@@ -346,7 +372,9 @@ sub IP_output {
     s/\s+/ /g;
     s/^ //;
     $str = "format OUTPUT = \n"
-	. (" " x ($tag_indent))
+	. (($opt_alt_format && $tag_indent > 1)
+	   ? ":" . " " x ($tag_indent - 1)
+	   : " " x ($tag_indent))
 	. '@' . ('<' x ($indent - $tag_indent - 1))
 	. "^" .  ("<" x ($cols - 1)) . "\n"
 	. '$tag, $_'
@@ -374,6 +402,7 @@ sub output {
     } else {
 	s/^/' ' x $indent/gem;
 	s/^\s+\n$/\n/gm;
+	s/^  /: /s if defined($reformat) && $opt_alt_format;
 	print OUTPUT;
     }
 }