1 files changed, 102 insertions, 0 deletions
diff --git a/src/_projects/pod-to-pager.adoc b/src/_projects/pod-to-pager.adoc
new file mode 100644
index 0000000..ca1af10
--- /dev/null
+++ b/src/_projects/pod-to-pager.adoc
@@ -0,0 +1,102 @@
+---
+layout:  project
+title:   Pod::To::Pager
+date:    2018-07-15T00:00:00Z
+langs:   Perl 6
+license: AGPLv3
+repo:    https://gitlab.com/tyil/perl6-pod-to-pager
+---
+:toc: preamble
+
+`Pod::To::Pager` is a Perl 6 project to generate prettier output from Perl 6
+Pod structures. By default, Perl 6 ships with a very simple Pod formatter,
+which can be used by calling `perl6 --doc <file>`. You can specify a doc
+formatter by giving it as argument, like `perl6 --doc=Text <file>`. This will
+use the `Pod::To::Text` module to format the output, which is also the default.
+
+But, I wanted something prettier, something I would actually like reading if I
+were looking for documentation on a module. Most people are familiar with UNIX
+man pages (or at least, most people who will read, this I hope). So I wanted to
+create something similar. To get used to Perl 6 Pod, I just tried making simple
+text, with some coloring, as this is easier than also trying to learn how man
+pages are to be created.
+
+And so, `Pod::To::Pager` was born. I've received some feedback from the Perl 6
+community, and included some of it in to the module. It comes with a `p6man`
+utility, which is very much like `p6doc`. It calls the formatter, and calls a
+pager to show the result. It looks very much like the UNIX man pages, and the
+pager lets you read it like one. It's basically an on-the-fly generated man
+page.
+
+== Installation
+
+To install the module, be sure to have Perl 6 and `zef`, the Perl 6 module
+manager, installed on your system. You can then call `zef install` to have it
+download, test, and install the module:
+
+[source,sh]
+----
+zef install Pod::To::Pager
+----
+
+== Usage
+
+Once installed, you can use the module in many ways. You can call it as a Pod
+formatter on Perl 6 itself:
+
+[source,sh]
+----
+perl6 --doc=Pager lib/Some/Module.pm6
+----
+
+This will render the document on `STDOUT`, and display it in your terminal. If
+it doesn't support scrollback, there's a high chance you can't see the top part
+of it. To solve that, you can use a pager, like `less`:
+
+[source,sh]
+----
+perl6 --doc=Pager lib/Some/Module.pm6 | less
+----
+
+This will keep it possible to scroll through the output, until you press `q` to
+quit the pager.
+
+=== p6man
+
+Since the last form is the way it was intended to be used (hence the *pager* in
+`Pod::To::Pager`), there's a utility bundled with the module to make such use
+easier. Inspired by the existence of `p6doc`, it's called `p6man`. It will use
+`less` as the pager on GNU+Linux if possible, otherwise it will fall back to
+`more`. On Windows, it will just use `more`. You can call it with either a
+(relative) file path, or a module name:
+
+[source,sh]
+----
+p6man lib/Some/Module.pm6
+p6man App::Assixt
+----
+
+For the latter variant to work, the module must be installed locally.
+
+=== In Perl 6 programs
+
+You can also use it directly in Perl 6 programs. This allows you to change
+behaviour of the formatting process, or render the program's own documentation
+with this formatter's output. To do that, `use` the module, and call the
+`format` method on the formatter class:
+
+[source,perl6]
+----
+use Pod::To::Pager;
+
+say Pod::To::Pager($=pod);
+----
+
+This will render the program's own Pod structure, formatted using
+`Pod::To::Pager`, and print it to `STDOUT`.
+
+== Feedback
+
+If you have any feedback, please reach out to me on `#perl6` on IRC, or create
+an issue on the repository.
+