On 07/20/2010 10:03 AM, Ronald J Kimball wrote:
[...]
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.
[...]
As preface: I, as author of perlpodspec, hereby disclaim any special
insight into =item except to note that I dimly remember... uh...
remember...
Well, the fact that there's a whole section on it in the spec is hint
enough that the issue is a mess. So yes, it is possible for !!EVEN
ME!! to read the spec wrong. (Cf. my book /Death and Return of the
Author/, 3e, 2008 Edinburgh University Press)...
But, if the question of the legality of "=item 1 Stuff Tra La" is
open, lessee what perlpodspec says...
Says that an =over...=back region should consist of one of several
possibilities, one of which is:
«
An "=over" ... "=back" region containing only "=item [text]" commands,
each one (or each group of them) followed by some number of
ordinary/verbatim paragraphs, other nested "=over" ... "=back"
regions, or "=for..." paragraphs, and "=begin"..."=end" regions.
The "=item [text]" paragraph should not match
"m/\A=item\s+\d+\.?\s*\z/" or "m/\A=item\s+\*\s*\z/", nor should it
match just "m/\A=item\s*\z/".
»
So, it seems that this:
=item 1 Stuff Tra La
and even this
=item 1. Stuff Tra La
...actually is legal. Since it isn't "=item 1" or "=item 1." (note
the \z's in the above regexps) or "=item", we fall thru to considering
it "=item [text]", which just happens to begin with a digit.
BUT YES, is not, and should not, produce an ordered list item.
So, this means that somebody's gonna get
* 1 Stuff Tra La
or
1 Stuff Tra La
where they /might/ have expected
1 Stuff Tra La
But we have "degraded gracefully" (a fine life goal), and no text has
disappeared. And it's not as if this is the point where the
institution of =over...=back falls from typographic perfection into a
splattered disarray!
(Incidentally, in writing perlpodspec, I considered expressing those
difficult regexps with the "x" switch, in as preformatted sections:
m<
...stuff...
...also... # helpful comments
>x
...but, well, I didn't. I think it was just too noisy on the page.
Conversely, I regret that having them in their current format is so
dense. The large print giveth and the fine print taketh away-- in a
rather literal sense in this case.)
Also, to illustrate the problem while FEEDING YOUR FACES, take the
following and compare processing it with pod2html versus perldoc -o html
=head1 Rather Easy Hummus
(Adapted from a recipe by Ralph Baccash (1937-2000),
heartily missed.)
=head2 Ingredients
=over
=item 6 tablespoons of tahini
=item 4 tablespoons of olive oil
=item 5 big cloves of garlic, chopped fine
=item The juice of two smallish lemons
(Adjust to taste, and depending on how
juicy the lemons are)
=item salt to taste
=item pepper to taste
=item onion powder to taste
=item pinch of coriander powder (optional)
=item big pinch of cumin
=back
I<B<Then:>>
=over
=item 2 16oz cans of "great northern" beans, or cannellini.
That is where every classic hummus recipe would have
garbanzos. However, peeling the garbanzos is a bother, and
if you don't peel them, the texture is a bit off. In my
experience, substituting either of these varieties of small
white beans is I<indistinguishable> from using laboriously
peeled garbanzos.
=item parsley, or Italian parsley (optional)
=item chili powder (I prefer a mix of ancho and chipotle)
=item a bit more olive oil
=back
=head2 Preparation:
Drain one of the cans of beans, discarding the juice. Drain
the other, reserving the juice. With smaller beans (unlike
garbanzos), "draining" is a very relative concept-- I
wouldn't insist on rinsing them until there's no juice on
them.
Now, in a blender, combine everything in the above list,
starting at the top, stopping at (but including) the cumin.
Add one-third of the can's worth of the juice that you
reserved. Blend very well. (For lack of a blender, I've
done okay using a Braun hand-mixer.)
Start adding the beans little by little, and keep blending,
and increasing speeds until very smooth. If you want to
make the mix less viscous, add more of the reserved juice.
Adjust the seasoning as needed.
Cover with chopped parsley, and a thin layer of olive oil.
The parsley is more or less optional, but the olive oil is
necessary, to keep the hummus from discoloring. Possibly
sprinkle with chili powder.
Serve at about room temperature, with warm pitas. Possible
garnishes include olives, peperoncini, tomato wedges.
Variations on this recipe consist of adding or substituting
other spices. The beans, tahini, lemon juice, and oil are
the only really core ingredients, and note that their
quantities are approximate.
For more good recipes along these lines, see:
Karaoglan, Aida. 1992. I<Food for the Vegetarian:
Traditional Lebanese Recipes>. Interlink Books,
New York. ISBN 1-56656-105-1.
L<http://www.amazon.com/dp/1566561051>
Also, I hear they have recipes on the Internets now.
=head2 Secret Substitution
"Sabra" brand hummus, if your supermarket carries it, is
about 80% as good as making hummus from scratch according to
the above. "Athenos" brand hummus is, in my experience,
unspeakably bad.
=head2 Author
Sean M. Burke, C<[email protected]>
=cut
Note: For normal use, I would probably use "=item *" instead of what I
did above, but... maybe I wouldn't. My moods are fickle!
Oh, and hey, /Death and Return of the Author/ is by the other Sean
Burke, not me. Hm, more self-referentiality.
