From: Gurusamy Sarathy Date: Tue, 29 Feb 2000 22:56:10 +0000 (+0000) Subject: fix Pod::Html to recognize C<< > >> etc., and convert some pods X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=35f2feb095c3dd2b77eb6efc2bf725b5886b6931;p=p5sagit%2Fp5-mst-13.2.git fix Pod::Html to recognize C<< > >> etc., and convert some pods to the more readable form (from Robin Barker) p4raw-id: //depot/perl@5373 --- diff --git a/lib/Pod/Html.pm b/lib/Pod/Html.pm index e48e9b2..4df9599 100644 --- a/lib/Pod/Html.pm +++ b/lib/Pod/Html.pm @@ -1382,7 +1382,9 @@ sub process_puretext { # converted to html commands. # -sub process_text1($$;$); +sub process_text1($$;$$); +sub pattern ($) { $_[0] ? '[^\S\n]+'.('>' x ($_[0] + 1)) : '>' } +sub closing ($) { local($_) = shift; (defined && s/\s+$//) ? length : 0 } sub process_text { return if $ignore; @@ -1391,8 +1393,8 @@ sub process_text { $$tref = $res; } -sub process_text1($$;$){ - my( $lev, $rstr, $func ) = @_; +sub process_text1($$;$$){ + my( $lev, $rstr, $func, $closing ) = @_; $lev++ unless defined $func; my $res = ''; @@ -1404,7 +1406,7 @@ sub process_text1($$;$){ } elsif( $func eq 'C' ){ # C - can be a ref or # need to extract text - my $par = go_ahead( $rstr, 'C' ); + my $par = go_ahead( $rstr, 'C', $closing ); ## clean-up of the link target my $text = depod( $par ); @@ -1432,7 +1434,7 @@ sub process_text1($$;$){ ## L => produce text, use cross-ref for linking ## L => make text from cross-ref ## need to extract text - my $par = go_ahead( $rstr, 'L' ); + my $par = go_ahead( $rstr, 'L', $closing ); # some L<>'s that shouldn't be: # a) full-blown URL's are emitted as-is @@ -1557,15 +1559,16 @@ sub process_text1($$;$){ unless $$rstr =~ s/^>//; } else { - while( $$rstr =~ s/\A(.*?)([BCEFILSXZ]<|>)//s ){ + my $term = pattern $closing; + while( $$rstr =~ s/\A(.*?)(([BCEFILSXZ])<(<+[^\S\n]+)?|$term)//s ){ # all others: either recurse into new function or - # terminate at closing angle bracket + # terminate at closing angle bracket(s) my $pt = $1; - $pt .= '>' if $2 eq '>' && $lev == 1; + $pt .= $2 if !$3 && $lev == 1; $res .= $lev == 1 ? pure_text( $pt ) : inIS_text( $pt ); - return $res if $2 eq '>' && $lev > 1; - if( $2 ne '>' ){ - $res .= process_text1( $lev, $rstr, substr($2,0,1) ); + return $res if !$3 && $lev > 1; + if( $3 ){ + $res .= process_text1( $lev, $rstr, $3, closing $4 ); } } @@ -1581,16 +1584,18 @@ sub process_text1($$;$){ # # go_ahead: extract text of an IS (can be nested) # -sub go_ahead($$){ - my( $rstr, $func ) = @_; +sub go_ahead($$$){ + my( $rstr, $func, $closing ) = @_; my $res = ''; - my $level = 1; - while( $$rstr =~ s/\A(.*?)([BCEFILSXZ]<|>)//s ){ + my @closing = ($closing); + while( $$rstr =~ + s/\A(.*?)(([BCEFILSXZ])<(<+[^\S\n]+)?|@{[pattern $closing[0]]})//s ){ $res .= $1; - if( $2 eq '>' ){ - return $res if --$level == 0; + unless( $3 ){ + shift @closing; + return $res unless @closing; } else { - ++$level; + unshift @closing, closing $4; } $res .= $2; } @@ -1889,7 +1894,7 @@ $E2c{sol} = '/'; $E2c{verbar} = '|'; $E2c{amp} = '&'; # in Tk's pods -sub depod1($;$); +sub depod1($;$$); sub depod($){ my $string; @@ -1902,15 +1907,15 @@ sub depod($){ } } -sub depod1($;$){ - my( $rstr, $func ) = @_; +sub depod1($;$$){ + my( $rstr, $func, $closing ) = @_; my $res = ''; return $res unless defined $$rstr; if( ! defined( $func ) ){ # skip to next begin of an interior sequence - while( $$rstr =~ s/\A(.*?)([BCEFILSXZ]))// ){ + my $term = pattern $closing; + while( $$rstr =~ s/\A(.*?)(([BCEFILSXZ])<(<+[^\S\n]+)?|$term)// ){ $res .= $1; - last if $2 eq '>'; - $res .= depod1( $rstr, substr($2,0,1) ); + last unless $3; + $res .= depod1( $rstr, $3, closing $4 ); } ## If we're here and $2 ne '>': undelimited interior sequence. ## Ignored, as this is called without proper indication of where we are. diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index e8f92d3..081709a 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -335,7 +335,7 @@ following a minus are interpreted as file tests. The C<-T> and C<-B> switches work as follows. The first block or so of the file is examined for odd characters such as strange control codes or -characters with the high bit set. If too many strange characters (E30%) +characters with the high bit set. If too many strange characters (>30%) are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file containing null in the first block is considered a binary file. If C<-T> or C<-B> is used on a filehandle, the current stdio buffer is examined @@ -544,7 +544,7 @@ arguments with which the subroutine was invoked. Be aware that the optimizer might have optimized call frames away before C had a chance to get the information. That means that C might not return information about the call frame you expect it do, for -C 1>. In particular, C<@DB::args> might have information from the +C<< N > 1 >>. In particular, C<@DB::args> might have information from the previous time C was called. =item chdir EXPR @@ -1002,8 +1002,8 @@ lookup: Outside an C, prints the value of LIST to C and exits with the current value of C<$!> (errno). If C<$!> is C<0>, -exits with the value of C<($? EE 8)> (backtick `command` -status). If C<($? EE 8)> is C<0>, exits with C<255>. Inside +exits with the value of C<<< ($? >> 8) >>> (backtick `command` +status). If C<<< ($? >> 8) >>> is C<0>, exits with C<255>. Inside an C the error message is stuffed into C<$@> and the C is terminated with the undefined value. This makes C the way to raise an exception. @@ -1217,12 +1217,12 @@ as terminals may lose the end-of-file condition if you do. An C without an argument uses the last file read. Using C with empty parentheses is very different. It refers to the pseudo file formed from the files listed on the command line and accessed via the -CE> operator. Since CE> isn't explicitly opened, -as a normal filehandle is, an C before CE> has been +C<< <> >> operator. Since C<< <> >> isn't explicitly opened, +as a normal filehandle is, an C before C<< <> >> has been used will cause C<@ARGV> to be examined to determine if input is available. -In a CE)> loop, C or C can be used to +In a C<< while (<>) >> loop, C or C can be used to detect the end of each file, C will only detect the end of the last file. Examples: @@ -1465,7 +1465,7 @@ operation is a hash or array key lookup or subroutine name: Although the deepest nested array or hash will not spring into existence just because its existence was tested, any intervening ones will. -Thus C<$ref-E{"A"}> and C<$ref-E{"A"}-E{"B"}> will spring +Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring into existence due to the existence test for the $key element above. This happens anywhere the arrow operator is used, including even: @@ -1933,8 +1933,8 @@ Returns the socket option requested, or undef if there is an error. Returns the value of EXPR with filename expansions such as the standard Unix shell F would do. This is the internal function -implementing the C*.cE> operator, but you can use it directly. -If EXPR is omitted, C<$_> is used. The C*.cE> operator is +implementing the C<< <*.c> >> operator, but you can use it directly. +If EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in more detail in L. Beginning with v5.6.0, this operator is implemented using the standard @@ -2109,7 +2109,7 @@ Implements the ioctl(2) function. You'll probably first have to say to get the correct function definitions. If F doesn't exist or doesn't have the correct definitions you'll have to roll your -own, based on your C header files such as Fsys/ioctl.hE>. +own, based on your C header files such as F<< >>. (There is a Perl script called B that comes with the Perl kit that may help you in this, but it's nontrivial.) SCALAR will be read and/or written depending on the FUNCTION--a pointer to the string value of SCALAR @@ -2553,24 +2553,24 @@ for this purpose; so if you're using C, specify EXPR in your call to open.) See L for a kinder, gentler explanation of opening files. -If MODE is C<'E'> or nothing, the file is opened for input. -If MODE is C<'E'>, the file is truncated and opened for -output, being created if necessary. If MODE is C<'EE'>, +If MODE is C<< '<' >> or nothing, the file is opened for input. +If MODE is C<< '>' >>, the file is truncated and opened for +output, being created if necessary. If MODE is C<<< '>>' >>>, the file is opened for appending, again being created if necessary. -You can put a C<'+'> in front of the C<'E'> or C<'E'> to indicate that -you want both read and write access to the file; thus C<'+E'> is almost -always preferred for read/write updates--the C<'+E'> mode would clobber the +You can put a C<'+'> in front of the C<< '>' >> or C<< '<' >> to indicate that +you want both read and write access to the file; thus C<< '+<' >> is almost +always preferred for read/write updates--the C<< '+>' >> mode would clobber the file first. You can't usually use either read-write mode for updating textfiles, since they have variable length records. See the B<-i> switch in L for a better approach. The file is created with permissions of C<0666> modified by the process' C value. -These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, C<'w'>, -C<'w+'>, C<'a'>, and C<'a+'>. +These various prefixes correspond to the fopen(3) modes of C<'r'>, C<'r+'>, +C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>. In the 2-arguments (and 1-argument) form of the call the mode and filename should be concatenated (in this order), possibly separated by -spaces. It is possible to omit the mode if the mode is C<'E'>. +spaces. It is possible to omit the mode if the mode is C<< '<' >>. If the filename begins with C<'|'>, the filename is interpreted as a command to which output is to be piped, and if the filename ends with a @@ -2590,7 +2590,7 @@ that pipes both in I out, but see L, L, and L for alternatives.) In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN -and opening C<'E-'> opens STDOUT. +and opening C<< '>-' >> opens STDOUT. Open returns nonzero upon success, the undefined value otherwise. If the C @@ -2662,10 +2662,10 @@ Examples: } You may also, in the Bourne shell tradition, specify an EXPR beginning -with C<'E&'>, in which case the rest of the string is interpreted as the +with C<< '>&' >>, in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) to be -duped and opened. You may use C<&> after C>, CE>, -C>, C<+E>, C<+EE>, and C<+E>. The +duped and opened. You may use C<&> after C<< > >>, C<<< >> >>>, +C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into account any existing contents of stdio buffers.) Duping file handles is not yet supported for 3-argument @@ -2696,7 +2696,7 @@ STDERR: print STDOUT "stdout 2\n"; print STDERR "stderr 2\n"; -If you specify C<'E&=N'>, where C is a number, then Perl will do an +If you specify C<< '<&=N' >>, where C is a number, then Perl will do an equivalent of C's C of that file descriptor; this is more parsimonious of file descriptors. For example: @@ -3092,10 +3092,10 @@ are inherently non-portable between processors and operating systems because they obey the native byteorder and endianness. For example a 4-byte integer 0x12345678 (305419896 decimal) be ordered natively (arranged in and handled by the CPU registers) into bytes as - + 0x12 0x34 0x56 0x78 # little-endian 0x78 0x56 0x34 0x12 # big-endian - + Basically, the Intel, Alpha, and VAX CPUs are little-endian, while everybody else, for example Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray are big-endian. MIPS can be either: Digital used it @@ -3105,12 +3105,12 @@ The names `big-endian' and `little-endian' are comic references to the classic "Gulliver's Travels" (via the paper "On Holy Wars and a Plea for Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980) and the egg-eating habits of the Lilliputians. - + Some systems may have even weirder byte orders such as - + 0x56 0x78 0x12 0x34 0x34 0x12 0x78 0x56 - + You can see your system's preference with print join(" ", map { sprintf "%#02x", $_ } @@ -3432,8 +3432,8 @@ When C<$/> is set to C, when readline() is in scalar context (i.e. file slurp mode), and when an empty file is read, it returns C<''> the first time, followed by C subsequently. -This is the internal function implementing the CEXPRE> -operator, but you can use it directly. The CEXPRE> +This is the internal function implementing the C<< >> +operator, but you can use it directly. The C<< >> operator is discussed in more detail in L. $line = ; @@ -3769,7 +3769,7 @@ This is also useful for applications emulating C. Once you hit EOF on your read, and then sleep for a while, you might have to stick in a seek() to reset things. The C doesn't change the current position, but it I clear the end-of-file condition on the handle, so that the -next CFILEE> makes Perl try again to read something. We hope. +next C<< >> makes Perl try again to read something. We hope. If that doesn't work (some stdios are particularly cantankerous), then you may need something more like this: @@ -3863,7 +3863,7 @@ You can effect a sleep of 250 milliseconds this way: select(undef, undef, undef, 0.25); B: One should not attempt to mix buffered I/O (like C -or EFHE) with C, except as permitted by POSIX, and even then only on POSIX systems. You have to use C instead. =item semctl ID,SEMNUM,CMD,ARG @@ -4072,7 +4072,7 @@ Sorts the LIST and returns the sorted list value. If SUBNAME or BLOCK is omitted, Cs in standard string comparison order. If SUBNAME is specified, it gives the name of a subroutine that returns an integer less than, equal to, or greater than C<0>, depending on how the elements -of the list are to be ordered. (The C=E> and C +of the list are to be ordered. (The C<< <=> >> and C operators are extremely useful in such routines.) SUBNAME may be a scalar variable name (unsubscripted), in which case the value provides the name of (or a reference to) the actual subroutine to use. In place @@ -4168,7 +4168,7 @@ Examples: || $a->[2] cmp $b->[2] } map { [$_, /=(\d+)/, uc($_)] } @old; - + # using a prototype allows you to use any comparison subroutine # as a sort subroutine (including other package's subroutines) package other; @@ -4465,7 +4465,7 @@ the F device) or based on the current time and process ID, among other things. In versions of Perl prior to 5.004 the default seed was just the current C