Turns out to be concise and safe enough to become the preferred one.

Make the list a bit easier to handle in scripts (colon does not have
special regex meaning).

Also im human-readable contexts, dot makes it more likely to confuse the
string with with filename (eg. `foo.bar`.)  But then again, it's better
for humans to go a bit further and decorate the reference, eg.
`foo:bar()` or `foo:$BAZ`.  (Doing that in default output would make
them hard to parse, though.)

In some cases the file is not slurped so declaring encoding at the tail
is useless.

Allow for re-use and more independent testing.

...or '(no version)', if version is not present.

In the rare case when pod2man is not available, the usage options are
limited (one can still view pages in other modes or list functions
etc.).

'sfdoc' is easier to type and resembles 'pydoc' and 'perldoc' so it's
even easier to remember.

The only purpose of the binary is to show local Shellfu path and it's
in every single Shellfu script.  Let's save people some typing.

The Perl code did not keep hash sign, nullifying effect of the strip_doc
pipe.  As a result, the function docstring would contain single space
before each non-empty line.

Markdown does not care about that (well, unless we already had 3 spaces
there in which case a block could be considered verbatim).  In POD,
however, this means verbatim plaintext.  Viewing as manpage later (by
far most common use case), the visual difference is normally too subtle
to notice, but at some point pod2html had spilled the beans.

Only used in POD so far

Try to get closer to how typical manpage looks like:

 *  Use NAME and DESCRIPTION sections.

 *  Make structure more flat (FUNCTIONS and VARIABLES on 1st level).

 *  Use `=item` formatting for function/variable references.

This should be especially useful in scenarios where docstrings are
exported directly from module file, but the filename is not
representative as module name.

This would typically happen where shellfu is only used for documentation
handling but not module handling.

These variables are not specific to shellfu internals but in all ways
specific to pretty.sh module.  The prefix is mostly historical cruft.

Let's clean that up.

Great rewrite with revamped CLI, many added features and bugfixes.

 *  New CLI optimized for simple use.  Default action is to show
    module doc in manpage viewer.

 *  Respects variable documentation.

 *  Respects module documentation (first stray docstring).

 *  Can export (ugly but usable) module docs as Markdown, POD or
    manpage.

 *  Dropped useless features as --cat (one can always open the file)
    or display of partial documentation.

 *  Provided more rich usage hint.

 *  Rewrote tests with focus on more probable scenarios.

shellfu-get (whose only job is to print one of hardcoded strings depending
on $1) and shellfu.sh should be as light as possible.  Most of this code
is only useful (and intended) for library exploration, which is domain
of shellfu-doc.

A neat side-effect is, that in its new home, we don't have to be so
fussy about performance and footprinting, so we can afford luxury such
as putting code into functions and documenting them, using $1 for first
argument, using shellfu libraries(!)...

Needless to say, this is an incompatible CLI change (or it would have
half the effect), so we take the opportunity to re-do the CLI to match
the new home.

According to best practice (leads to cleaner code).

If user does not provide mandatory parameter, `shift 2` will fail but
will not shift anything, resulting in infinite loop.

A more conventional hierarchy

Although pretty, this way of initializing ffoo must go since it's
not possible to protect it with a working `|| exit 3` clause.

Problem is that bash will create the pipe no matter if the ffoom call
eventually succeeds or not, so in case ffoom is not ready we end up
sourcing and empty file--which always succeeds.

to easily test out documentation for currently developed library.