Re: Z<> in =item
[email protected] (Karl Williamson)
| Newsgroups | perl.pod-people |
|---|---|
| Message-ID | <[email protected]> |
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?
0001-perlpod-Add-info-about-using-Z-in-items.patch
(text/x-patch, 1.8 KB)
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