diff options
Diffstat (limited to 'src/_projects/pod-to-pager.adoc')
-rw-r--r-- | src/_projects/pod-to-pager.adoc | 102 |
1 files changed, 0 insertions, 102 deletions
diff --git a/src/_projects/pod-to-pager.adoc b/src/_projects/pod-to-pager.adoc deleted file mode 100644 index ca1af10..0000000 --- a/src/_projects/pod-to-pager.adoc +++ /dev/null @@ -1,102 +0,0 @@ ---- -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. - |