Editing Plain Old Documentation (section)

==Use==

Pod is the language used for most [[documentation]] in the Perl world. This includes Perl itself, nearly all publicly released [[Perl module|modules]], many [[script (computer programming)|script]]s, most design documents, many articles on [http://www.perl.com/ Perl.com] and other Perl-related web sites,
and the [[Parrot virtual machine]].

Pod is rarely read in the raw, although it is designed to be readable without the assistance of a formatting tool.  Instead, it is read with the {{anchor|perldoc}}perldoc tool, or converted into Unix [[man page]]s or Web-standard HTML pages.

It is also possible to use pod in other contexts than Perl. For example, to add simple documentation to [[Bash (Unix shell)|bash scripts]], which can then be easily converted to man pages.<ref name="pod_in_bash">[http://bahut.alma.ch/2007/08/embedding-documentation-in-shell-script_16.html Embedding POD documentation in a shell script] (retrieved 10 Jan 2011)</ref> Such uses rely on language-specific hacks to hide the pod part(s), such as (in bash) prefixing the POD section with the line <code>:<<=cut</code> which works by calling bash's [[no-op]] <code>:</code> command, with the whole block of Pod as a [[here document]] as input to it.

Pure pod files usually have the extension <code>.pod</code>, but pod is mostly used directly in Perl
code, which typically uses the <code>.pl</code> and <code>.pm</code> extensions.  (The Perl
[[Interpreter (computing)|interpreter]]'s [[parser]] is designed to ignore pod in Perl code.) In source code files, the documentation is generally placed after the <code>__END__</code> marker (which also helps [[syntax highlighting]] in some editors to display it as comments).

Pod can easily be converted to other formats, for example some of the various [[Wiki]] formats like: [[WikiWikiWeb]], [[Kwiki]], [[TWiki]], [[UseModWiki]], [[TiddlyWiki]], [[Textile (markup language)|Textile]], [[MediaWiki]], [[MoinMoin]] or [[Confluence]] using Pod::Simple::Wiki.