On 06/26/2011 05:34 AM, Shawn H Corey wrote:
On 11-06-25 11:53 PM, Karl Williamson wrote:
In perldiag.pod, there is a line like this
=item Z<>500 Server error
All the other items form a definition list. My guess is that this is to
make sure that the 500 isn't mistaken for a numbered =item in the list.
However, with html, anyway, I don't see any difference in the output
with and without the Z<>, and podchecker ignores the Z<> and says that
the list has mismatched item types.
Can someone explain?
Originally, these are the only valid =item's:
=item *
=item 1
=item 1.
=item definition
These are invalid but frequency occur:
=item * bulleted?
=item 1 numbered?
=item 1. numbered?
They all should be treated as a definition but seldom are. That means,
an `=item Z<> anything` should be treated like a definition.
So then, does the attached patch look ok?
>From ee770e42cab702ec6a23e2a97f0833a051758c55 Mon Sep 17 00:00:00 2001
From: Karl Williamson <[email protected]>
Date: Sun, 26 Jun 2011 11:35:45 -0600
Subject: [PATCH] perlpod: Add info about using Z<> in =items
---
pod/perlpod.pod | 15 ++++++++++++++-
1 files changed, 14 insertions(+), 1 deletions(-)
diff --git a/pod/perlpod.pod b/pod/perlpod.pod
index 068afe4..ee7d715 100644
--- a/pod/perlpod.pod
+++ b/pod/perlpod.pod
@@ -156,7 +156,11 @@ And perhaps most importantly, keep the items consistent: either use
"=item *" for all of them, to produce bullets; or use "=item 1.",
"=item 2.", etc., to produce numbered lists; or use "=item foo",
"=item bar", etc.--namely, things that look nothing like bullets or
-numbers.
+numbers. (If you have a list that contains both: 1) things that don't
+look like bullets nor numbers, plus 2) things that do, you should
+preface the bullet- or number-like items with C<ZE<lt>E<gt>>. See
+L<ZE<lt>E<gt>|/ZE<lt>E<gt> -- a null (zero-effect) formatting code>
+below for an example.)
If you start with bullets or numbers, stick with them, as
formatters use the first "=item" type to decide how to format the
@@ -535,6 +539,15 @@ EE<lt>...E<gt> code sometimes. For example, instead of
the "E<lt>" so they can't be considered
the part of a (fictitious) "NE<lt>...E<gt>" code.
+Another use is to indicate that I<stuff> in C<=item ZE<lt>E<gt>I<stuff...>>
+is not to be considered to be a bullet or number. For example,
+without the C<ZE<lt>E<gt>>, the line
+
+ =item Z<>500 Server error
+
+could possibly be parsed as an item in a numbered list when it isn't
+meant to be.
+
=for comment
This was formerly explained as a "zero-width character". But it in
most parser models, it parses to nothing at all, as opposed to parsing
--
1.7.1
