Re: Z<> in =item

[Russ Allbery]

Karl Williamson  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) 

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 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 
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 CE>.  See
+LE|/ZEE -- 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...E code sometimes.  For example, instead of
 the "E" so they can't be considered
 the part of a (fictitious) "NE...E" code.
 
+Another use is to indicate that I in C<=item ZEEI>
+is not to be considered to be a bullet or number.  For example,
+without the CE>, 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

Re: Z<> in =item

[Shawn H Corey]

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.



--
Just my 0.0002 million dollars worth,
  Shawn

Confusion is the first step of understanding.

Programming is as much about organization and communication
as it is about coding.

The secret to great software:  Fail early & often.

Eliminate software piracy:  use only FLOSS.

Re: AW: Z<> in =item

[Shawn H Corey]

On 11-06-26 05:24 AM, Marek Rouchal wrote:

check for "^=item\s+(\d+)\.?$", verify that $1 equals 1,2,3... in
sequence, and if so, generate a.


So, you can't do:

=over

=item 1.

first

=item 1.

second

=item 1.

third

=back

And let the computer resqeuence the numbers?  And here I thought 
computers were good at dealing with numbers.  Oh, well.



--
Just my 0.0002 million dollars worth,
  Shawn

Confusion is the first step of understanding.

Programming is as much about organization and communication
as it is about coding.

The secret to great software:  Fail early & often.

Eliminate software piracy:  use only FLOSS.

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
(,,), except with "=item *" which should result in a 
2. or check for "^=item\s+(\d+)\.?$", verify that $1 equals 1,2,3... in
sequence, and if so, generate a . If not, fall back to . Note that
 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 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?

Z<> in =item

[Karl Williamson]

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?