Re: How can one put a table into a pod

[Ronald J Kimball]

On Sun, May 01, 2011 at 10:07:46PM -0600, Karl Williamson wrote:
> On 04/26/2011 10:51 AM, Allison Randal wrote:
> >
> >How about adding some modifiers to the PseudoPod tags, such as:
> >
> >=row center
> >
> >=row right
> 
> I'm thinking this would mean that the first column in the first row 
> would be centered, and the first column in the second row would be right 
> justified, and any other columns would have the default?  Is that 
> correct?  Thus for three columns, one could say
> 
> =row center left left
> 
> >
> >=cell span 2
> 
> I would think that it would be better to put the span info on the =row 
> tag because the =cell tag already accepts text after it, and it is 
> sufficient to put it on the row tag, like this:
> 
> =row center left span 2
> 
> denotes three columns, with the final 2 merged.

This is an interesting approach.  However, I think it would be difficult to
edit tables, especially if one wants to move cells around within a table,
because settings that belong to a specific cell would not be placed with
the cell.

Putting the modifiers on the =cell tag would be much better, except that,
as Karl points out, the text following the =cell tag already has meaning as
the contents of the cell.

Perhaps a new inline character tag could be used to mark these modifiers?

=cell J J This is a wide, centered cell!

(Where J is whichever of the available letters is most appropriate.)

Ronald

Re: [perl #95784] [PATCH] Let X<> within anchorifiable paragraphs be additional anchors.

[Ronald J Kimball]

On Sun, Jul 31, 2011 at 05:34:22PM -0400, Rocco Caputo wrote:

> Cc: pod-people@perl.org ... trying to segue the discussion into that list.

To that same end, I've removed p5p from this reply.

> It's legal and encouraged for the same index term to reference multiple 
> points in the broader text.  Indexes have always done this.  This example 
> from _TeXbook_ links "indexes" to four anchors in the book:
> 
>   indexes, 261-263, 392-394, 423-425, 481
> 
> Unfortunately hypertext doesn't support ambiguous link targets.  New syntax 
> for anchors doesn't solve this problem.  It only pushes renderer-specific 
> concerns into POD where they don't belong.
> 
> X can and should become an anchor wherever it's present.  L can and 
> should link to ALL of them.  The anchors' actual names are unimportant 
> implementation details, as long as X<> and L<> do the right things.
> 
> When we read books, we resolve ambiguous references by visiting the index and 
> branching.  We often take multiple branches until our curiosities are 
> satisfied.  And we benefit from incidental, serendipitous context while we're 
> there.
> 
> The obvious solution to ambiguous L is to emulate books.  If we know 
> L is ambiguous, then we already have a list of link targets.  Send the 
> reader to that list, and let them branch out from there.
> 
> A sufficiently advanced renderer could pop up a menu of options on link 
> click, but again, people writing POD shouldn't need new syntax to make it 
> happen.
> 

I can definitely see the usefulness of a link that leads to all the indexed
entries for a particular term.  However, I'm not convinced this should
replace the current behavior for L<>.  There's a difference between
something that IS foo, and something that is RELATED TO foo.  Sometimes
when using an index I want to follow the multiple branches, but other times
I just want the main entry.

Right now, L<> links to the main entry for a term (specifically, in cases
where X<> is added to the main entry as a convenient link target, as well
as to related entries).  Under your proposal, it would link to all the
entries for a term.  These are both useful; I just hesitate to add the
latter at the cost of the former.

Maybe there's a good way to allow both behaviors?

Ronald

Re: [perl #95784] [PATCH] Let X<> within anchorifiable paragraphs be additional anchors.

[Ronald J Kimball]

Sorry about contributing to pulling the thread away from your original
proposal.  I would definitely like to see a way to alias link targets as
you suggest.

Ronald

Re: Removal of specific Pod::Checker warnings

[Ronald J Kimball]

On Thu, Aug 11, 2011 at 12:19:45PM -0400, Shawn H Corey wrote:
> You're correct.  Under "Pod Commands", =item is listed as a bare item. 
> I don't know why there is a note for being forgiving for a valid 
> structure, but it's confusing.  And, of course, if it's valid, it can't 
> be bad style.

What?  Valid syntax can most definitely be bad style.  That's why we have
style checkers in the first place.

Ronald

Re: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X<...>

[Ronald J Kimball]

On Wed, Jan 25, 2012 at 07:03:26PM -0800, David E. Wheeler wrote:
> On Jan 25, 2012, at 6:00 PM, Ricardo Signes wrote:
> 
> >>> =head1 NAME
> >>> X
> >>> 
> >>> Pod::Simple::Pullparser get_title expands 'Some entry' in the title.  It
> >>> seems to me that it should not, and instead should replace it with an 
> >>> empty string.  This  behaviour is also hinted in the pod documentation.
> > 
> > It becomes NAME Some Entry?  That would certainly be an error.
> 
> No, it doesn't. Text:
> 
> > air ~> perl -MPod::Simple::Text -E 
> > 'Pod::Simple::Text->filter(\"=pod\n\n=head1 NAME\nX")'   
> > NAME 


> XHTML:

> > NAME 
  ^

That space should not be there.


> HTML:
> 
> > air ~> perl -MPod::Simple::HTML -E 
> > 'Pod::Simple::HTML->filter(\"=pod\n\n=head1 NAME\nX")' 
> > NAME Some entry
   ^^^

Here it did become "NAME Some entry", which is wrong.

> >  > name="NAME"
> > >NAME 

Re: pod checker that finds missing internal links?

[Ronald J Kimball]

On Sun, Jan 29, 2012 at 10:33:01AM +0100, 'Patrice Dumas' wrote:
> My personal opinion (and it shouldn't be really surprising, since I 
> also wrote a mail proposing a new command for anchors...) is that 
> index entries and anchors are different, serve a different editing 
> purpose and should be specified with different commands.

I agree; index entries and anchor targets should be different commands.

Ronald

Re: pod checker that finds missing internal links?

[Ronald J Kimball]

On Thu, Feb 02, 2012 at 09:24:30PM +0100, Marek Rouchal wrote:
> The main reason why I dislike an additional A<> is that since
> the existence of POD nobody really needed it - since anchors 
> for L<> are created by =head and =item. And as Perl stands for
> simplicity and efficiency, you certainly don't want to
> force people to rewrite all their POD to add A<> markup
> WITH THE SAME CONTENT as the =head/=item near it.

No one was proposing that.  The proposal is to *optionally* use A<> to
create an link target *in addition to* that created by the =head or =item.

The trouble with relying on =head/=item to define the link target is that
the primary purpose of that text is to be read by the user.  If you want to
change the text, you have to change all the links as well, possibly in
completely separate documents.

Letting the POD tools create "short" anchors is a reasonably effective
solution for perlfunc, but not very robust in general.


> Honestly, I do not see much difference in arguing whether an
> index entry should be an anchor or an anchor should be an
> index entry. I am trying to think practical, and that is:
> we have X<> and L<>, and all the PODs using these around.
> And we can add value by specifying that X<> creates _also_
> an anchor for potential L<>s to link against it. Then we 
> would not break any existing POD and give guidance to existing 
> or new renderers.
> 
> And I think we heard enough voices saying that we need index
> entries, and I understand that as "don't change the semantics
> of X<> being an index entry" - which IMHO does not prevent
> us from _extending_ its meaning.

The key feature of a link target is that it is unique.  You cannot have two
identical link targets.  There is no such restriction on index markers.
You could have multiple X tags in a single document.  That is why
index entries and link targets should be separate entities.

Ronald

Re: Allowing '->' and '=>' in C<...>

[Ronald J Kimball]

On Tue, Jan 25, 2000 at 08:22:01AM -0600, Brad Appleton wrote:
> On Tue, Jan 25, 2000 at 12:03:51AM -0500, Ronald J Kimball wrote:
> > I'm concerned that someone may find another exception, and then another,
> > and then another, and soon POD parsing becomes extremely complicated.
> 
> Too late - thats already the case with special-handling -> and =>
> inside of C<...>. It won't get significantly more or less complicated
> by limiting what can appear to the left of [-=]>. In fact its more likely
> to make the code less complicated.

The code may become less complicated, but the parsing rules may become more
complicated, which would make writing more complicated.  The POD author
would have to remember when -> and => end the block and when they don't,
depending on the characters which appear before.


> > > its not enough to simply be '->' or '=>', perhaps we only want to allow
> > > certain classes of characters to be to the left of '->' and '=>' and
> > > maybe only a select few punctuation characters are in that set.
> > 
> > This has the drawback of trading simplicity for readibility.  I think it
> > would create too many special cases to remember.
> 
> Unlike the dozen or so special cases we already have where we want
> to allow -> and => but not ==> --> !=> /=> and <>= in general.
> Perhaps you're not fully aware of the existing special cases. The
> regexp in the code looks something like:
> 
>qr/(?:[^-+*/=!&|%^x.<>$]+=|[^-$]+-)$/;
> 
> If anything I bet the above proposal would decrease the amount of special
> cases rather than increase it.
> 

How would you allow both C<@-> and C<$@->[0]> while decreasing the number of
special cases?


I think I'm starting the favor the original proposal of C<@-Z<>>.  :D


Ronald

Re: [p5pod] [ID 20000124.002] Unterminated C<...> at perlvar.pod line 188

[Ronald J Kimball]

On Mon, Jan 24, 2000 at 10:51:28PM -0600, Brad Appleton wrote:
> On Mon, Jan 24, 2000 at 11:28:52PM -0500, Ronald J Kimball wrote:
> > Ah, so the problem is a choice between C<@-Z<>> and C<$a-E[0]>, neither
> > of which is particularly readable.
> 
> So why not come up with a patch to the regular expression in Pod::Parser
> so that neither one is required?

I'm concerned that someone may find another exception, and then another,
and then another, and soon POD parsing becomes extremely complicated.


> I'm the first one to say how much I dislike having that code inside
> Pod::Parser to hack things up to allow -> and => in certain cases. I'm
> also the first one to admit the overwhelmingly vast majority of p5p
> was pretty insistent upon it at the time - which is why I coded it up
> anyway, even though my own preference and instincts went against it.

I can understand the desire, perhaps even the need, for it.
C<$ref-E[0]> is hard to read.


> > Code sections (and others, if desired) may begin with one or more
> > consecutive left angle brackets, and are terminated by the same number of
> > consecutive right angle brackets.  Within the code section, any lesser
> > number of consecutive angle brackets is ignored (unless, of course, they're
> > part of a nested section).  Other than at the beginning and end of a
> > section, angles would _not_ nest.
> 
> Zoinks - I don't care for that at all. I think it is far more limiting and
> restrictive than is necessary. Why not just try to be more precise about
> the circumstances under which '>' does NOT terminate a C<...>. Maybe
> its not enough to simply be '->' or '=>', perhaps we only want to allow
> certain classes of characters to be to the left of '->' and '=>' and
> maybe only a select few punctuation characters are in that set.

This has the drawback of trading simplicity for readibility.  I think it
would create too many special cases to remember.  As a start, the
characters that would have to be allowed before -> and => would include
[\w '\]}].  Of course, -> can follow any variable name, so these would both
be legal code -- $x->[0] , $@->[0] -- but only one could put in a C<>
block as is.  (Note that the second case may be quite common with exception
objects.)


> Thats a heckuva lot more accommodating and less restrictive than
> forbidding most forms of nesting (something which I'm not willing to do
> because Pod::Parser gets used for lots more stuff than just translation
> and removing the nesting will break lots of code that I personally have
> a stake in).

I'm not sure what you mean by "removing the nesting"...  Is Cc> an
entire code section, including c>?  If that's the case, there's no reason
to change it.  I was under the impression that bare angle brackets did not
nest, which is why I stated it that way.  My mistake.

In that case, under my proposal, C<> would be an unterminated code
block.


Actually, I think the subtlest problem to my proposal is that someone might
try to represent the comparison operator as C<<=>>, which would actually be
the assignment operator.  Hmm.


Ronald

Re: [ID 20000124.002] Unterminated C<...> at perlvar.pod line 188

[Ronald J Kimball]

[CC'ed to pod-people -- doc patch changed C<@-> to C<@-Z<>> to avoid
Unterminated C<...> errors.]

On Mon, Jan 24, 2000 at 03:04:16PM -0500, Ilya Zakharevich wrote:
> Ronald J Kimball writes:
> > >   ** Unterminated C<...> at .../pod/perlvar.pod line 188
> > >   ** Unterminated C<...> at .../pod/perlvar.pod line 188
> > >   ** Unterminated C<...> at .../pod/perlvar.pod line 424
> > > 
> > > This is due to C<@-> and the like.
> > > 
> > > Patch below
> > 
> > Why can't the POD parser be fixed, rather than hacking the POD?  POD is
> > supposed to be readable; C<@-Z<>> and C<$#-Z<>> are not readable.
> 
> This is another indication that the idea of allowing -> and => inside
> a group is a broken idea.
> 

Ah, so the problem is a choice between C<@-Z<>> and C<$a-E[0]>, neither
of which is particularly readable.

I propose a third solution, which I think preserves the simplicity and
readability of POD.

Code sections (and others, if desired) may begin with one or more
consecutive left angle brackets, and are terminated by the same number of
consecutive right angle brackets.  Within the code section, any lesser
number of consecutive angle brackets is ignored (unless, of course, they're
part of a nested section).  Other than at the beginning and end of a
section, angles would _not_ nest.

The above two examples would become:

C<@->
C<<$a->[0]>>

And other examples:

C<<{ key => 'value' }>>
C<<<$b >> 4>>>


However, this would be a problem for a code section such as C<<>.  In that
situation C> would then be necessary.  (Also, C> would still be
necessary, as before.)  So this solution is not perfect either.  But I'll
put it out for consideration.


Ronald

Re: http:// in L<>

[Ronald J Kimball]

On Fri, Sep 01, 2000 at 10:03:21PM +0100, Nicholas Clark wrote:
> On Fri, Sep 01, 2000 at 03:35:49PM -0500, Jarkko Hietaniemi wrote:
> > Tick, tock, tick, tock...
> 
> man perl56delta says
> 
>See the section on "/www.plover.com/~mjd/perl/at-
>error.html" in the http: manpage for more details about
>the history here.
> 
> 
> perlpod.pod says
> 
> L A link (cross reference) to name
>   L manual page
>   L   item in manual page
>   L   section in other manual page
>   L<"sec">section in this manual page
>   (the quotes are optional)
>   L   ditto
>   same as above but only 'text' is used for output.
>   (Text can not contain the characters '/' and '|', 
>   and should contain matched '<' or '>')
>   L
>   L
>   L
>   L
>   L
> 
> so this would mean perlguts.pod's 
> 
> L
> 
> is illegal but it does work. Patch attached makes the same change for the
> instances in perlxs.pod perl56delta.pod and perlos2.pod.
> Long term would it be a better idea to ammend the rules of POD so that
> L<[a-z]+:/.*> is taken as being a URL, before the rule L
> is applied? I'm assuming that no man pages end in a colon - is this wise?

My understanding is that the correct markup for a URL is no
special markup at all.  The POD translators are supposed to detect bare
URLs and convert them to links.

Ronald

Re: L versus L ?

[Ronald J Kimball]

On Fri, Apr 20, 2001 at 02:37:59PM -0600, Sean M. Burke wrote:
> At 02:13 PM 2001-04-20 -0400, Stephen P. Potter wrote:
> 
> Now, your suggestion:
> 
> >L A link (cross reference) to "link"
> >   "link" follows these rules:
> >   name(#) A manual Page (# is optional)
> >   /"sec"  A section (" optional)
> >   :"ident"An item (" optional)
> >   "text"| An arbitrary text string to print (" optional)
> >[...]  L<"text"|name(#)/"sec":"ident">
> 
> is rather more ambitious than mine, and is yet a third way to impute the
> semantics of section-link-destination versus item-link-destination: it
> apparently envisages a distinction between the two, such that they are no
> longer mutually exclusive!
> (At least as I understand things, they /are/ mutually exclusive currently:
> a link is either to L or L.)
> 
> So does L mean a link to the link-tag in the "sec"
> section, ignoring any other "foos" things in the document?  I don't think
> those semantics are feasable in HTML, and I think of hypertextification as
> basically the whole point of the L<...> construct (since otherwise you
> could just have plaintext saying: "See Foo::Bar's section on Baz").  And
> making a hypertext construct that's hard to make into HTML is very bad idea.

Sure it's feasible; you just have to set up the A NAME anchors
appropriately.







> Also, if I read it right, your proposal is incompatible with existing POD;
> it would reject like L and L.  And,
> for incompatibility in the other direction, I think that current POD
> parsers would misread L as making the text foo a link
> to a man page called name":"section [sic!].

Ugh.  L<> is broken.  Personally, I'd like to see it fixed, even if it
breaks compatibility with existing POD.  Perhaps with a converter from old
L<> style to new L<> style.


> But I like compatibility; and my suggestion is basically a clarification of
> existing practice (i.e., clarifying that section-link-targets and
> item-link-targes might as well be the same thing), and my further
> suggestion for deprecation (above) is just to shoo people away from
> pointlessly ambiguous constructs.

It is an improvement, but I think it's worth considering going further and
fixing L<> completely.


Ronald

Re: L versus L ?

[Ronald J Kimball]

On Fri, Apr 20, 2001 at 03:36:00PM -0600, Sean M. Burke wrote:
> At 04:47 PM 2001-04-20 -0400, Ronald J Kimball wrote:
> >Sure it's feasible; you just have to set up the A NAME anchors
> >appropriately.
> >
> >
> >
> >
> >
> 
> So if the HTML anchorname for something is made from its section name, a
> '-', and its item name, that means that you can't easily HTMLify a
> Potter-syntax link like L (where there's an item but no
> section) -- because you'd need to actually look at the document Foo (in its
> HTML output, which might not exist yet?  in its POD original?), and see
> what section contains a 'baz' item, so that you can know what to use for
> 'somesection' in .

This is still easy.  For example:


Section 1



Section 1, Item foos


Section 2



Section 2, Item foos


> That's what I mean saying that Stephen Potter's suggestion (such as I
> understood it) made HTMLification hard, all for the sake of some extra
> semantics that we've gotten this far without (and that I for one never
> missed).

Other people have missed it, though.  And this suggestion doesn't make
HTMLification hard.  You're just not trying hard enough to see how it would
work.


> Making HTMLification /easy/ would be if one could translate
> L without having to inspect the document Foo.  If one
> accepts that there is a section-target/item-target distinction and that
> they are mutually exclusive (i.e., they're two different namespaces for
> target-names in a document), then a pod2html could turn L
> into href="/path/to/Foo#s_whatever" and L into
> href="/path/to/Foo#i_whatever", with those s_ and i_ prefixes to keep the
> namespaces separate.

With the accompanying arbitrary restriction against using the same item in
two different sections.


> Conversely, if one accepts my proposal that there is no section-target /
> item-target distinction, then they both happily fold into
> href="/path/to/Foo#whatever".

With the accompanying arbitrary restriction against using the same label
for both an item and a section.


> In neither of THOSE cases (of non-Potter syntax) does HTMLification mean
> having to look at the target document.

None of these cases, including Potter's suggested syngtax, make
HTMLification hard.  The target document simply needs to set up all the
appropriate NAME anchors at each location.


> >> Also, if I read it right, your proposal is incompatible with existing POD;
> >>[...]
> >Ugh.  L<> is broken.  Personally, I'd like to see it fixed, even if it
> >breaks compatibility with existing POD.  Perhaps with a converter from old
> >L<> style to new L<> style.
> 
> Parts of L<...> are pointlessly ambiguous, and if we get people to avoid
> those (by deprecating in perlpod as I suggested; and by making podchecker
> scream), and then clarify this section-target/item-target distinction, or
> lack thereof, then it's FIXED.  Tra la!  Then we can turn on the fountains,
> bring out the giant peaches, and declare it a reflowering of happytime on
> Earth.

See above regarding arbitrary restrictions.  :)


> Moreover: if one /were/ to change link syntax to something incompatible,
> one might as well just use a new sequence, say, H<...> (h for hypertext).
> At least there you can /tell/ the old from the new (L<...> from H<...>),
> which is a minimal requirement on any sane data format.
> However, I don't think a new sequence is warranted.

Or something like:

LSIT>

where each of the pieces is optional.  This would also solve the problem of
E and E.  Just a crazy idea I had recently, though.  :)


Ronald

Re: L versus L ?

[Ronald J Kimball]

On Mon, Apr 23, 2001 at 03:05:23PM -0400, Stephen P. Potter wrote:
> Lightning flashed, thunder crashed and "Sean M. Burke" <[EMAIL PROTECTED]> whisp
> ered:
> | At 04:47 PM 2001-04-20 -0400, Ronald J Kimball wrote:
> | So if the HTML anchorname for something is made from its section name, a
> | '-', and its item name, that means that you can't easily HTMLify a
> | Potter-syntax link like L (where there's an item but no
> | section) -- because you'd need to actually look at the document Foo (in its
> | HTML output, which might not exist yet?  in its POD original?), and see
> | what section contains a 'baz' item, so that you can know what to use for
> | 'somesection' in .
> 
> No, you'd just make it be .  This does mean that you can't
> have two items in two different sections that are exactly the same.
> Hmm.. that is a bit of a problem, but less so than the current situation.

Well, really it just means that, if you do have two identical items in two
different sections, then any POD which links to either of those two items
should include the section and the item in the L<>.

Ronald

Re: [PATCH pod/perlfaq4.pod] Example of working in integers to avoid floating point errors

[Ronald J Kimball]

On Wed, May 30, 2001 at 09:07:24AM -0500, Jarkko Hietaniemi wrote:
> +(19.95) and divide by 100 at the end.  In fact, if you are dividing by
> +100, you don't even need to really divide-- just split of the
> +fractional parts and insert the '.'  (or whichever is your decimal
> +separator) in between, e.g.
> +
> +sub d100 {
> +$_[0] =~ /(.*?)(.(?:.)?)$/;
> +sprintf("%d.%02d", $1||0, $2);
> +}
> +
> +and then display all your numbers like this: C

In general, using $1 et al. without checking that the match succeeded is a
bad practice; I'm not sure it should be used in the FAQ.

Ronald

Re: [PATCH pod/perlfaq4.pod] Example of working in integers to avoid floating point errors

[Ronald J Kimball]

On Tue, May 29, 2001 at 06:51:32PM +0100, Michael G Schwern wrote:
> The perlfaq4 answer about floating point error should point out the
> technique of working in integers and then converting to decimal at the
> end.
> 
> --- pod/perlfaq4.pod  2001/05/29 17:46:32
> +++ pod/perlfaq4.pod  2001/05/29 17:48:38
> @@ -39,6 +39,11 @@
>  (part of the standard Perl distribution), but mathematical operations
>  are consequently slower.
>  
> +If precision is important, such as when dealing with money, its good
> +to work with integers and then divide at the last possible moment.
> +For example, work in pennies (1995) instead of dollars and cents
> +(19.95) and divide by 100 at the end.
> +

s/its/it's/;

Ronald

Re: translation experiment (was: pod in multiple languages?)

[Ronald J Kimball]

On Wed, Jul 11, 2001 at 05:23:46PM +0200, Brigitte Jellinek wrote:

> I've already translated the smallest core pod I could find:
> perlstyle.pod
> Sean's proposal of putting the different language versions into one file 
> 
> > =for :lang en
> > Hooboy, this does something!
> > 
> > =for :lang es
> > EWuju!  Hace algo
> 
> 
> didn't seem right for stand-alone pods, so I'm currently saving it
> as perlstyle.pod.de.  What do I do with it now?  Where do I hand it in?

Instead of adding .de to the filename, I would suggest having a directory
named de/ containing perlstyle.pod, to allow for 8.3 filesystems.

Ronald

Re: perlpodspec, draft 1

[Ronald J Kimball]

On Fri, Aug 10, 2001 at 04:28:50AM -0600, Sean M. Burke wrote:

> Pod content is contained in B.  A pod block starts with a
> line that matches , and continues up to the next line
> that matches C -- or up to the end of the file, if there is
> no C line.
> 
> =for comment
>  The current perlsyn says:
>  [beginquote]
>Note that pod translators should look at only paragraphs beginning
>with a pod directive (it makes parsing easier), whereas the compiler
>actually knows to look for pod escapes even in the middle of a
>paragraph.  This means that the following secret stuff will be ignored
>by both the compiler and the translators.
>   $a=3;
>   =secret stuff
>warn "Neither POD nor CODE!?"
>   =cut back
>   print "got $a\n";
>You probably shouldn't rely upon the warn() being podded out forever.
>Not all pod translators are well-behaved in this regard, and perhaps
>the compiler will become pickier.
>  [endquote]
>  I think that those paragraphs should just be removed; paragraph-based
>  parsing  seems to have been largely abandoned, because of the hassle
>  with non-empty blank lines messing up what people meant by "paragraph".

I agree with Philip, that paragraph-based parsing should *not* be removed.
The problem of non-empty blank lines is not a reason remove paragraph-based
parsing; just declare non-empty blank lines to be the same as empty blank
lines.


>  Even if the "it makes parsing easier" bit were especially true,
>  it wouldn't be worth the confusion of having perl and pod2whatever
>  actually disagree on what can constitute a pod block.

Until pod2whatever can parse Perl, perl and pod2whatever will always
disagree on what can constitute a pod block.

By the way, it would be much easier to add paragraph-based detection of pod
to perl, than parsing of perl to pod2whatever.


> (In other words, the pod processor for "head1" will apply the same
> processing to "Did You Remember to CEuse strict;>?" that it would
> to an ordinary paragraph -- i.e., interior sequences (like
> "CE...>" are parsed (and presumably formatted appropriately), and
> whitespace in the form of literal spaces and/or tabs is not significant.

This paragraph should be rewritten.  It's confusing, and there are three
open parens and only one close paren.  :)


> =item *
> 
> A B.  The first line of this paragraph must be a
> literal space or tab, and this paragraph must not be inside a "=begin
> I", ... "=end I" sequence where
> "I" begins with something other than a colon (":").

The significance of the colon has not been introduced yet, which makes this
sentence even harder to grasp than it already is.


> =item *
> 
> An B.  An ordinary paragraph is distinguished by
> the fact that the first line matches neither C nor
> C, I by not being inside a "=begin I",
> ... "=end I" sequence, where "I" begins with
> something other than a colon (":").

Same here.


> =item *
> 
> A B.  This is a paragraph that I inside a "=begin
> I" ... "=end I" sequence where
> "I" does I begin with a literal colon (":").  In
> some sense, a data paragraph is not part of pod at all, since it's
> not subject to pod parsing; but it is specified here, since pod
> parsers need to be able to call an event for it, or store it in some
> form in a parse tree, or at least just parse I it.

Same here.


What is the name for a paragraph that is inside a =begin/=end sequence with
a colon?


> =head1 About LE...> Sequences
> 
> As you can tell from a glance at L, the LE...>
> sequence is the most complex sequence in POD.  These points will
> hopefully clarify what it means and how processor should deal with
> it.
> 
> =over
> 
> =item *
> 
> In parsing an LE...> sequence, pod parsers must note four
> attributes:
> 
> =over
> 
> =item 1
> 
> The link-text.  If there is none, this must be undef.  (E.g., in
> "LEPerl Functions/perlfunc>", the link-text is "Perl Functions".
> In "LETime::HiRes>" and even "LE|Time::HiRes>", there is no
> link text.  Note that link text may contain formatting.)
> 
> =item 2
> 
> The link-text -- but if there was none, then the text that we'll
> infer in its place.  (E.g., for "LEGetopt::Std>", the inferred
> link text is "Getopt::Std".)

Attributes 1 and 2 are both "the link-text".  This is confusing.  I would
suggest calling these attributes "the specified link-text" and "the inferred
link-text".

=item 1

The specified link-text.  If there is none, this must be undef.  (E.g., in
"LEPerl Functions/perlfunc>", the specified link-text is "Perl
Functions".  In "LETime::HiRes>" and even "LE|Time::HiRes>", there
is no specified link-text.  Note that the link-text may contain
formatting.)

=item 2

The inferred link-text.  This is the same as the specified link-text if
there was any.  Otherwise, some reasonable link-text is inferred.  (E.g.,
for "LEGetopt::Std>", the inferred link-text is "Getopt::Std".)


> =back
> 
> Pod parsers may also note additional attributes including:
> 
> =over
> 
> 

Re: perlpodspec, draft 1

[Ronald J Kimball]

On Mon, Aug 20, 2001 at 10:53:15AM -0600, Sean M. Burke wrote:
> At 11:00 AM 2001-08-20 -0400, Ronald J Kimball wrote:
> >I agree with Philip, that paragraph-based parsing should *not* be removed.
> >The problem of non-empty blank lines is not a reason remove paragraph-based
> >parsing; just declare non-empty blank lines to be the same as empty blank
> >lines.
> 
> First off, when did Philip (Newton?) say that [this kind of]
> paragraph-based parsing should be removed?  I'd like to see his arguments.
> (I do see his message that asks "Does that mean that the following will be
> misparsed?[...]" but that was just a question (answered: "no").)

Err...  I thought he had said that it should not be removed.  Apologies if
I'm mistaken.

> So that I can make sure that we're talking about the same thing:  What I
> think we're arguing here is just whether or a =foo that starts a pod
> section has to be preceded by a blank/empty line, and also whether a =cut
> that ends a pod section has to be followed by a blank/empty line.
> Correct me if you have something else in mind.

I think pod commands in general should be preceeded by a blank line and
followed by a blank line.  But especially a pod command that starts a pod
section should be preceeded by a blank line, in perl and pod parsers.


> >Since the above conventions are just a recommendation (and not even a
> >"processors should...", I don't think this keeps authors from having to use
> >that absurd formatting.  Speaking for myself, if parsers are still allowed
> >to expand L as "the LWP::Simple manpage", then I will still
> >write L (and still hate having to do it).
> 
> I agree.  I was feeling benificent in permitting different ways to generate
> implicated link text (i.e., in the case where there was no L, but
> on reflection I've come to think that such variance is annoying in the
> extreme, and serves no useful purpose.
> So I will don the iron fist and make this a requirement:
> 
> Processors MUST treat L as if it were L.

Works for me.  :)


> Processors MUST treat L About The Stuff"> as if it were...
> and there I'm feeling a bit ambivalent.
> 
> For the implicated text there, I'm not sure which I like best:
> * Things::Stuff::Guh's section on Everything You Ever Wanted To Know About
> The Stuff
> * Things::Stuff::Guh's section on "Everything You Ever Wanted To Know About
> The Stuff"
> * "Everything You Ever Wanted To Know About The Stuff" in Things::Stuff::Guh

Maybe even: 

Things::Stuff::Guh / Everything You Ever Wanted To Know About The Stuff

?



> >> The text in the "=item [text]" paragraph should not match
> >> C or C, nor should it
> >> match just C.
> >
> >The third regex is redundant with the second.  :)
> 
> Is it?
>   C matches "=item *", "=item * ", etc.
>   C   matches "=item", "=item ", etc.

Oops.  I was seeing a \ before the * that isn't there.  Sorry about that.


Ronald

Proposed new syntax for L<> in POD

[Ronald J Kimball]

I actually wrote this proposal several months ago, after an earlier
discussion about difficulties with L<>.  However, it appears that I never
posted it anywhere.  I would appreciate feedback on this idea.  I think it
would make L<> much more useable.

The previous discussion is at
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2001-04/msg01017.html

thanks,
Ronald



A new syntax for the L<> sequence in pod.


Rationale:

The current syntax for the L<> sequence in pod has several acknowledged
drawbacks:

  First, there is ambiguity when linking to sections and items.

  Second, the characters |, /, and possibly " must be encoded with E<>.

  Third, it is not currently possible to specify an item within a section.


Proposal:

I propose the following new syntax for pod links:

  L< p s i t >

At least one of p<>, s<>, or i<> must appear; t<> is optional.  If p<> is
not specified, the current page is assumed.  Whitespace may be used around
the attributes to improve readability; it will be ignored by the parser.

This solution addresses all of the aforementioned drawbacks:

  There is no ambiguity as to which part of the link is a section and which
  is an item.  Additionally, the parts may be specified in whatever order
  the author finds most appropriate for the given link.

  Any character may be used without being encoded.  The characters < and >
  may be used via the same approach as the new C<< >> syntax:
  L< p i<< $< >> >

  Specifying both a section and an item is trivial.  Additionally, further
  attributes may be added later without complicating the syntax (e.g. d<>
  for diagram, to link to a specific diagram in a page).

The use of lowercase letters for the attributes avoids conflict and
confusion with already existing sequences, such as I<> for italic and S<>
for text with non-breaking spaces.


Transition:

Changing the syntax in this way raises the issue of transitioning from the
current syntax.  There are several approaches that could be taken:

  Outlaw the existing syntax, and force all pod documents and parsers to be
  updated.  This approach is unreasonable, particularly because people will
  end up using new parsers on existing pod, or existing parsers on new pod.

  Deprecate the existing syntax, encourage the updating of all pod
  documents, and update the parsers to produce warnings for the old syntax.

  Accept both syntaxes as equally acceptable, while reminding authors that
  the new syntax is more flexible and less ambiguous.

Either of the last two approaches would work well.  Pod parsers should be
able to easily distinguish between the existing and the new syntax.

I personally prefer the solution of deprecating the existing syntax.  That
will lead to the cleanest state of affairs: having a single supported
syntax for links in pod.

Re: FAQ patches.

[Ronald J Kimball]

On Sat, Sep 08, 2001 at 12:53:45AM -0400, Michael G Schwern wrote:
> On Fri, Sep 07, 2001 at 10:49:00PM -0600, Chris Fedde wrote:
> > The other suggestions have been rolled up except that ppt does not seem to
> > be at http://language.perl.org/ppt.
> 
> Sorry, language.perl.com/ppt.

That project has not been updated for more than two years.

Ronald

Re: FAQ patches.

[Ronald J Kimball]

On Sat, Sep 08, 2001 at 10:52:27PM -0700, Robert Spier wrote:
> Michael G Schwern writes:
> >On Sat, Sep 08, 2001 at 11:19:16AM -0400, Ronald J Kimball wrote:
> >> On Sat, Sep 08, 2001 at 12:53:45AM -0400, Michael G Schwern wrote:
> >> > Sorry, language.perl.com/ppt.
> >> 
> >> That project has not been updated for more than two years.
> >
> >Yeah, but it's better than just throwing them into Tom's scripts
> >directory.
> 
> There was a flurry of activity this past June.
> 
> http://sourceforge.net/projects/ppt

True, but this activity has not touched http://language.perl.org/ppt, which
has not been updated for more than two years.

Ronald

Re: perlpodspec: adding a markup for handling URIs

[Ronald J Kimball]

On Tue, Apr 02, 2002 at 11:13:17PM -0700, Sean M. Burke wrote:
> At 13:32 2002-04-03 +0800, Stas Bekman wrote:
> >U< title | uri >
> 
> I would greatly appreciate if L were the absolutely only Pod formatting 
> code that uses that execrable "|".  It complicates an already very 
> complicated parsing model.

L<> shouldn't use | either.  :)

Ronald

Re: perl that comes with MacOSX

[Ronald J Kimball]

On Sun, Sep 29, 2002 at 01:38:01PM -0400, Conrad Halling wrote:
> On Saturday, September 28, 2002, at 02:19 AM, Sean M. Burke wrote:
> 
> >From different sources, I've heard that the pod directory in the perl 
> >that comes with MacOSX has been renamed from "pod" to "pods".  Can 
> >anyone further confirm this?
> 
> Under Mac OS X 10.2.1, the directory is
> 
> /System/Library/Perl/pods

Presumably to keep it from being confused with the Pod directory, which
contains the various POD-related modules.  OSX is case-preserving but
not case-sensitive.

Ronald

Clarification of markup within a link

[Ronald J Kimball]

I could use some clarification regarding the use of formatting codes other
than Z<> and E<> within a link.


perlpodspec explains what to do when the section name contains markup, with
L Operator> as an example:

   o   Note that section names might contain markup.  I.e.,
   if a section starts with:

 =head2 About the C<-M> Operator

   or with:

 =item About the C<-M> Operator

   then a link to it would look like this:

 L Operator>

   Formatters may choose to ignore the markup for pur-
   poses of resolving the link and use only the render-
   able characters in the section name, as in:

 About the -M
 Operator

 ...

 About the
 -M
 Operator" in somedoc


But later, perlpodspec says that if the L<...> code does not have a "text|"
part, only E<...> and Z<> may occur:

   o   In a "L" code, text may contain formatting
   codes for formatting or for E<...> escapes, as in:

 Lstuff>|...>

   For "L<...>" codes without a "name|" part, only
   "E<...>" and "Z<>" codes may occur -- no other format-
   ting codes.  That is, authors should not use
   ""L>"".

   Note, however, that formatting codes and Z<>'s can
   occur in any and all parts of an L<...> (i.e., in
   name, section, text, and url).

What is the intended specification for formatting codes in a link?  (Is
L> legal if it's a link to =head1 B?)


thanks,
Ronald

RFC: perlpod and perlpodspec, L<> attribute syntax

[Ronald J Kimball]

The enclosed patch to perlpod.pod and perlpodspec.pod explains my proposed
syntax for attributes in L<>.
(e.g. L< p s the print function>)


Here's a quick summary of my proposal, as it currently stands:

  Lowercase letters are used to indicate attribute codes.  Attribute codes
  can only appear within formatting codes.  Attribute codes can appear
  anywhere within the formatting code, in any order.  Whitespace immediately
  preceeding and following an attribute code is ignored (that's just to make
  the pod easier to read).

  Each formatting code can have its own set of attributes, and only known
  attribute codes are accepted.  Right now I am only proposing attribute
  codes for L<>.


The patch does not yet address exactly how URL links with display text
should be rendered.  My current plan is to add a flag indicating that the
link should be rendered as 'text ' instead of 'text' in formats
that don't do hypertext links.

  e.g.
  pod:  L< u the Perl homepage>
   becomes
  text: the Perl homepage 
  HTML: http://www.perl.com/";>the Perl homepage

This is not ideal, because it requires a special case in most renderers,
but it's the best solution I've come up with.


I searched the standard documentation for instances of a lowercase letter
followed by <.  Under my proposal, these would become errors.  Most of the
instances either occur within verbatim text and are not affected, or are
errors and need to be fixed anyway.  These are the only two instances that
would need to be changed for my proposal:

perlop.pod:C or C<< s/bar/ >>.  A C will cause the
  could be either C<< sEfoo>/bar/ >>, C<< sZ<>/bar/ >>,
  or C<< s{foo}/bar/ >>

perlpodspec.pod:"\n\n\n").
  could be \nEhr>\n or \nZ<>\n


Ronald
diff -r -x '*~' -x '*.old' -x blib -uw Pod-Simple-0.96.orig/lib/perlpod.pod 
Pod-Simple-0.96/lib/perlpod.pod
--- Pod-Simple-0.96.orig/lib/perlpod.podWed May 14 17:21:34 2003
+++ Pod-Simple-0.96/lib/perlpod.pod Mon Jun  2 14:56:18 2003
@@ -332,73 +332,119 @@
 this represents program text ("Cgmtime($^T)E>") or some other
 form of computerese ("Cdrwxr-xr-xE>").
 
-=item CnameE> -- a hyperlink
+=item C...E> -- a hyperlink
 
-There are various syntaxes, listed below.  In the syntaxes given,
-C, C, and C cannot contain the characters
-'/' and '|'; and any '<' or '>' should be matched.
+There are two ways of specifying a link with LE...>: the traditional
+syntax and the attribute syntax.
+
+In the traditional syntax (e.g. LEtext|page/section>), C, C,
+and C cannot contain the characters '/' and '|', as those
+characters are used to separate the parts of the link.
+
+In the attribute syntax (e.g. LE pEpage> sEsection> text >),
+attribute codes are used to indicate the parts of the link.  Attribute
+codes are like formatting codes but begin with lowercase letters instead.
+The specific attribute codes for C...E> and their meanings are
+listed below.  See L< s > for a description of attribute
+codes in general.
+
+In both syntaxes, any '<' or '>' should be matched.
+
+In the following descriptions, the first example is in the traditional
+syntax, and the second example is in the attribute syntax.
 
 =over
 
 =item *
 
-CnameE>
+CpageE>
+
+=item *
+
+C pEpageE E>
+
+Link to a Perl manual page (e.g., CNet::PingE> or C
+pENet::PingE E>).  Note that C should not contain spaces.
+This syntax is also occasionally used for references to UNIX man pages, as
+in Ccrontab(5)E> or C pEcrontab(5)E E>.
+
+=item *
 
-Link to a Perl manual page (e.g., CNet::PingE>).  Note
-that C should not contain spaces.  This syntax
-is also occasionally used for references to UNIX man pages, as in
-Ccrontab(5)E>.
+Cpage/"section"E> or Cpage/sectionE>
 
 =item *
 
-Cname/"sec"E> or Cname/secE>
+C pEpageE sEsectionE E>
+
+Link to a section in another manual page.  E.g.,
+Cperlsyn/"For Loops"E> or C pEperlsynE sEFor
+LoopsE E>.
+
+=item *
 
-Link to a section in other manual page.  E.g.,
-Cperlsyn/"For Loops"E>
+C/"section"E> or C/sectionE> or C"section"E>
 
 =item *
 
-C/"sec"E> or C/secE> or C"sec"E>
+C sEsectionE E>
 
 Link to a section in this manual page.  E.g.,
-C/"Object Methods"E>
+C/"Object Methods"E> or C sEObject MethodsE E>.
 
 =back
 
-A section is started by the named heading or item.  For
-example, Cperlvar/$.E> or Cperlvar/"$."E> both
-link to the section started by "C<=item $.>" in perlvar.  And
-Cperlsyn/For LoopsE> or Cperlsyn/"For Loops"E>
-both link to the section started by "C<=head2 For Loops>"
-in perlsyn.
-
-To control what text is used for display, you
-use "Ctext|...E>", as in:
+A section is started by the named heading or item.  For example,
+Cperlvar/$.E>, Cperlvar/"$."E>, and C
+pEperlvarE sE$.E E> all link to the section started by
+"C<=item $.>" in perlvar.  Cperlsyn/For LoopsE>,
+Cperlsyn/"For Loops"E>, and C pEperlsynE
+sEFor loopsE E> all link to the section started by "C<=head2
+For Loops>" in perlsyn.
+
+To control what text is used for display under the tradition

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Ronald J Kimball]

On Mon, Mar 15, 2010 at 04:28:15PM -0700, David E. Wheeler wrote:
> On Mar 15, 2010, at 12:19 PM, Ricardo Signes wrote:
> 
> > In other words, the only change /C<{2,}\s+/ has over /C<{1}/ is that it 
> > changes
> > the number of >'s that are needed to close that code.  Fewer >'s than that 
> > are
> > just text.
> > 
> > Frustrating.
> 
> Well, should it change to that? If we can all agree on a proper solution
> and update the spec to be specific, I'm happy to modify Pod::Simple (if I
> can find the tuits) to match that.

I think it should be changed back to the original behavior.  The new
behavior was based on a misreading of the spec.

Ronald

Re: `=item 1. Text` Doesn't Produce Ordered List Item

[Ronald J Kimball]

http://perldoc.perl.org/perlpodspec.html#About-=over...=back-Regions

According to the spec, the asterisk or number should be by itself in the
=item paragraph; additional text should be in a separate verbatim
paragraph.

Ronald