AW: Z in =item

[Marek Rouchal]

Right - some POD formatters use heuristics like /^\d+/ on what follows =item
to detect whether this is a numbered list. In the specific case of HTML
output, you have 2 choices:
1. always use the full text behind =item and generate a definition list
(dl,dt,dd), except with =item * which should result in a ul
2. or check for ^=item\s+(\d+)\.?$, verify that $1 equals 1,2,3... in
sequence, and if so, generate a ol. If not, fall back to dl. Note that
li allows a value=... attribute, which is however deprecated. See
http://www.w3.org/TR/html4/struct/lists.html#edef-OL

To keep things simple, my personal vote goes to 1.

HTH,

Marek


-Ursprüngliche Nachricht-
Von: Karl Williamson [mailto:pub...@khwilliamson.com] 
Gesendet: Sonntag, 26. Juni 2011 05:53
An: pod-people@perl.org
Betreff: Z in =item

In perldiag.pod, there is a line like this

=item Z500 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?

Re: Z in =item

[Karl Williamson]

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 Z500 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 pub...@khwilliamson.com
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 CZEltEgt.  See
+LZEltEgt|/ZEltEgt -- 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 @@ EElt...Egt code sometimes.  For example, instead of
 the Elt so they can't be considered
 the part of a (fictitious) NElt...Egt code.
 
+Another use is to indicate that Istuff in C=item ZEltEgtIstuff...
+is not to be considered to be a bullet or number.  For example,
+without the CZEltEgt, the line
+
+ =item Z500 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

Re: Z in =item

[Russ Allbery]

Karl Williamson pub...@khwilliamson.com writes:
 On 06/26/2011 05:34 AM, Shawn H Corey wrote:

 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?

I wholeheartedly approve, but before applying this patch to perlpod, we
should probably ensure that the most common tools actually do this, or at
least that we're going to commit to treating this as a bug and making them
do this.  It sounded from your previous message like that may not
currently be the case, and I'm not sure what Pod::Simple does.

-- 
Russ Allbery (r...@stanford.edu) http://www.eyrie.org/~eagle/

Z in =item

[Karl Williamson]

In perldiag.pod, there is a line like this

=item Z500 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?