Lines Matching full:perl

5 perldocstyle - A style guide for writing Perl's documentation
10 documentation that ships with Perl. This includes the following:
16 The several dozen manual sections whose filenames begin with "C<perl>",
17 such as C<perlobj>, C<perlre>, and C<perlintro>. (And, yes, C<perl>.)
21 The documentation for all the modules included with Perl (as listed by
37 applicable to Perl's core documentation.
40 Perl's manual has a tone and style consistent with that of any other. As
41 with the rest of the Perl project, the language's documentation
47 This will help its readers--especially those new to Perl--to feel
48 more welcome and engaged with Perl's documentation, and this in turn
49 will help the Perl project itself grow stronger through having a larger,
54 Anyone interested in contributing to Perl's core documentation should
57 Programmers documenting their own work apart from the Perl project
59 their work to extend the tone and style of Perl's own manual.
65 contemporary with Perl. This has included Python, Raku, Rust, and the
69 which to launch a review of Perl's reams of extant documentation, with
72 particular to Perl's programming manual.
78 All of Perl's core documentation uses Pod ("Plain Old Documentation"), a
82 with Perl itself.
89 Perl programmers also use Pod to document their own scripts, libraries,
95 Perl's core documentation is written in English, with a preference for
100 We name one style of English for the sake of consistency across Perl's
106 Contributors to Perl's documentation should note that this rule
115 Community-authored translations of Perl's documentation do exist,
116 covering a variety of languages. While the Perl project appreciates
120 That said, keeping Perl's documentation clear, simple, and short has a
124 included with Perl's source distributions provide an exception to this
130 Perl's core documentation files are encoded in UTF-8, and can make use
138 Perl's documentation uses the L<Chicago Manual of
142 for the purposes of documenting Perl, authors should consider CMOS the
146 for contributing to Perl's documentation; the doc team will help
153 =head2 Contributing to Perl's documentation
155 Perl, like any programming language, is only as good as its
156 documentation. Perl depends upon clear, friendly, and thorough
159 reference for experienced Perl programmers. As such, the Perl project
163 Perl accepts documentation contributions through the same open-source
169 This section details specific Pod syntax and style that all core Perl
175 Each individual work of core Perl documentation, whether contained
179 self-contained part of Perl's documentation.)
181 Adhering to these conventions helps Pod formatters present a Perl man
190 Perl man page I<must> present a level-one header named "NAME" (literally),
204 Most Perl man pages also contain a DESCRIPTION section featuring a
210 deep into the inner workings of Perl's regular expression engine should
223 containing hyperlinks to relevant sections of Perl's manual, other Unix
240 In most circumstances, Perl's stand-alone man pages--those contained
242 information about themselves. Their source Pod files are part of Perl's
244 same copyright and license terms as Perl itself. You do not need to
250 given page from L<writing in a voice consistent with the rest of Perl's
254 that ship with Perl. These have their own standards for authorship and
261 Each line within a Perl man page's Pod source file should measure 72
274 For the sake of consistency within and across Perl's man pages, all
279 during a demonstration of how Perl disregards whitespace, for example,
301 referring to any bit of Perl code--even if it is only one character
304 For instance, when referring within an explanatory paragraph to Perl's
309 Use C<CE<lt>...E<gt>> to render all Perl function names in monospace,
314 parentheses. That is, when referring in general to Perl's C<print>
322 Convention specifies a few ones commonly seen throughout Perl's
331 The "generic" argument: any scalar value, or a Perl expression that
384 (outside of Perl's documentation), include its manual section number in
401 the most specific section of a separate page within Perl's
409 Here is an example sentence that mentions Perl's C<say> function, with a
412     In version 5.10, Perl added support for the 
454 Due in part to these limitations, most Perl man pages use neither tables
487 needed for other Perl documentation writers (including your future
493 Perl built-in function, has a handful of formatting rules not seen
494 elsewhere in Perl's documentation.
496 Software used during Perl's build process
498 rules, in order to build separate man pages for each of Perl's
504 header L<"Alphabetical Listing of Perl Functions"|perlfunc/Alphabetical
505 Listing of Perl Functions>. Each function reference is an entry on that
573 each of Perl's man pages should conform to one of the four documentation
583 concept about Perl can ease into a tutorial about it, and later expand
589 Perl's documentation must strive to meet these different situational
598 follow along themselves using their own Perl interpreter. The tutorial
606 Perl reads, playing a significant role in whether they choose
630 A Perl cookbook demonstrates ways that all the tools and techniques
637 The most prominent cookbook pages that ship with Perl itself are its
644 Perl's history of creative cuisine prefers the more kitchen-ready term
655 Perl's own best example of a reference work is C<perlfunc>, the
657 into Perl, with each function's documentation presenting the same kinds
671 needed into some Perl-relevant topic, taking all the time and space
674 student has a Perl interpreter fired up and hungry for immediate examples
675 (as with a tutorial), or specific Perl problems that they need quick
678 Outside of its reference pages, most of Perl's manual belongs to this
680 "C<perl>". A fine example is C<perlsyn>, the Perl Syntax page, which
681 explores the whys and wherefores of Perl's unique syntax in a
685 Perl's explainer pages give authors a chance to explore Perl's penchant
688 the remainder of this guide discusses, the ideal Perl documentation
704 it up into separate pages. That may mean creating a new "C<perl[...]>"
710 Perl's several man pages about Unicode--comprising a short tutorial, a
717 Perl has grown a great deal from its humble beginnings as a tool for
719 Today, a person learning Perl might come from any social or
723 Perl's core documentation must recognize this by making as few
725 should assume that readers of Perl's documentation are smart, curious,
730 =head3 Keep Perl's documentation about Perl
732 Outside of pages tasked specifically with exploring Perl's relationship
734 focus on Perl. Avoid drawing analogies to other technologies that the
737 For example, when documenting one of Perl's built-in functions, write as
748 understanding with practical applications for a Perl programmer, you may
751 documentation or external articles more concerned with examining Perl's
761 For example, Perl loves working with filehandles, and as such that word
762 appears throughout its documentation. A new Perl programmer arriving at
764 "filehandle" is, though. Any Perl man page mentioning filehandles
766 elsewhere in Perl's documentation. If appropriate--for example, in the
798 As much as possible, the language employed by Perl's core documentation
805 "second-order" documentation about Perl, like books, blog entries, and
807 mind. But Perl's own docs should use language as accessible and
813 Perl. No section header should be followed by text reading only "Watch
814 this space", "To be included later", or the like. While Perl's source
820 Take advantage of Perl's regular release cycle. Instead of cluttering
824 issue to address like any other in the Perl project. Let Perl's
854 all comes together using a small, easy-to-read snippet of tested Perl
859 Perl famously gives programmers more than one way to do things. Like any
860 other long-lived programming language, Perl has also built up a large,
866 Whenever it needs to show the rules for a technique which Perl provides
868 practices. And when discussing some part of the Perl toolkit with many
872 The C<open> function, for example, has myriad potential uses within Perl
874 to Perl--turn to this reference because they simply wish to open a
886 For example, a certain Perl function might have an alternate syntax now
890 clarity that modern Perl avoids such structures, and does not recommend
896 programmer new to Perl, who may feel uncertain about learning a complex
899 true picture of how it works in Perl, and boost their own confidence to
905 =head2 Document Perl's present
907 Perl's documentation should stay focused on Perl's present behavior,
918 When some Perl feature changes its behavior, documentation about
923 Since Perl's core documentation is part of Perl's source distribution,
925 source code of Perl itself. Take advantage of this, and update the text
926 boldly when needed. Perl's history remains safe, even when you delete or
929 Perl's docs can acknowledge or discuss former behavior when warranted,
941 Perl features marked as "experimental"--those that generate warnings
945 Perl, but they have unstable interfaces and uncertain future presence.
950 inherent instability; this experimentation can help Perl grow and
959 treat them with the same prominence as Perl's stable features. Using
967 the many years of Perl's lifetime, the language's documentation should
973 Perl did begin life as a deeply personal expression by a single
975 documentation as well. Today, Perl's community understands that the
988 Like the best written works, Perl's documentation has a soul. Get
994 Every line in the docs--whether English sentence or Perl
997 further the reader's knowledge of Perl, set it aside, and consider
1007 to Perl documentation.
1031 =item Perl; perl
1033 The name of the programming language is Perl, with a leading capital
1034 "P", and the remainder in lowercase. (Never "PERL".)
1036 The interpreter program that reads and executes Perl code is named
1037 "C<perl>", in lowercase and in monospace (as with any other command
1041 command-line C<perl> program (as, for example, L<C<perlrun>|perlrun>
1042 does), use "Perl" instead.
1044 =item Perl 5
1046 Documentation need not follow Perl's name with a "5", or any other
1047 number, except during discussions of Perl's history, future plans,
1048 or explicit comparisons between major Perl versions.
1050 Before 2019, specifying "Perl 5" was sometimes needed to distinguish
1051 the language from Perl 6. With the latter's renaming to "Raku", this
1054 =item Perl 6
1058 =item Perl 5 Porters, the; porters, the; p5p
1060 The full name of the team responsible for Perl's ongoing maintenance
1061 and development is "the Perl 5 Porters", and this sobriquet should
1070 executable Perl code. Synonymous with, and preferable to, "script".
1074 Perl's "sister language", whose homepage is L<https://raku.org>.
1076 Previously known as "Perl 6". In 2019, its design team renamed the
1078 Perl. As such, Perl's documentation should always refer to this language
1079 as "Raku" and not "Perl 6".
1087 Perl code's frequently overlooked punctuation mark. Not "semi-colon".
1115 (jmac@jmac.org), under a grant from The Perl Foundation.