{
    "mode": "man",
    "parameter": "perldocstyle",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/perldocstyle/1/json",
    "generated": "2026-08-24T10:48:41Z",
    "sections": {
        "NAME": {
            "content": "perldocstyle - A style guide for writing Perl's documentation\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This document is a guide for the authorship and maintenance of the documentation that ships\nwith Perl. This includes the following:\n\n•   The several dozen manual sections whose filenames begin with \"\"perl\"\", such as \"perlobj\",\n\"perlre\", and \"perlintro\". (And, yes, \"perl\".)\n\n•   The documentation for all the modules included with Perl (as listed by \"perlmodlib\").\n\n•   The  hundreds  of  individually  presented reference sections derived from the \"perlfunc\"\nfile.\n\nThis guide will hereafter  refer  to  user-manual  section  files  as  man  pages,  per  Unix\nconvention.\n",
            "subsections": [
                {
                    "name": "Purpose of this guide",
                    "content": "This  style  guide  aims  to  establish standards, procedures, and philosophies applicable to\nPerl's core documentation.\n\nAdherence to these standards will help ensure that any one part of Perl's manual has  a  tone\nand  style  consistent  with  that  of  any  other. As with the rest of the Perl project, the\nlanguage's documentation collection is an open-source project authored over a long period  of\ntime  by  many  people.  Maintaining  consistency across such a wide swath of work presents a\nchallenge; this guide provides a foundation to help mitigate this difficulty.\n\nThis will help its readers--especially those new to Perl--to feel more  welcome  and  engaged\nwith  Perl's  documentation, and this in turn will help the Perl project itself grow stronger\nthrough having a larger, more diverse, and more confident population of knowledgeable users.\n"
                },
                {
                    "name": "Intended audience",
                    "content": "Anyone interested in contributing to Perl's core documentation should familiarize  themselves\nwith the standards outlined by this guide.\n\nProgrammers  documenting their own work apart from the Perl project itself may also find this\nguide worthwhile, especially if they wish their work to extend the tone and style  of  Perl's\nown manual.\n"
                },
                {
                    "name": "Status of this document",
                    "content": "This guide was initially drafted in late 2020, drawing from the documentation style guides of\nseveral  open-source  technologies  contemporary  with  Perl. This has included Python, Raku,\nRust, and the Linux kernel.\n\nThe author intends to see this guide used as starting place from which to launch a review  of\nPerl's  reams of extant documentation, with the expectation that those conducting this review\nshould grow and modify this guide as needed  to  account  for  the  requirements  and  quirks\nparticular to Perl's programming manual.\n"
                }
            ]
        },
        "FUNDAMENTALS": {
            "content": "",
            "subsections": [
                {
                    "name": "Choice of markup: Pod",
                    "content": "All  of  Perl's  core  documentation  uses  Pod  (\"Plain Old Documentation\"), a simple markup\nlanguage, to format its  source  text.  Pod  is  similar  in  spirit  to  other  contemporary\nlightweight  markup  technologies,  such as Markdown and reStructuredText, and has a decades-\nlong shared history with Perl itself.\n\nFor a comprehensive reference to Pod syntax, see \"perlpod\".  For the  sake  of  reading  this\nguide,  familiarity  with  the  Pod  syntax for section headers (\"=head2\", et cetera) and for\ninline text formatting (\"C<like this>\") should suffice.\n\nPerl programmers also use Pod to document their own scripts, libraries, and modules. This use\nof Pod has its own style guide, outlined by \"perlpodstyle\".\n"
                },
                {
                    "name": "Choice of language: American English",
                    "content": "Perl's core documentation is written in English, with a preference for American  spelling  of\nwords  and  expression  of  phrases. That means \"color\" over \"colour\", \"math\" versus \"maths\",\n\"the team has decided\" and not \"the team have decided\", and so on.\n\nWe name one style of English for the sake of consistency across Perl's documentation, much as\na software project might declare a four-space indentation standard--even  when  that  doesn't\naffect how well the code compiles. Both efforts result in an easier read by avoiding jarring,\nmid-document changes in format or style.\n\nContributors  to  Perl's  documentation  should  note  that this rule describes the ultimate,\npublished output of the project, and does not prescribe the  dialect  used  within  community\ncontributions.   The   documentation  team  enthusiastically  welcomes  any  English-language\ncontributions, and will actively assist in Americanizing spelling and style when warranted.\n\nOther languages and translations\n\nCommunity-authored translations of Perl's documentation  do  exist,  covering  a  variety  of\nlanguages.  While  the  Perl  project appreciates these translation efforts and promotes them\nwhen applicable, it does not officially support or maintain any of them.\n\nThat said, keeping Perl's documentation clear, simple, and short has a welcome side effect of\naiding any such translation project.\n\n(Note that the Chinese, Japanese, and  Korean-language  README  files  included  with  Perl's\nsource  distributions  provide  an  exception to this choice of language--but these documents\nfall outside the scope of this guide.)\n"
                },
                {
                    "name": "Choice of encoding: UTF-8",
                    "content": "Perl's core documentation files are encoded in UTF-8, and can make use of the full  range  of\ncharacters this encoding allows.\n\nAs  such,  every core doc file (or the Pod section of every core module) should commence with\nan \"=encoding utf8\" declaration.\n"
                },
                {
                    "name": "Choice of underlying style guide: CMOS",
                    "content": "Perl's documentation uses the Chicago Manual of Style  <https://www.chicagomanualofstyle.org>\n(CMOS), 17th Edition, as its baseline guide for style and grammar. While the document you are\ncurrently  reading endeavors to serve as an adequate stand-alone style guide for the purposes\nof documenting Perl, authors should consider CMOS the fallback authority  for  any  pertinent\ntopics not covered here.\n\nBecause  CMOS  is not a free resource, access to it is not a prerequisite for contributing to\nPerl's documentation; the  doc  team  will  help  contributors  learn  about  and  apply  its\nguidelines  as  needed.  However,  we  do  encourage  anyone  interested  in  significant doc\ncontributions to obtain or at least read through CMOS. (Copies are likely  available  through\nmost public libraries, and CMOS-derived fundamentals can be found online as well.)\n"
                },
                {
                    "name": "Contributing to Perl's documentation",
                    "content": "Perl,  like any programming language, is only as good as its documentation. Perl depends upon\nclear, friendly, and thorough documentation in order to welcome brand-new  users,  teach  and\nexplain the language's various concepts and components, and serve as a lifelong reference for\nexperienced  Perl  programmers.  As  such, the Perl project welcomes and values all community\nefforts to improve the language's documentation.\n\nPerl accepts documentation contributions through the same  open-source  project  pipeline  as\ncode contributions. See \"perlhack\" for more information.\n"
                }
            ]
        },
        "FORMATTING AND STRUCTURE": {
            "content": "This  section  details  specific Pod syntax and style that all core Perl documentation should\nadhere to, in the interest of consistency and readability.\n",
            "subsections": [
                {
                    "name": "Document structure",
                    "content": "Each individual work of core Perl documentation, whether contained within a \".pod\" file or in\nthe Pod section of a standard code module, patterns its structure after a number of long-time\nUnix man page conventions. (Hence this guide's use of \"man page\" to refer to  any  one  self-\ncontained part of Perl's documentation.)\n\nAdhering  to  these  conventions  helps  Pod  formatters present a Perl man page's content in\ndifferent contexts--whether a terminal, the  web,  or  even  print.  Many  of  the  following\nrequirements  originate  with  \"perlpodstyle\", which derives its recommendations in turn from\nthese well-established practices.\n\nName\n\nAfter its \"=encoding utf8\" declaration, a Perl man page must present a level-one header named\n\"NAME\" (literally), followed by a paragraph containing the  page's  name  and  a  very  brief\ndescription.\n\nThe first few lines of a notional page named \"perlpodexample\":\n\n=encoding utf8\n\n=head1 NAME\n\nperlpodexample - An example of formatting a manual page's title line\n\nDescription and synopsis\n\nMost  Perl  man  pages  also  contain  a  DESCRIPTION  section  featuring  a  summary  of, or\nintroduction to, the document's content and purpose.\n\nThis section should also, one way or another, clearly identify the  audience  that  the  page\naddresses, especially if it has expectations about the reader's prior knowledge. For example,\na man page that dives deep into the inner workings of Perl's regular expression engine should\nstate  its  assumptions  up front--and quickly redirect readers who are instead looking for a\nmore basic reference or tutorial.\n\nReference pages, when appropriate, can precede the DESCRIPTION with a SYNOPSIS  section  that\nlists,  within  one or more code blocks, some very brief examples of the referenced feature's\nuse. This section should show a handful of common-case  and  best-practice  examples,  rather\nthan an exhaustive list of every obscure method or alternate syntax available.\n\nOther sections and subsections\n\nPages  should  conclude,  when  appropriate, with a SEE ALSO section containing hyperlinks to\nrelevant sections of Perl's manual, other Unix man pages, or appropriate web pages. Hyperlink\neach such cross-reference via \"L<...>\".\n\nWhat other sections to include depends entirely upon the topic at hand.  Authors should  feel\nfree  to  include  further  \"=head1\"-level  sections,  whether  other standard ones listed by\n\"perlpodstyle\", or ones specific to the page's topic; in either case, render these  top-level\nheadings in all-capital letters.\n\nYou  may  then  include  as  many subsections beneath them as needed to meet the standards of\nclarity, accessibility, and cross-reference affinity suggested elsewhere in this guide.\n\nAuthor and copyright\n\nIn most circumstances, Perl's stand-alone man pages--those contained within \".pod\"  files--do\nnot  need  to include any copyright or license information about themselves. Their source Pod\nfiles are part of Perl's own core software repository, and that already covers them under the\nsame copyright and license terms as Perl itself.  You  do  not  need  to  include  additional\n\"LICENSE\" or \"COPYRIGHT\" sections of your own.\n\nThese  man pages may optionally credit their primary author, or include a list of significant\ncontributors, under \"AUTHOR\" or \"CONTRIBUTORS\" headings. Note that the presence  of  authors'\nnames  does  not  preclude  a  given page from writing in a voice consistent with the rest of\nPerl's documentation.\n\nNote that these guidelines do not apply to the core software modules  that  ship  with  Perl.\nThese  have  their  own  standards  for  authorship  and  copyright  statements,  as found in\n\"perlpodstyle\".\n"
                },
                {
                    "name": "Formatting rules",
                    "content": "Line length and line wrap\n\nEach line within a Perl man page's Pod source file should measure 72 characters or  fewer  in\nlength.\n\nPlease break paragraphs up into blocks of short lines, rather than \"soft wrapping\" paragraphs\nacross hundreds of characters with no line breaks.\n\nCode blocks\n\nJust  like  the  text  around  them,  all  code  examples  should be as short and readable as\npossible, displaying no more complexity than absolutely necessary to illustrate  the  concept\nat hand.\n\nFor  the  sake of consistency within and across Perl's man pages, all examples must adhere to\nthe code-layout principles set out by \"perlstyle\".\n\nSample code should deviate from these standards only when necessary: during  a  demonstration\nof  how  Perl  disregards  whitespace,  for  example,  or to temporarily switch to two-column\nindentation for an unavoidably verbose illustration.\n\nYou may include comments within example code to further clarify or label the code's  behavior\nin-line.  You may also use comments as placeholder for code normally present but not relevant\nto the current topic, like so:\n\nwhile (my $line = <$fh>) {\n#\n# (Do something interesting with $line here.)\n#\n}\n\nEven the simplest code blocks often require the use of  example  variables  and  subroutines,\nwhose names you should choose with care.\n\nInline code and literals\n\nWithin  a  paragraph  of  text,  use  \"C<...>\"  when  quoting or referring to any bit of Perl\ncode--even if it is only one character long.\n\nFor instance, when referring within an explanatory paragraph to Perl's  operator  for  adding\ntwo numbers together, you'd write \"\"C<+>\"\".\n\nFunction names\n\nUse \"C<...>\" to render all Perl function names in monospace, whenever they appear in text.\n\nUnless you need to specifically quote a function call with a list of arguments, do not follow\na  function's  name  in  text  with  a  pair of empty parentheses. That is, when referring in\ngeneral to Perl's \"print\" function, write it as \"\"print\"\", not \"print()\".\n\nFunction arguments\n\nRepresent functions' expected arguments in all-caps, with no sigils, and  using  \"C<...>\"  to\nrender  them  in  monospace.  These arguments should have short names making their nature and\npurpose  clear.   Convention  specifies  a  few  ones   commonly   seen   throughout   Perl's\ndocumentation:\n\n•   EXPR\n\nThe \"generic\" argument: any scalar value, or a Perl expression that evaluates to one.\n\n•   ARRAY\n\nAn array, stored in a named variable.\n\n•   HASH\n\nA hash, stored in a named variable.\n\n•   BLOCK\n\nA curly-braced code block, or a subroutine reference.\n\n•   LIST\n\nAny  number  of  values,  stored across any number of variables or expressions, which the\nfunction will \"flatten\" and treat as a single list.  (And  because  it  can  contain  any\nnumber of variables, it must be the last argument, when present.)\n\nWhen  possible,  give  scalar arguments names that suggest their purpose among the arguments.\nSee, for example, \"substr\"'s documentation, whose listed arguments include \"EXPR\",  \"OFFSET\",\n\"LENGTH\", and \"REPLACEMENT\".\n\nApostrophes, quotes, and dashes\n\nIn Pod source, use straight quotes, and not \"curly quotes\":  \"Like\nthis\", not “like this”. The same goes for apostrophes:  Here's a\npositive example, and here’s a negative one.\n\nRender em dashes as two hyphens--like this:\n\nRender em dashes as two hyphens--like this.\n\nLeave  it up to formatters to reformat and reshape these punctuation marks as best fits their\nrespective target media.\n\nUnix programs and C functions\n\nWhen referring to a Unix program or C function with its  own  man  page  (outside  of  Perl's\ndocumentation),  include its manual section number in parentheses. For example: malloc(3), or\nmkdir(1).\n\nIf mentioning this program for the first time within a man page or section, make it  a  cross\nreference, e.g. \"L<malloc(3)>\".\n\nDo not otherwise style this text.\n\nCross-references and hyperlinks\n\nMake generous use of Pod's \"L<...>\" syntax to create hyperlinks to other parts of the current\nman  page,  or  to other documents entirely -- whether elsewhere on the reader's computer, or\nsomewhere on the internet, via URL.\n\nUse \"L<...>\" to link to another section of the current man page when mentioning it, and  make\nuse  of  its  page-and-section syntax to link to the most specific section of a separate page\nwithin Perl's documentation. Generally, the first time you  refer  to  a  specific  function,\nprogram,  or  concept  within  a  certain  page  or  section,  consider  linking  to its full\ndocumentation.\n\nHyperlinks do not supersede other formatting required by this guide; Pod allows  nested  text\nformats, and you should use this feature as needed.\n\nHere  is  an  example  sentence  that  mentions  Perl's  \"say\"  function,  with a link to its\ndocumentation section within the \"perlfunc\" man page:\n\nIn version 5.10, Perl added support for the\nL<C<say>|perlfunc/say FILEHANDLE LIST> function.\n\nNote the use of the vertical pipe (\"\"|\"\") to separate how the link  will  appear  to  readers\n(\"\"C<say>\"\") from the full page-and-section specifier that the formatter links to.\n\nTables and diagrams\n\nPod  does  not  officially support tables. To best present tabular data, include the table as\nboth HTML and plain-text representations--the latter as an indented code block. Use  \"=begin\"\n/ \"=end\" directives to target these tables at \"html\" and \"text\" Pod formatters, respectively.\nFor example:\n\n=head2 Table of fruits\n\n=begin text\n\nName           Shape           Color\n=====================================\nApple          Round           Red\nBanana         Long            Yellow\nPear           Pear-shaped     Green\n\n=end text\n\n=begin html\n\n<table>\n<tr><th>Name</th><th>Shape</th><th>Color</th></tr>\n<tr><td>Apple</td><td>Round</td><td>Red</td></tr>\n<tr><td>Banana</td><td>Long</td><td>Yellow</td></tr>\n<tr><td>Pear</td><td>Pear-shaped</td><td>Green</td></tr>\n</table>\n\n=end html\n\nThe  same  holds  true for figures and graphical illustrations. Pod does not natively support\ninline graphics, but you can mix HTML \"<img>\" tags with monospaced  text-art  representations\nof those images' content.\n\nDue  in  part to these limitations, most Perl man pages use neither tables nor diagrams. Like\nany other tool in your documentation toolkit, however, you may consider their inclusion  when\nthey would improve an explanation's clarity without adding to its complexity.\n"
                },
                {
                    "name": "Adding comments",
                    "content": "Like any other kind of source code, Pod lets you insert comments visible only to other people\nreading  the  source directly, and ignored by the formatting programs that transform Pod into\nvarious human-friendly output formats (such as HTML or PDF).\n\nTo comment Pod text, use the \"=for\" and \"=begin\" / \"=end\" Pod directives, aiming  them  at  a\n(notional) formatter called \"\"comment\"\". A couple of examples:\n\n=for comment Using \"=for comment\" like this is good for short,\nsingle-paragraph comments.\n\n=begin comment\n\nIf you need to comment out more than one paragraph, use a\n=begin/=end block, like this.\n\nNone of the text or markup in this whole example would be visible to\nsomeone reading the documentation through normal means, so it's\ngreat for leaving notes, explanations, or suggestions for your\nfellow documentation writers.\n\n=end comment\n\nIn  the  tradition of any good open-source project, you should make free but judicious use of\ncomments to leave in-line \"meta-documentation\" as needed for other Perl documentation writers\n(including your future self).\n"
                },
                {
                    "name": "Perlfunc has special rules",
                    "content": "The \"perlfunc\" man page, an exhaustive reference of  every  Perl  built-in  function,  has  a\nhandful of formatting rules not seen elsewhere in Perl's documentation.\n\nSoftware  used  during  Perl's  build  process (Pod::Functions) parses this page according to\ncertain rules, in order to build separate man pages for each of Perl's functions, as well  as\nachieve  other indexing effects. As such, contributors to perlfunc must know about and adhere\nto its particular rules.\n\nMost of the perfunc man page comprises a single list, found under  the  header  \"Alphabetical\nListing  of  Perl Functions\". Each function reference is an entry on that list, made of three\nparts, in order:\n\n1.  A list of \"=item\" lines which each demonstrate, in template format, a way  to  call  this\nfunction.  One  line  should  exist  for every combination of arguments that the function\naccepts (including no arguments at all, if applicable).\n\nIf modern best practices prefer certain ways to invoke the  function  over  others,  then\nthose ways should lead the list.\n\nThe  first  item of the list should be immediately followed by one or more \"X<...>\" terms\nlisting index-worthy topics; if nothing else, then the name  of  the  function,  with  no\narguments.\n\n2.  A  \"=for\"  line,  directed at \"Pod::Functions\", containing a one-line description of what\nthe function does. This is written as a phrase, led with an imperative verb, with neither\nleading capitalization nor ending punctuation. Examples include \"quote a list  of  words\"\nand \"change a filename\".\n\n3.  The function's definition and reference material, including all explanatory text and code\nexamples.\n\nComplex  functions  that  need  their  text divided into subsections (under the principles of\n\"Apply section-breaks and examples generously\") may do so by  using  sublists,  with  \"=item\"\nelements as header text.\n\nA  fictional  function  \"\"myfunc\"\", which takes a list as an optional argument, might have an\nentry in perlfunc shaped like this:\n\n=item myfunc LIST\nX<myfunc>\n\n=item myfunc\n\n=for Pod::Functions demonstrate a function's perlfunc section\n\n[ Main part of function definition goes here, with examples ]\n\n=over\n\n=item Legacy uses\n\n[ Examples of deprecated syntax still worth documenting ]\n\n=item Security considerations\n\n[ And so on... ]\n\n=back\n"
                }
            ]
        },
        "TONE AND STYLE": {
            "content": "",
            "subsections": [
                {
                    "name": "Apply one of the four documentation modes",
                    "content": "Aside from \"meta\" documentation such as \"perlhist\" or  \"perlartistic\",  each  of  Perl's  man\npages  should conform to one of the four documentation \"modes\" suggested by The Documentation\nSystem  by  Daniele  Procida  <https://documentation.divio.com>.  These  include   tutorials,\ncookbooks, explainers, and references--terms that we define in further detail below.\n\nEach  mode  of  documentation  speaks  to  a different audience--not just people of different\nbackgrounds and skill levels, but individual readers whose needs from language  documentation\ncan  shift  depending  upon context. For example, a programmer with plenty of time to learn a\nnew concept about Perl can ease into a tutorial about it, and later  expand  their  knowledge\nfurther  by studying an explainer. Later, that same programmer, wading knee-deep in live code\nand needing only to look up some function's exact syntax, will want to reach for a  reference\npage instead.\n\nPerl's documentation must strive to meet these different situational expectations by limiting\neach  man  page  to  a  single  mode. This helps writers ensure they provide readers with the\ndocumentation needed or expected, despite ever-evolving situations.\n\nTutorial\n\nA tutorial man page focuses on learning, ideally by doing. It presents the reader with small,\ninteresting examples that allow  them  to  follow  along  themselves  using  their  own  Perl\ninterpreter.   The  tutorial  inspires  comprehension  by  letting  its  readers  immediately\nexperience (and experiment  on)  the  concept  in  question.  Examples  include  \"perlxstut\",\n\"perlpacktut\", and \"perlretut\".\n\nTutorial  man  pages  must strive for a welcoming and reassuring tone from their outset; they\nmay very well be the first things that a newcomer to Perl reads, playing a  significant  role\nin  whether  they choose to stick around. Even an experienced programmer can benefit from the\nsense of courage imparted by a strong tutorial about a more advanced topic. After  completing\na  tutorial,  a  reader should feel like they've been led from zero knowledge of its topic to\nhaving an invigorating spark of basic understanding, excited to  learn  more  and  experiment\nfurther.\n\nTutorials  can  certainly  use  real-world examples when that helps make for clear, relatable\ndemonstrations, so long as they keep the focus on  teaching--more  practical  problem-solving\nshould be left to the realm of cookbooks (as described below). Tutorials also needn't concern\nthemselves with explanations into why or how things work beneath the surface, or explorations\nof  alternate  syntaxes  and  solutions; these are better handled by explainers and reference\npages.\n\nCookbook\n\nA cookbook man page focuses on results. Just like its name suggests,  it  presents  succinct,\nstep-by-step  solutions  to  a variety of real-world problems around some topic. A cookbook's\ncode examples serve less to enlighten and more to provide quick, paste-ready  solutions  that\nthe reader can apply immediately to the situation facing them.\n\nA  Perl  cookbook demonstrates ways that all the tools and techniques explained elsewhere can\nwork together in order to achieve practical results. Any explanation deeper than that belongs\nin explainers and reference pages, instead. (Certainly, a cookbook can cross-reference  other\nman  pages  in  order  to satisfy the curiosity of readers who, with their immediate problems\nsolved, wish to learn more.)\n\nThe most prominent cookbook pages that ship with Perl itself  are  its  many  FAQ  pages,  in\nparticular  \"perlfaq4\"  and  up,  which  provide  short  solutions  to practical questions in\nquestion-and-answer style.   \"perlunicook\"  shows  another  example,  containing  a  bevy  of\npractical code snippets for a variety of internationally minded text manipulations.\n\n(An  aside: The Documentation System calls this mode \"how-to\", but Perl's history of creative\ncuisine prefers the more kitchen-ready term that we employ here.)\n\nReference\n\nA  reference  page  focuses  on  description.  Austere,  uniform,  and  succinct,   reference\npages--often arranged into a whole section of mutually similar subpages--lend themselves well\nto  \"random  access\" by a reader who knows precisely what knowledge they need, requiring only\nthe minimum amount of information before returning to the task at hand.\n\nPerl's own best example of a reference work  is  \"perlfunc\",  the  sprawling  man  page  that\ndetails  the  operation of every function built into Perl, with each function's documentation\npresenting the same kinds of information in the same order as every other. For an example  of\na shorter reference on a single topic, look at \"perlreref\".\n\nModule  documentation--including  that of all the modules listed in \"perlmodlib\"--also counts\nas reference. They follow precepts similar to those laid down by the \"perlpodstyle\" man page,\nsuch as opening with an example-laden \"SYNOPSIS\" section, or featuring  a  \"METHODS\"  section\nthat succinctly lists and defines an object-oriented module's public interface.\n\nExplainer\n\nExplainer  pages  focus on discussion. Each explainer dives as deep as needed into some Perl-\nrelevant topic, taking all  the  time  and  space  needed  to  give  the  reader  a  thorough\nunderstanding  of  it.  Explainers  mean to impart knowledge through study. They don't assume\nthat the student has a Perl interpreter fired up and hungry for immediate examples (as with a\ntutorial), or specific Perl problems that they need quick answers for  (which  cookbooks  and\nreference pages can help with).\n\nOutside of its reference pages, most of Perl's manual belongs to this mode. This includes the\nmajority  of  the man pages whose names start with \"\"perl\"\". A fine example is \"perlsyn\", the\nPerl Syntax page, which explores the whys and wherefores of Perl's unique syntax in  a  wide-\nranging discussion laden with many references to the language's history, culture, and driving\nphilosophies.\n\nPerl's  explainer  pages  give  authors  a  chance  to  explore Perl's penchant for TMTOWTDI,\nillustrating alternate and even obscure ways to use the language  feature  under  discussion.\nHowever,  as  the  remainder of this guide discusses, the ideal Perl documentation manages to\ndeliver its message clearly and concisely, and not confuse mere wordiness for completeness.\n\nFurther notes on documentation modes\n\nKeep in mind that the purpose of this  categorization  is  not  to  dictate  content--a  very\nthorough  explainer  might  contain  short  reference  sections of its own, for example, or a\nreference page about a very complex function might resemble  an  explainer  in  places  (e.g.\n\"open\").  Rather, it makes sure that the authors and contributors of any given man page agree\non what sort of audience that page addresses.\n\nIf a new or otherwise uncategorized man page presents itself as  resistant  to  fitting  into\nonly  one  of  the  four  modes,  consider  breaking it up into separate pages. That may mean\ncreating a new \"\"perl[...]\"\"  man page, or (in the case of module documentation)  making  new\npackages underneath that module's namespace that serve only to hold additional documentation.\nFor  instance,  \"Example::Module\"'s  reference documentation might include a see-also link to\n\"Example::Module::Cookbook\".\n\nPerl's several man pages about Unicode--comprising a short tutorial, a thorough explainer,  a\ncookbook,  and  a FAQ--provide a fine example of spreading a complicated topic across several\nman pages with different and clearly indicated purposes.\n"
                },
                {
                    "name": "Assume readers' intelligence, but not their knowledge",
                    "content": "Perl has grown a great deal from its humble beginnings as a  tool  for  people  already  well\nversed in C programming and various Unix utilities.  Today, a person learning Perl might come\nfrom  any social or technological background, with a range of possible motivations stretching\nfar beyond system administration.\n\nPerl's core documentation must recognize this by making as few assumptions as possible  about\nthe  reader's  prior  knowledge. While you should assume that readers of Perl's documentation\nare smart, curious, and eager  to  learn,  you  should  not  confuse  this  for  pre-existing\nknowledge  about any other technology, or even programming in general--especially in tutorial\nor introductory material.\n\nKeep Perl's documentation about Perl\n\nOutside  of  pages  tasked  specifically  with  exploring  Perl's  relationship  with   other\nprogramming  languages,  the  documentation  should  keep  the  focus  on Perl. Avoid drawing\nanalogies to other technologies that the reader may not have familiarity with.\n\nFor example, when documenting one of Perl's built-in functions, write as if the reader is now\nlearning about that function for the first time, in any programming language.\n\nChoosing to instead compare it to an equivalent or underlying C function  will  probably  not\nilluminate  much understanding in a contemporary reader. Worse, this can risk leaving readers\nunfamiliar with C feeling locked out from fully understanding of the topic--to say nothing of\nreaders new to computer programming altogether.\n\nIf, however, that function's ties to its C  roots  can  lead  to  deeper  understanding  with\npractical  applications  for  a  Perl  programmer,  you  may mention that link after its more\nimmediately useful documentation.  Otherwise, omit this information entirely, leaving it  for\nother  documentation  or  external  articles  more concerned with examining Perl's underlying\nimplementation details.\n\nDeploy jargon when needed, but define it as well\n\nDomain-specific jargon has its place, especially within documentation.   However,  if  a  man\npage  makes use of jargon that a typical reader might not already know, then that page should\nmake an effort to define the term in  question  early-on--either  explicitly,  or  via  cross\nreference.\n\nFor  example,  Perl  loves working with filehandles, and as such that word appears throughout\nits documentation. A new Perl programmer arriving at a man page for the first time  is  quite\nlikely  to  have  no  idea  what  a  \"filehandle\"  is,  though.  Any Perl man page mentioning\nfilehandles should, at the very least, hyperlink that term to  an  explanation  elsewhere  in\nPerl's  documentation.  If  appropriate--for  example,  in  the  lead-in to \"open\" function's\ndetailed reference--it can also include a very short in-place definition of the  concept  for\nthe reader's convenience.\n"
                },
                {
                    "name": "Use meaningful variable and symbol names in examples",
                    "content": "When  quickly  sketching  out examples, English-speaking programmers have a long tradition of\nusing short nonsense words as placeholders for  variables  and  other  symbols--such  as  the\nvenerable  \"foo\",  \"bar\", and \"baz\". Example code found in a programming language's official,\npermanent documentation, however, can and should make an effort  to  provide  a  little  more\nclarity through specificity.\n\nWhenever possible, code examples should give variables, classes, and other programmer-defined\nsymbols  names that clearly demonstrate their function and their relationship to one another.\nFor example, if an example requires that one class show an \"is-a\" relationship with  another,\nconsider  naming  them  something  like  \"Apple\"  and  \"Fruit\",  rather than \"Foo\" and \"Bar\".\nSimilarly, sample code creating an instance of that class would do better to name it  $apple,\nrather than $baz.\n\nEven  the  simplest  examples  benefit  from  clear  language  using concrete words. Prefer a\nconstruct like \"for my $item (@items) { ... }\" over \"for my $blah (@blah) { ... }\".\n"
                },
                {
                    "name": "Write in English, but not just for English-speakers",
                    "content": "While this style guide does specify American English as the documentation's language for  the\nsake of internal consistency, authors should avoid cultural or idiomatic references available\nonly  to  English-speaking  Americans (or any other specific culture or society).  As much as\npossible, the language employed by Perl's core documentation should strive  towards  cultural\nuniversality,  if  not  neutrality.  Regional  turns  of phrase, examples drawing on popular-\nculture knowledge, and other rhetorical techniques of that nature should appear sparingly, if\nat all.\n\nAuthors should feel free  to  let  more  freewheeling  language  flourish  in  \"second-order\"\ndocumentation  about  Perl,  like  books,  blog  entries,  and  magazine  articles, published\nelsewhere and with a narrower readership in mind. But Perl's own docs should use language  as\naccessible and welcoming to as wide an audience as possible.\n"
                },
                {
                    "name": "Omit placeholder text or commentary",
                    "content": "Placeholder text does not belong in the documentation that ships with Perl. No section header\nshould  be  followed  by text reading only \"Watch this space\", \"To be included later\", or the\nlike. While Perl's source files may shift and alter as much as any other actively  maintained\ntechnology,  each  released  iteration  of  its  technology  should  feel  complete and self-\ncontained, with no such future promises or other loose ends visible.\n\nTake advantage of Perl's regular release cycle. Instead of cluttering  the  docs  with  flags\npromising more information later--the presence of which do not help readers at all today--the\ndocumentation's maintenance team should treat any known documentation absences as an issue to\naddress  like  any  other  in the Perl project. Let Perl's contributors, testers, and release\nengineers address that need, and resist the temptation to insert apologies,  which  have  all\nthe utility in documentation as undeleted debug messages do in production code.\n"
                },
                {
                    "name": "Apply section-breaks and examples generously",
                    "content": "No  matter  how  accessible  their  tone, the sight of monolithic blocks of text in technical\ndocumentation can present a will-weakening challenge for the reader. Authors can improve this\nsituation through breaking long passages up into subsections with short, meaningful headers.\n\nSince every section-header in Pod also acts as a potential end-point  for  a  cross-reference\n(made  via  Pod's  \"L<...>\" syntax), putting plenty of subsections in your documentation lets\nother man pages more precisely link to a particular topic. This creates  hyperlinks  directly\nto  the most appropriate section rather than to the whole page in general, and helps create a\nmore cohesive sense of a rich, consistent, and interrelated manual for readers.\n\nAmong the  four  documentation  modes,  sections  belong  more  naturally  in  tutorials  and\nexplainers.  The  step-by-step  instructions  of  cookbooks,  or  the  austere definitions of\nreference pages, usually have no room for them. But authors can always  make  exceptions  for\nunusually complex concepts that require further breakdown for clarity's sake.\n\nExample code, on the other hand, can be a welcome addition to any mode of documentation. Code\nblocks  help  break up a man page visually, reassuring the reader that no matter how deep the\ntextual explanation gets, they are never far from another practical example  showing  how  it\nall comes together using a small, easy-to-read snippet of tested Perl code.\n"
                },
                {
                    "name": "Lead with common cases and best practices",
                    "content": "Perl  famously  gives  programmers  more than one way to do things. Like any other long-lived\nprogramming language, Perl  has  also  built  up  a  large,  community-held  notion  of  best\npractices,  blessing  some  ways  to do things as better than others, usually for the sake of\nmore maintainable code.\n\nShow the better ways first\n\nWhenever it needs to show the rules for a technique which Perl provides many avenues for, the\ndocumentation should always lead with best practices. And when discussing some  part  of  the\nPerl  toolkit  with  many  applications,  the  docs  should begin with a demonstration of its\napplication to the most common cases.\n\nThe \"open\" function, for example, has myriad potential uses within Perl programs, but most of\nthe time programmers--and especially those new to Perl--turn to this reference  because  they\nsimply  wish  to  open a file for reading or writing. For this reason, \"open\"'s documentation\nbegins there, and only descends into  the  function's  more  obscure  uses  after  thoroughly\ndocumenting and demonstrating how it works in the common case. Furthermore, while engaging in\nthis  demonstration,  the  \"open\"  documentation  does  not burden the reader right away with\ndetailed explanations about calling \"open\" via any route other than the best-practice, three-\nargument style.\n\nShow the lesser ways when needed\n\nSometimes, thoroughness demands documentation  of  deprecated  techniques.   For  example,  a\ncertain  Perl  function  might have an alternate syntax now considered outmoded and no longer\nbest-practice, but which a maintainer of a legacy project might  quite  reasonably  encounter\nwhen  exploring  old code. In this case, these features deserve documentation, but couched in\nclarity that modern Perl avoids such structures, and does not  recommend  their  use  in  new\nprojects.\n\nAnother   way   to   look   at   this   philosophy   (and   one  borrowed  from  our  friends\n<https://devguide.python.org/documenting/#affirmative-tone> on Python's  documentation  team)\ninvolves  writing  while  sympathizing  with a programmer new to Perl, who may feel uncertain\nabout learning a complex concept. By leading that concept's main  documentation  with  clear,\npositive  examples, we can immediately give these readers a simple and true picture of how it\nworks in Perl, and boost their own confidence to start making  use  of  this  new  knowledge.\nCertainly  we  should include alternate routes and admonitions as reasonably required, but we\nneedn't emphasize them. Trust the reader to  understand  the  basics  quickly,  and  to  keep\nreading for a deeper understanding if they feel so driven.\n"
                },
                {
                    "name": "Document Perl's present",
                    "content": "Perl's  documentation  should  stay  focused on Perl's present behavior, with a nod to future\ndirections.\n\nRecount the past only when necessary\n\nWhen some Perl feature changes its behavior, documentation about that feature  should  change\ntoo,  and  just  as  definitively.  The  docs have no obligation to keep descriptions of past\nbehavior hanging around, even if attaching clauses like \"Prior to version 5.10, [...]\".\n\nSince Perl's core documentation is part of Perl's source distribution,  it  enjoys  the  same\nbenefits  of versioning and version-control as the source code of Perl itself. Take advantage\nof this, and update the text boldly when needed. Perl's history remains safe, even  when  you\ndelete or replace outdated information from the current version's docs.\n\nPerl's  docs  can acknowledge or discuss former behavior when warranted, including notes that\nsome feature appeared in the language as of some  specific  version  number.  Authors  should\nconsider  applying principles similar to those for deprecated techniques, as described above:\nmake the information present, but not prominent.\n\nOtherwise, keep the past in the past. A manual uncluttered with  outdated  instruction  stays\nmore succinct and relevant.\n\nDescribe the uncertain future with care\n\nPerl  features  marked  as \"experimental\"--those that generate warnings when used in code not\ninvoking the \"experimental\" pragma--deserve documentation, but only in certain contexts,  and\neven  then  with caveats. These features represent possible new directions for Perl, but they\nhave unstable interfaces and uncertain future presence.\n\nThe documentation should take both implications of \"experimental\" literally.  It  should  not\ndiscourage  these  features'  use by programmers who wish to try out new features in projects\nthat can risk their inherent  instability;  this  experimentation  can  help  Perl  grow  and\nimprove.  By the same token, the docs should downplay these features' use in just about every\nother context.\n\nIntroductory or overview material should omit coverage of experimental features altogether.\n\nMore thorough reference materials or explanatory articles can include experimental  features,\nbut needs to clearly mark them as such, and not treat them with the same prominence as Perl's\nstable   features.  Using  unstable  features  seldom  coincides  with  best  practices,  and\ndocumentation that puts best practices first should reflect this.\n"
                },
                {
                    "name": "The documentation speaks with one voice",
                    "content": "Even though it comes from many hands and minds, criss-crossing  through  the  many  years  of\nPerl's  lifetime,  the language's documentation should speak with a single, consistent voice.\nWith few exceptions, the docs should  avoid  explicit  first-person-singular  statements,  or\nsimilar self-reference to any individual's contributor's philosophies or experiences.\n\nPerl did begin life as a deeply personal expression by a single individual, and this famously\ncarried  through  the  first  revisions of its documentation as well. Today, Perl's community\nunderstands that the language's continued development and  support  comes  from  many  people\nworking  in  concert, rather than any one person's vision or effort. Its documentation should\nnot pretend otherwise.\n\nThe documentation should, however, carry forward the best tradition that Larry Wall set forth\nin the language's earliest days: Write both economically  and  with  a  humble,  subtle  wit,\nresulting  in  a  technical  manual  that mixes concision with a friendly approachability. It\navoids the dryness that one might expect from technical documentation, while not  leaning  so\nhard  into  overt  comedy as to distract and confuse from the nonetheless-technical topics at\nhand.\n\nLike the best written works, Perl's documentation has a soul.  Get  familiar  with  it  as  a\nreader  to  internalize  its  voice,  and  then  find  your own way to express it in your own\ncontributions.  Writing  clearly,  succinctly,  and  with  knowledge   of   your   audience's\nexpectations will get you most of the way there, in the meantime.\n\nEvery  line in the docs--whether English sentence or Perl statement--should serve the purpose\nof bringing understanding to the reader. Should a sentence exist mainly to make  a  wry  joke\nthat  doesn't further the reader's knowledge of Perl, set it aside, and consider recasting it\ninto a personal blog post or other article instead.\n\nWrite with a light heart, and a miserly hand.\n"
                }
            ]
        },
        "INDEX OF PREFERRED TERMS": {
            "content": "As noted above, this guide \"inherits\" all the preferred terms listed in the Chicago Manual of\nStyle,  17th  edition,  and  adds  the  following  terms  of  particular  interest  to   Perl\ndocumentation.\n\nbuilt-in function\nNot \"builtin\".\n\nDarwin\nSee macOS.\n\nmacOS\nUse this term for Apple's operating system instead of \"Mac OS X\" or variants thereof.\n\nThis term is also preferable to \"Darwin\", unless one needs to refer to macOS's Unix layer\nspecifically.\n\nman page\nOne unit of Unix-style documentation. Not \"manpage\". Preferable to \"manual page\".\n\nPerl; perl\nThe  name  of  the  programming  language  is  Perl,  with a leading capital \"P\", and the\nremainder in lowercase. (Never \"PERL\".)\n\nThe interpreter program that reads and executes Perl code is named \"\"perl\"\", in lowercase\nand in monospace (as with any other command name).\n\nGenerally, unless you are specifically writing about the command-line \"perl\" program (as,\nfor example, \"perlrun\" does), use \"Perl\" instead.\n\nPerl 5\nDocumentation need not follow Perl's name with a \"5\", or any other number, except  during\ndiscussions  of  Perl's history, future plans, or explicit comparisons between major Perl\nversions.\n\nBefore 2019, specifying \"Perl 5\" was sometimes needed to distinguish  the  language  from\nPerl 6. With the latter's renaming to \"Raku\", this practice became unnecessary.\n\nPerl 6\nSee Raku.\n\nPerl 5 Porters, the; porters, the; p5p\nThe  full  name of the team responsible for Perl's ongoing maintenance and development is\n\"the Perl 5 Porters\", and this sobriquet should be  spelled  out  in  the  first  mention\nwithin any one document. It may thereafter call the team \"the porters\" or \"p5p\".\n\nNot \"Perl5 Porters\".\n\nprogram\nThe  most  general  descriptor  for  a stand-alone work made out of executable Perl code.\nSynonymous with, and preferable to, \"script\".\n\nRaku\nPerl's \"sister language\", whose homepage is <https://raku.org>.\n\nPreviously known as \"Perl 6\". In 2019, its design team renamed  the  language  to  better\nreflect  its  identity  as a project independent from Perl. As such, Perl's documentation\nshould always refer to this language as \"Raku\" and not \"Perl 6\".\n\nscript\nSee program.\n\nsemicolon\nPerl code's frequently overlooked punctuation mark. Not \"semi-colon\".\n\nUnix\nNot \"UNIX\", \"*nix\", or \"Un*x\". Applicable to both the original operating system from  the\n1970s  as  well as all its conceptual descendants. You may simply write \"Unix\" and not \"a\nUnix-like operating system\" when referring to a Unix-like operating system.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "•   perlpod\n\n•   perlpodstyle\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "This guide was initially drafted by Jason McIntosh (jmac@jmac.org), under a  grant  from  The\nPerl Foundation.\n\nperl v5.38.2                                 2026-06-12                              PERLDOCSTYLE(1)",
            "subsections": []
        }
    },
    "summary": "perldocstyle - A style guide for writing Perl's documentation",
    "flags": [],
    "examples": [],
    "see_also": []
}