=begin pod :kind("Programs") :subkind("programs") :category("programs")

=TITLE Reading the docs

=SUBTITLE rakudoc - the Raku pod reader

=head1 X<INTRODUCTION|rakudoc>

Program C<rakudoc> is a command-line-interface (CLI) program that reads
Raku pod from B<installed> modules' source code, in contrast to
running C<raku --doc=MODULE programfile> which reads Raku pod from
the named source file.

Note that C<rakudoc> may not be installed automatically depending upon
how you installed Rakudo Raku.  To install it use C<zef>:

=for code :lang<usage>
zef install rakudoc

=head1 SYNOPSIS

=for code :lang<usage>
rakudoc [switches] [arguments]

=head1 DESCRIPTION

With no switches or arguments, C<rakudoc> lists its help to C<$*OUT> (C<stdout>):

=begin code :lang<output>
You want to maintain the index?
To build the index for `rakudoc -r ...`:
          rakudoc -b

What documentation do you want to read?
Examples: rakudoc Str
          rakudoc Str.split
          rakudoc faq
          rakudoc path/to/file

You can also look up specific method/routine/sub definitions:
          rakudoc -r hyper
          rakudoc -r push

You can bypass the pager and print straight to stdout:
          rakudoc -n Str
=end code

The text output can be captured and converted to other forms if desired.

If you want to use ANSI escape sequences, which will apply boldface
and other enhancements to the output, you will have to set
POD_TO_TEXT_ANSI, which is unset by default

=for code :lang<shell>
export POD_TO_TEXT_ANSI=1


=head1 LIMITATIONS

Currently C<rakudoc> can only extract embedded Raku pod from installed
module source files (as listed in a distribution's C<META6.json>
file).  It is planned to add a feature for C<rakudoc> (in conjunction
with C<META6.json> changes) to extract B<all> Raku pod in files
included with the installed distribution.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
