From c455896ae9e69e2498742ff795e7886dee1ffa23 Mon Sep 17 00:00:00 2001 From: Patrick Spek Date: Fri, 5 Feb 2021 09:55:25 +0100 Subject: Move source files into src --- src/_projects/pod-to-pager.adoc | 102 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 src/_projects/pod-to-pager.adoc (limited to 'src/_projects/pod-to-pager.adoc') 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 `. You can specify a doc +formatter by giving it as argument, like `perl6 --doc=Text `. 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. + -- cgit v1.1