Changeset 15891 for docs/Perl6/Spec
- Timestamp:
- 04/12/07 18:40:52 (20 months ago)
- Files:
-
- 1 modified
-
docs/Perl6/Spec/Documentation.pod (modified) (36 diffs)
Legend:
- Unmodified
- Added
- Removed
-
docs/Perl6/Spec/Documentation.pod
r14843 r15891 21 21 Maintainer: Damian Conway 22 22 Date: 9 Apr 2005 23 Last Modified: 22 Nov 200623 Last Modified: 14 Feb 2007 24 24 25 25 … … 60 60 would be the source code of the program that the Pod is documenting. Pod 61 61 parsers still parse this text into the internal representation of the 62 file (representing it as a nC<Perldoc::Block::Ambient> block), but62 file (representing it as a C<Perldoc::Block::Ambient> block), but 63 63 renderers will usually ignore such blocks. 64 64 … … 145 145 that is either empty or that contains only whitespace characters. That 146 146 is, a blank line matches the Perl 6 pattern: C</^^ \h* $$/>. Pod uses 147 blank lines , rather than empty lines, as delimiters onthe principle of147 blank lines as delimiters, rather than empty lines, the principle of 148 148 least surprise. 149 149 … … 279 279 B<=begin code :nested(0)> 280 280 281 12 3 4 5 6281 1 2 3 4 5 6 282 282 123456789012345678901234567890123456789012345678901234567890 283 283 |------|-----------------------|---------------------------| … … 323 323 Warning: Do not immerse in water. Do not expose to bright light. 324 324 Do not feed after midnight. 325 325 >> 326 326 =end para 327 327 … … 350 350 related L<configurations|#Block pre-configuration>. For example: 351 351 352 =config head2 :like<head1> :formatt ing<I>352 =config head2 :like<head1> :formatted<I> 353 353 354 354 =end item … … 433 433 =end nested 434 434 435 3 :The Implementation435 3. The Implementation 436 436 =end nested 437 437 … … 479 479 480 480 Ordinary paragraph blocks consist of text that is to be formatted into 481 a document at the current lylevel of nesting, with whitespace481 a document at the current level of nesting, with whitespace 482 482 squeezed, lines filled, and any special L<inline mark-up|#Formatting codes> 483 483 applied. … … 485 485 Ordinary paragraphs consist of one or more consecutive lines of text, 486 486 each of which starts with a non-whitespace character at column 1. The 487 paragraph is terminated by the first blank line or opening block488 directive.For example:487 paragraph is terminated by the first blank line or block directive. 488 For example: 489 489 490 490 =head1 This is a heading block … … 493 493 Its text will be squeezed and 494 494 short lines filled. It is terminated by 495 the first blank line 495 the first blank line. 496 496 497 497 This is another ordinary paragraph. 498 498 Its text will also be squeezed and 499 499 short lines filled. It is terminated by 500 the trailing directive on the next line 501 500 the trailing directive on the next line. 502 501 =head2 This is another heading block 503 502 504 Within a C<=pod>, C<=item>, or C<=nested> block, ordinary paragraphs do not 505 require an explicit marker or delimiters, but there is also an explicit 506 C<para> marker (which may be used anywhere): 507 508 =para 503 Within a C<=pod>, C<=item>, C<=nested>, or C<=END> block, ordinary 504 paragraphs do not require an explicit marker or delimiters, but there is 505 also an explicit C<para> marker (which may be used anywhere): 506 507 =for code :allow<B> 508 B<=para> 509 509 This is an ordinary paragraph. 510 510 Its text will be squeezed and … … 513 513 and likewise the longer C<=for> and C<=begin>/C<=end> forms. For example: 514 514 515 =begin para 515 =for code :allow<B> 516 B<=begin para> 516 517 This is an ordinary paragraph. 517 518 Its text will be squeezed and 518 519 short lines filled. 519 =end para520 B<=end para> 520 521 521 522 As the previous example implies, when any form of explicit C<para> block … … 557 558 558 559 sub loud_update ($who, $status) { 559 say "$who -> $status .";560 say "$who -> $status"; 560 561 561 562 silent_update($who, $status); … … 645 646 (C<K<>> and C<T<>>) to indicate embedded input or output, so you can use 646 647 the block type that indicates the overall purpose of the sample (i.e. is 647 it demonstrating an input operation or an output sequence ) and then use648 it demonstrating an input operation or an output sequence?) and then use 648 649 the "contrasting" formatting code within the block. 649 650 … … 659 660 660 661 Height: 180cm/5'11" 661 Weight: 10 5kg/230lb662 Weight: 104kg/230lb 662 663 Age: 49 663 664 … … 789 790 =end nested 790 791 791 although the numbering scheme is at the discretion of the renderer, so it792 might equally well be rendered:792 although the numbering scheme is entirely at the discretion of the 793 renderer, so it might equally well be rendered: 793 794 794 795 =begin nested … … 840 841 The numbering of successive C<=item1> list items increments 841 842 automatically, but is reset to 1 whenever any other kind of non-ambient 842 Perldoc block appears between t o C<=item1> blocks. For example:843 Perldoc block appears between two C<=item1> blocks. For example: 843 844 844 845 The options are: … … 948 949 E<curren;nbsp;nbsp>'Rithmetic 949 950 951 As with numbering styles, the bulleting strategy used for different levels 952 within a nested list is entirely up to the renderer. 953 950 954 951 955 =head4 Multi-paragraph list items … … 1026 1030 =for code :allow<B> 1027 1031 B<=begin nested> 1028 1029 1032 We are all of us in the gutter,E<NL> 1033 but some of us are looking at the stars! 1030 1034 B<=begin nested> 1031 1035 -- Oscar Wilde 1032 1036 B<=end nested> 1033 1037 B<=end nested> … … 1040 1044 1041 1045 Simple tables can be specified in Perldoc using a C<=table> block. 1042 The table may be given a label using the C<:caption> option. 1046 The table may be given an associated description or title using the 1047 C<:caption> option. 1043 1048 1044 1049 Columns are separated by whitespace, vertical lines (C<|>), or border … … 1220 1225 =LICENCE 1221 1226 =LICENSE 1227 =TITLE 1222 1228 =SECTION 1223 1229 =CHAPTER … … 1249 1255 =begin code 1250 1256 use Perldoc::Parser 1251 1257 1252 1258 my Perldoc::Parser $parser .= new(); 1253 1259 1254 1260 my $tree = $parser.parse($fh); 1255 1261 =end code … … 1271 1277 =begin code :allow< L > 1272 1278 use L<Perldoc::Parser|doc:Perldoc::Parser>; 1273 1279 1274 1280 my Perldoc::Parser $parser .= new(); 1275 1281 1276 1282 my $tree = $parser.parse($fh); 1277 1283 =end code … … 1297 1303 immediately by a set of angle brackets. The brackets contain the text or 1298 1304 data to which the formatting code applies. You can use a set of single 1299 angles (C ´<...>ª), a set of double angles (C<´...ª>), or multiple1300 single-angles (C ´<<<...>>>ª).1305 angles (C�<...>�), a set of double angles (C<�...�>), or multiple 1306 single-angles (C�<<<...>>>�). 1301 1307 1302 1308 Within angle delimiters, you cannot use sequences of the same angle … … 1307 1313 These are errors... 1308 1314 1309 C< $fooB ´<<ªbarB´>>ª>1310 The Perl 5 heredoc syntax was: C< B ´<<ªEND_MARKER >1315 C< $fooB�<<�barB�>>� > 1316 The Perl 5 heredoc syntax was: C< B�<<�END_MARKER > 1311 1317 =end code 1312 1318 … … 1320 1326 1321 1327 =for code :allow<B> 1322 CB< ´>$foo < $barB<ª>1323 The Perl 5 heredoc syntax was: CB< ´> <<END_MARKER B<ª>1328 CB<�>$foo < $barB<�> 1329 The Perl 5 heredoc syntax was: CB<�> <<END_MARKER B<�> 1324 1330 1325 1331 or delimiters with more consecutive angles than your text contains: 1326 1332 1327 1333 =for code :allow<B> 1328 CB ´<<ª$foo < $barB´>>ª1329 The Perl 5 heredoc syntax was: CB ´<<<ª <<END_MARKER B´>>>ª1334 CB�<<�$foo < $barB�>>� 1335 The Perl 5 heredoc syntax was: CB�<<<� <<END_MARKER B�>>>� 1330 1336 1331 1337 A formatting code ends at the matching closing angle bracket(s), or at … … 1387 1393 output, code, and metasyntax: 1388 1394 1389 = item1395 =begin item 1390 1396 The C<T<>> formatting code specifies that the contained text is 1391 1397 B<terminal output>; that is: something that a program might print out. 1392 Such content would typically be rendered in a T<fixed-width font>. The 1393 contents of a C<T<>> code are always L<space-preserved | 1394 #Space-preserving text> (as if they had an implicit C<S<...>> around them). 1395 The C<T<>> code is the inline equivalent of the C<=output> block. 1396 1397 =item 1398 Such content would typically be rendered in a T<fixed-width font> or with 1399 C< <code>...</code> > tags. The contents of a C<T<>> code are always 1400 L<space-preserved | #Space-preserving text> (as if they had an implicit 1401 C<S<...>> around them). The C<T<>> code is the inline equivalent of the 1402 C<=output> block. 1403 =end item 1404 1405 =begin item 1398 1406 The C<K<>> formatting code specifies that the contained text is 1399 1407 B<keyboard input>; that is: something that a user might type in. Such 1400 content would typically be rendered in a K<fixed-width font>, preferably a 1401 different font from that used for the C<T<>> formatting code. The 1402 contents of a C<K<>> code are always L<space-preserved| 1403 #Space-preserving text>. The C<K<>> code is the inline equivalent of the 1404 C<=input> block. 1408 content would typically be rendered in a K<fixed-width font> (preferably a 1409 different font from that used for the C<T<>> formatting code) or with 1410 C< <kbd>...</kbd> > tags. The contents of a C<K<>> code are always 1411 L<space-preserved| #Space-preserving text>. The C<K<>> code is the 1412 inline equivalent of the C<=input> block. 1413 =end item 1405 1414 1406 1415 =begin item 1407 1416 The C<C<>> formatting code specifies that the contained text is B<code>; 1408 1417 that is, something that might appear in a program or specification. Such 1409 content would typically be rendered in a C<fixed-width font> ,preferably1418 content would typically be rendered in a C<fixed-width font> (preferably 1410 1419 a different font from that used for the C<T<>> or C<K<>> formatting 1411 codes . The contents of a C<C<>> code are L<space-preserved|1412 #Space-preserving text> and L<verbatim| #Verbatim text>.1420 codes) or with C< <samp>...</samp> > tags. The contents of a C<C<>> code 1421 are L<space-preserved| #Space-preserving text> and L<verbatim| #Verbatim text>. 1413 1422 The C<C<>> code is the inline equivalent of the C<=code> block. 1414 1423 … … 1449 1458 =end code 1450 1459 1451 Typically replaceables would be rendered in fixed-width italics. The1452 font used should be the same as that used for the C<C<>> code, unless 1453 the C< R<>> is inside a C<K<>> or C<T<>> code (or the equivalent1454 C<=input> or C<=output> blocks), in which case their respective fonts 1455 should be used.1460 Typically replaceables would be rendered in R<fixed-width italics> or with 1461 C< <var>...</var> > tags. The font used should be the same as that used for 1462 the C<C<>> code, unless the C<R<>> is inside a C<K<>> or C<T<>> code (or 1463 the equivalent C<=input> or C<=output> blocks), in which case their 1464 respective fonts should be used. 1456 1465 =end item 1457 1466 … … 1502 1511 1503 1512 =for code :allow<B> 1504 In Perl 5 POD, the B ´V<ªZ<>>B´>ªcode was widely used to break up text1513 In Perl 5 POD, the B�V<�Z<>B�>� code was widely used to break up text 1505 1514 that would otherwise be considered mark-up. 1506 1515 … … 1509 1518 1510 1519 =for code :allow<B> 1511 In Perl 5 POD, the B ´C<ªZ<>B´>ªcode was widely used to break up text1520 In Perl 5 POD, the B�C<�Z<>B�>� code was widely used to break up text 1512 1521 that would otherwise be considered mark-up. 1513 1522 … … 1574 1583 1575 1584 =for code :allow<B> 1576 Please forward bug reports to L<B<mailto:devnull@ megagigatera.com>>1585 Please forward bug reports to L<B<mailto:devnull@rt.cpan.org>> 1577 1586 1578 1587 =end item … … 1597 1606 view the results. See also: L<B<doc:perldata>>. 1598 1607 1608 =end item 1609 1610 =begin item :term<C<defn:>> 1611 1612 A link to the L<definition|#Definitions> of the specified term within 1613 the current document. For example: 1614 1615 =for code :allow<B> 1616 He was highly prone to D<lexiphania>: an unfortunate proclivity for 1617 employing sesquipedalian words (such as "proclivity", 1618 "sesquipedalian", and indeed "lexiphania"). 1619 1620 and later, to link back to the definition 1621 1622 To treat his chronic L<defn:lexiphania> the doctor prescribed an 1623 immediate glossectomy or, if that proved ineffective, a complete 1624 cephalectomy. 1625 1599 1626 =end item 1600 1627 … … 1645 1672 =head3 Placement links 1646 1673 1647 A second kind of link --the C<P<>> or B<placement link>--works in the1674 A second kind of linkE<mdash>the C<P<>> or B<placement link>E<mdash>works in the 1648 1675 opposite direction. Instead of directing focus out to another document, 1649 1676 it allows you to draw the contents of another document into your own. … … 1661 1688 1662 1689 =DISCLAIMER 1663 P<http://www. megagigatera.com/std/disclaimer.txt>1690 P<http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt> 1664 1691 1665 1692 might produce: … … 1668 1695 B<Copyright> 1669 1696 1670 This document is copyright (c) MegaGigaTera Corp, 2006. All rights reserved.1697 This document is copyright (c) MegaGigaTeraPetaCorp, 2006. All rights reserved. 1671 1698 1672 1699 B<Disclaimer> … … 1692 1719 B<Disclaimer> 1693 1720 1694 See: L<http://www. megagigatera.com/std/disclaimer.txt>1721 See: L<http://www.MegaGigaTeraPetaCorp.com/std/disclaimer.txt> 1695 1722 =end nested 1696 1723 … … 1699 1726 1700 1727 Any text enclosed in an C<S<>> code is formatted normally, except that 1701 every whitespace character in it --including any newline--is preserved.1728 every whitespace character in itE<mdash>including any newlineE<mdash>is preserved. 1702 1729 These characters are also treated as being non-breaking (except for the 1703 1730 newlines, of course). For example:
