Official Perl 6 Documentation
An HTML version of this documentation can be found at https://docs.perl6.org/. This is currently the recommended way to consume the documentation.
There is also a command line tool called "p6doc".
(If you are browsing this repository via GitHub, it will not display most files correctly, because this is Perl 6 Pod, and GitHub assumes Perl 5 POD).
Install p6doc
This module is available via the Perl 6 module ecosystem. Use
zef install p6doc
to install the binaries and make it available in your binaries execution path.
Use p6doc
With a Rakudo perl6
executable in PATH
, try
./bin/p6doc Str
to see the documentation for class Str
, or
./bin/p6doc Str.split
to see the documentation for method split
in class Str
. You can
skip the ./bin
part if you have installed it via
zef
. You can also do
p6doc -f slurp
to browse the documentation of standard functions. Depending on your disk speed and Rakudo version, it might take a while.
Building the HTML documentation
Install dependencies by running the following in the checkout directory:
zef --deps-only install .
If you use rakudobrew
, also run the
following, to update the shims for installed executables:
rakudobrew rehash
In addition to the Perl 6 dependencies, you need to have graphviz
installed, which
on Debian you can do by running
sudo apt-get install graphviz
To build the documentation web pages, simply run
$ make html
Please note that you will need to have nodejs
installed to produce HTML content with the above command, in particular
a node
executable should be in your PATH
.
After the pages have been generated, you can view them on your local
computer by starting the included app.pl
program:
$ make run
You can then view the examples documentation by pointing your web browser at http://localhost:3000.
You will need at least Mojolicious installed and you will need nodejs to perform highlighting. There are also some additional modules you might need; install them all using
$ cpanm --installdeps .
Help Wanted!
Perl 6 is not a small language, and documenting it takes a lot of effort. Any help is appreciated.
Here are some ways to help us:
- add missing documentation for classes, roles, methods or operators
- add usage examples to existing documentation
- proofread and correct the documentation
- tell us about missing documentation by opening issues on github.
- Do a
git grep TODO
in this repository, and replace the TODO items by actual documentation.
Issues page has a list of current issues and documentation parts that are known to be missing and CONTRIBUTING explains briefly how to get started contributing documentation.
Some notes:
Q: Why aren't you embedding the docs in the CORE sources?
A: Several reasons:
- This documentation is intended to be universal with respect to a given version of the specification, and not necessarily tied to any specific Perl 6 implementation.
- Implementations' handling of embedded POD is still a bit uneven; this avoids potential runtime impacts.
- A separate repo in the perl6 Github account invites more potential contributors and editors.
Q: Should I include methods from superclasses or roles
A: No. The HTML version already includes methods from superclasses and
roles, and the p6doc
script will be taught about those as well.
Q: Which license is this stuff under?
A: Both code and documentation are available under the Artistic License 2.0
as published by The Perl Foundation. See the LICENSE file for the full
text.
Vision
I want p6doc and doc.perl6.org to become the No. 1 resource to consult when you want to know something about a Perl 6 feature, be it from the language, or built-in types and routines. I want it to be useful to every Perl 6 programmer.
-- moritz
Wishlist stuff:
-
Perl 6 implementations could embed
P<...>
tags in their source code that would then inline the corresponding entry fromp6doc
. This would enable things like&say.WHY
to (dynamically!) retrieve the documentation string fromp6doc
, without having to duplicate the documentation in theCORE.setting
sources or to encode the documentation into the binaries.Example:
# In Rakudo's src/core/IO.pm: #= P<p6doc/&print> sub print(|$) { ... } #= P<p6doc/&say> sub say(|$) { ... } #= P<p6doc/¬e> sub note(|$) { ... }
ENV VARS
P6_DOC_TEST_VERBOSE
to a true value to display verbose messages during test suite run. Helpful when debugging failing test suite.P6_DOC_TEST_FUDGE
fudgesskip-test
code examples as TODO inxt/examples-compilation.t
test
LICENSE
See LICENSE file for the details of the license of the code in this repository.
This repository also contains code authored by third parties that may be licensed under a different license. Such files indicate the copyright and license terms at the top of the file. Currently these include:
- jQuery and jQuery UI libraries: Copyright 2015 jQuery Foundation and other contributors; MIT License
- jQuery Cookie plugin: Copyright 2006, 2015 Klaus Hartl & Fagner Brack; MIT License
- Examples from Stack Overflow MIT License; (ref #1 for 1f7cc4e)