1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
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.
|
