1-1sam

Manuals for Raku Programs

In this post, I will detail my strategy for distributing manuals with Raku programs, especially those which you wish to distribute via Zef.

TLDR

Write your manual in Pod, then include a --help option that does

use Pod::To::Text;

multi sub MAIN(Bool :h(:$help)!) {

    put pod2text $=pod;

}

The Problem

Manuals (or manpages) are a form of documentation that have been standard in Unix operating systems since ancient times. I believe two reasons manpages have stood the test of time are the following:

  1. Detail: Manpages typically contain all the information necessary to use a program (or they should, at least ;-).
  2. Accessibility: Manpages can be immediately accessed via the command line using man command. Convenient and no network required!

Despite this, there are two issues with traditional manpages.

  1. Portability: Systems like Windows don't believe in manpages.
  2. Language Support: Some programming languages don't support distributing/generating manpages very well.

These are unfortunately problems you will run into when trying to distribute a manual for a cross-platform Raku program. The conventional way to distribute documentation for a Raku program is to either put the manual in its backend module's Pod or in the README. Neither of these are ideal either, primarily because of accessibility concerns. If you put it in program's module Pod, the user will have to know how to access it. This isn't an issue if you're a Raku dev who knows about rakudoc, but is an issue if you aren't in the know and just want to read the documentation. The alternative, to put it in the README, is just as bad, as the README is not installed with the distribution, meaning the user will have to go out of their way to find and save the README themselves.

The Solution

Many programs have the option to be ran with the --help option, which will print out a help message that details the usage of the program and its options. The help message is usually meant to just be a quick synopsis on the usage of the program, as opposed to the manual which contains much more comprehensive documentation. However, many programs have their help option bring up their manual (exiftool, systemctl, off the top of my head), so what if we did something similar; have a --help option that prints out a manual? By combining the manual and help message, we have a manual that is:

  1. Accessible: Can be read from the program itself.
  2. Detailed: We can choose the level of detail to write our help message.
  3. Portable: Built into the program itself; if the program be ran, it can be read.
  4. Supported: Raku provides a simple way to implement this
use Pod::To::Text;

multi sub MAIN(Bool :h(:$help)!) {

    put pod2text $=pod;

}

=begin pod

=head1 NAME
...

What this code does is render the Pod in the file it is located in and print it out. It accomplishes this by using pod2text, which is exported by Pod::To::Text. Pod::To::Text is a core module provided by Raku, so portability is not a concern here. $=pod is the variable holding your file's Pod structure, it's guarenteed to be there as long as you have Pod. Then you just have to write your manual in Pod.

I also like generating a README from my manuals, which I do via the Pod::To::Markdown module. That way, my README and manual have the same documentation, but I only need to maintain a single file.

One issue with this approach is that you won't be able to use special Pod comments (#|, #=). It's not a problem for me because I never liked using them anyway, but YMMV.

If you'd like to see this trick used in practice, you can view the following programs of mine:

Conclusion

That's all. I've been trying to come up with a good idea for a new post for a while but nothing could come to mind. I realized that manuals seems to be a relatively untapped topic in Raku, so I thought this post might be helpful to some folks.

Merry Christmas and Happy Holidays :-)

Last Modified: 2024-12-27