From 210b36aa2e9e009554be8970c3315c2658c0384f Mon Sep 17 00:00:00 2001 From: Abhijit Menon-Sen Date: Fri, 16 Nov 2001 12:11:14 +0000 Subject: [PATCH] Doc spellcheck + podcheck From: Autrijus Tang Date: Thu, 15 Nov 2001 22:49:05 -0800 Message-Id: <20011116064905.GA44092@egb.elixus.org> Subject: [PATCH] podcheck+spellcheck, the rest of the story From: Autrijus Tang Date: Fri, 16 Nov 2001 00:42:20 -0800 Message-Id: <20011116084220.GA44295@egb.elixus.org> Subject: Re: [PATCH] podcheck+spellcheck, the rest of the story From: Nicholas Clark Date: Fri, 16 Nov 2001 10:32:01 +0000 Message-Id: <20011116103200.F62891@plum.flirble.org> (Applied after suitable de-mangling.) p4raw-id: //depot/perl@13041 --- pod/perlpodspec.pod | 222 ++++++++++++++++++++++++++-------------------------- 1 file changed, 111 insertions(+), 111 deletions(-) (limited to 'pod/perlpodspec.pod') diff --git a/pod/perlpodspec.pod b/pod/perlpodspec.pod index 46d3ec8707..145309c58f 100644 --- a/pod/perlpodspec.pod +++ b/pod/perlpodspec.pod @@ -121,7 +121,7 @@ But they may span several (non-blank) lines: =for comment Hm, I wonder what it would look like if you tried to write a BNF for Pod from this. - + =head3 Dr. Strangelove, or: How I Learned to Stop Worrying and Love the Bomb @@ -176,11 +176,11 @@ For example: consider the following paragraphs: # <- that's the 0th column =head1 Foo - + Stuff - + $foo->bar - + =cut Here, "=head1 Foo" and "=cut" are command paragraphs because the first @@ -208,7 +208,7 @@ This command indicates that the text in the remainder of the paragraph is a heading. That text may contain formatting codes. Examples: =head1 Object Attributes - + =head3 What B to Do! =item "=pod" @@ -219,9 +219,9 @@ all.) If there is any text in this command paragraph after "=pod", it must be ignored. Examples: =pod - + This is a plain Pod paragraph. - + =pod This text is ignored. =item "=cut" @@ -251,9 +251,9 @@ explained in the L section, further below. Formatting codes are not expanded. Examples: =over 3 - + =over 3.5 - + =over =item "=item" @@ -265,20 +265,20 @@ explained in the L section, further below. Examples: =item - + =item * - + =item * - + =item 14 - + =item 3. - + =item C<< $thing->stuff(I) >> - + =item For transporting us beyond seas to be tried for pretended offenses - + =item He is at this time transporting large armies of foreign mercenaries to complete the works of death, desolation and tyranny, already begun with circumstances of cruelty and perfidy @@ -320,9 +320,9 @@ L=end" Regions>. This is synonymous with: =begin formatname - + text... - + =end formatname That is, it creates a region consisting of a single paragraph; that @@ -517,7 +517,7 @@ starting at line 123: 'Time objects are not...'"). So these two paragraphs: I ...must I be parsed as two paragraphs in italics (with the I @@ -526,7 +526,7 @@ the first paragraph should generate a warning, but that aside, the above code must parse as if it were: I - + Don't make me say it again!E (In SGMLish jargon, all Pod commands are like block-level @@ -645,11 +645,11 @@ version numbers of any modules it might be using to process the Pod. Minimal examples: %% POD::Pod2PS v3.14159, using POD::Parser v1.92 - + - + {\doccomm generated by Pod::Tree::RTF 3.14159 using Pod::Tree 1.08} - + .\" Pod::Man version 3.14159, using POD::Parser version 1.92 Formatters may also insert additional comments, including: the @@ -802,7 +802,7 @@ characters (also defined there by Unicode, with the same meaning), which all Pod formatters must render faithfully. Characters in the ranges 0-31 and 127-159 should not be used (neither as literals, nor as EEnumber> codes), except for the -literal byte-sequences for newline (13, 13 10, or 13), and tab (9). +literal byte-sequences for newline (13, 13 10, or 10), and tab (9). Characters in the range 160-255 refer to Latin-1 characters (also defined there by Unicode, with the same meaning). Characters above @@ -861,7 +861,7 @@ it contains spaces, which aren't alphanumeric characters. This presumably does not I special treatment by a Pod processor; " 0 1 2 3 " doesn't look like a number in any base, so it would presumably be looked up in the table of HTML-like names. Since -there is (and cannot be) an HTML-like entity called " 0 1 2 3 ", +there isn't (and cannot be) an HTML-like entity called " 0 1 2 3 ", this will be treated as an error. However, Pod processors may treat "EE 0 1 2 3 >" or "EEe-acute>" as I invalid, potentially earning a different error message than the @@ -942,7 +942,7 @@ unknown EEthing> sequence that the parser couldn't resolve to anything, renderable or not). It is good practice to map Latin letters with diacritics (like "EEeacute>"/"EE233>") to the corresponding unaccented US-ASCII letters (like a simple character 101, "e"), but -clearly this is often not feasable, and an unrenderable character may +clearly this is often not feasible, and an unrenderable character may be represented as "?", or the like. In attempting a sane fallback (as from EE233> to "e"), Pod formatters may use the %Latin1Code_to_fallback table in L, or @@ -987,7 +987,7 @@ representation that maps best to what the output format demands. =item * -Some processors may find it the C...E> code easiest to +Some processors may find that the C...E> code is easiest to implement by replacing each space in the parse tree under the content of the S, with an NBSP. But note: the replacement should apply I to spaces in I text, but I to spaces in I text. (This @@ -1018,7 +1018,7 @@ character/code and no code for "don't break this stuff across lines". Besides the NBSP character discussed above, implementors are reminded of the existence of the other "special" character in Latin-1, the -"soft hyphen" chararacter, also known as "discretionary hyphen", +"soft hyphen" character, also known as "discretionary hyphen", i.e. C173E> = C0xADE> = CshyE>). This character expresses an optional hyphenation point. That is, it normally renders as nothing, but may render as a @@ -1225,9 +1225,9 @@ as in:

About the -M Operator

- + ... - + About the -M Operator" in somedoc @@ -1434,17 +1434,17 @@ Pod processors should tolerate "=item *" / "=item I" commands with no accompanying paragraph. The middle item is an example: =over - + =item 1 - + Pick up dry cleaning. - + =item 2 - + =item 3 - + Stop by the store. Get Abba Zabas, Stoli, and cheap lawn chairs. - + =back =item * @@ -1458,7 +1458,7 @@ Note that an "=over" ... "=back" region should have some content. That is, authors should not have an empty region like this: =over - + =back Pod processors seeing such a contentless "=over" ... "=back" region, @@ -1479,7 +1479,7 @@ Authors of Pod formatters should note that this construct: =item Porro =item Quisquam Est - + Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. @@ -1494,9 +1494,9 @@ paragraph "Qui dolorem ipsum quia dolor..."; and then an item "Ut Enim". In that case, you'd want to format it like so: Neque - + Porro - + Quisquam Est Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut @@ -1534,7 +1534,7 @@ authors to distinguish which grouping is meant by the above Ut Enim -That is, there should be (at least roughtly) equal spacing between +That is, there should be (at least roughly) equal spacing between items as between paragraphs (although that spacing may well be less than the full height of a line of text). This leaves it to the reader to use (con)textual cues to figure out whether the "Qui dolorem @@ -1554,9 +1554,9 @@ to be used (typically passed through) when rendering the document to a specific format: =begin rtf - + \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par} - + =end rtf The exact same effect could, incidentally, be achieved with a single @@ -1570,11 +1570,11 @@ meaning as one, and Pod parsers may parse it as one.) Another example of a data paragraph: =begin html - + I like PIE! - +
Especially pecan pie! - + =end html If these were ordinary paragraphs, the Pod parser would try to @@ -1620,26 +1620,26 @@ Note that a "=begin I"..."=end I" region where I begins with a colon, I contain commands. For example: =begin :biblio - + Wirth's classic is available in several editions, including: - + =for comment hm, check abebooks.com for how much used copies cost. - + =over - + =item - + Wirth, Niklaus. 1975. I Teubner, Stuttgart. [Yes, it's in German.] - + =item - + Wirth, Niklaus. 1976. I Prentice-Hall, Englewood Cliffs, NJ. - + =back - + =end :biblio Note, however, a "=begin I"..."=end I" @@ -1648,13 +1648,13 @@ directly contain "=head1" ... "=head4" commands, nor "=over", nor "=back", nor "=item". For example, this may be considered invalid: =begin somedata - + This is a data paragraph. - + =head1 Don't do this! - + This is a data paragraph too. - + =end somedata A Pod processor may signal that the above (specifically the "=head1" @@ -1662,48 +1662,48 @@ paragraph) is an error. Note, however, that the following should I be treated as an error: =begin somedata - + This is a data paragraph. - + =cut - + # Yup, this isn't Pod anymore. sub excl { (rand() > .5) ? "hoo!" : "hah!" } - + =pod - + This is a data paragraph too. - + =end somedata And this too is valid: =begin someformat - + This is a data paragraph. - + And this is a data paragraph. - + =begin someotherformat - + This is a data paragraph too. - + And this is a data paragraph too. - + =begin :yetanotherformat =head2 This is a command paragraph! This is an ordinary paragraph! - + And this is a verbatim paragraph! - + =end :yetanotherformat - + =end someotherformat - + Another data paragraph! - + =end someformat The contents of the above "=begin :yetanotherformat" ... @@ -1720,35 +1720,35 @@ other than "=end", "=pod", and "=cut". Also consider this valid structure: =begin :biblio - + Wirth's classic is available in several editions, including: - + =over - + =item - + Wirth, Niklaus. 1975. I Teubner, Stuttgart. [Yes, it's in German.] - + =item - + Wirth, Niklaus. 1976. I Prentice-Hall, Englewood Cliffs, NJ. =back - + Buy buy buy! - + =begin html - + - +
- + =end html - + Now now now! - + =end :biblio There, the "=begin html"..."=end html" region is nested inside @@ -1774,22 +1774,22 @@ contentless "=for I" and "=for :I" paragraphs. I.e., these should be tolerated: =for html - + =begin html - + =end html - + =begin :biblio - + =end :biblio Incidentally, note that there's no easy way to express a data paragraph starting with something that looks like a command. Consider: =begin stuff - + =shazbot - + =end stuff There, "=shazbot" will be parsed as a Pod command "shazbot", not as a data @@ -1804,40 +1804,40 @@ Note that =end commands must match the currently open =begin command. That is, they must properly nest. For example, this is valid: =begin outer - + X - + =begin inner - + Y - + =end inner - + Z - + =end outer while this is invalid: =begin outer - + X - + =begin inner - + Y - + =end outer - + Z - + =end inner - + This latter is improper because when the "=end outer" command is seen, the currently open region has the formatname "inner", not "outer". (It just happens that "outer" is the format name of a higher-up region.) This is an error. Processors must by default report this as an error, and may halt -processing the document containing that error. A corrolary of this is that +processing the document containing that error. A corollary of this is that regions cannot "overlap" -- i.e., the latter block above does not represent a region called "outer" which contains X and Y, overlapping a region called "inner" which contains Y and Z. But because it is invalid (as all @@ -1847,7 +1847,7 @@ anything at all. Similarly, this is invalid: =begin thing - + =end hting This is an error because the region is opened by "thing", and the "=end" @@ -1856,7 +1856,7 @@ tries to close "hting" [sic]. This is also invalid: =begin thing - + =end This is invalid because every "=end" command must have a formatname -- cgit v1.2.1