# p6doc -- an attempt to write something like 'perldoc' for Perl 6
[](https://travis-ci.org/perl6/doc) [](https://opensource.org/licenses/Artistic-2.0)
An HTML version of this documentation can be found at http://doc.perl6.org/.
(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).
With a Rakudo `perl6` executable in `PATH`, try
./bin/p6doc Type::Str
to see the documentation for class `Str`, or
./bin/p6doc Type::Str.split
to see the documentation for method `split` in class `Str`.
--------
## Building the HTML documentation
To build the documentation web pages, simply run
$ make html
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 Inline::Python is recommended
to speed up the syntax highlighting phase.
--------
## 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, either by adding it to the WANTED
file, or by opening issues on github.
* Do a `git grep TODO` in this repository, and replace the TODO items by
actual documentation.
The file [WANTED](WANTED) has a list of particular documents that are known
to be missing and [CONTRIBUTING](CONTRIBUTING.md) 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:
1. 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.
2. Implementations' handling of embedded POD is still
a bit uneven; this avoids potential runtime impacts.
3. 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](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:
* Search terms like `.any`, `any()`, `&any`, `::Any`, etc. can be
used to disambiguate whether information is sought on a method,
subroutine, type, etc.
* Searching for `Int.Bool` returns the documentation for the
inherited method `Numeric.Bool`.
* Searching for an operator name returns the documentation for
the operator. (`p6doc '%%'` returns the documentation for
`&infix:<%%>`.)
* Perl6 implementations could embed `P<...>` tags in their source
code that would then inline the corresponding entry from `p6doc`.
This would enable things like `&say.WHY` to (dynamically!)
retrieve the documentation string from `p6doc`, without having
to duplicate the documentation in the `CORE.setting` sources
or to encode the documentation into the binaries.
Example:
# In Rakudo's src/core/IO.pm:
#= P
sub print(|$) { ... }
#= P
sub say(|$) { ... }
#= P
sub note(|$) { ... }