Perl 6 documentation (tools and docs)
Perl6 CSS JavaScript Shell Makefile HTML Other
Latest commit 388a1d8 Jan 21, 2017 @coke coke Remove debug output
Permalink
Failed to load latest commit information.
assets/sass CSS: make <regexidentifiers> darker and color token/rule nicely Dec 28, 2016
bin p6doc add local file usage example Dec 31, 2016
doc group optional slash(/) and data so data does not parse without slash… Jan 20, 2017
highlights Remove debug output Jan 21, 2017
html Do not focus search with Escape key Dec 24, 2016
lib Revert "Only alter filenames based on disallowed filenames per distro" Jan 7, 2017
t Revert flawed test Jan 14, 2017
template CSS: make <regexidentifiers> darker and color token/rule nicely Dec 28, 2016
util Trigger rebuild to pull in highlighting fixes Jan 13, 2017
xt add new maybe-word Jan 17, 2017
.gitignore Enable SASS Compiler and TOSS style.css Dec 23, 2016
.travis.yml Allow failures on Travis on MacOS (OS X) Jan 11, 2017
Build.pm Rename .pod files to .pod6 Jun 28, 2016
CONTRIBUTING.md Remove references in *.md to Inline::Python and pygments Dec 29, 2016
CREDITS add username to credits Dec 4, 2016
LICENSE No more trailing whitespace (EVERYWHERE!) May 20, 2016
META.info Add mandatory "perl" META field Oct 26, 2016
Makefile move htmlify to its own rule Jan 5, 2017
README.md fix spelling errors Jan 9, 2017
STYLEGUIDE.md fix typo Dec 2, 2016
app-start Use SASS Jun 28, 2016
app.pl Revert "Make sure we only correct `::` into $COLON$COLON on MSWin" Jan 7, 2017
htmlify.p6 Revert "Try and end the highlights process after we are done with it" Jan 11, 2017
type-graph.txt Added docs for X::Proc::Unsuccessful Nov 12, 2016
type-groups.json In preparation to make /type.html decent, first shot at grouping types. Jan 15, 2017

README.md

p6doc -- an attempt to write something like 'perldoc' for Perl 6

Build Status artistic

An HTML version of this documentation can be found at https://docs.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).

Install

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.

Once it has been downloaded, run

p6doc-index build

to build the index.

Use

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. You can skip the ./bin part if you have installed it via panda or 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:

panda installdeps .       # if you use panda
zef --depsonly install .  # if you use zef

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

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.


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:

  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 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 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<p6doc/&print>
    sub print(|$) { ... }
    
    #= P<p6doc/&say>
    sub say(|$) { ... }
    
    #= P<p6doc/&note>
    sub note(|$) { ... }
    

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: