Where regular expression is read from a variable and -e argument is not
provided, the resulting call may end up being interpreted as grep
argument,  This can be pretty dangerous, eg. if the variable expands to
`--help`, grep help is shown and grep exits with zero, which would be
interprered as match.  Another example is when the variable expands to
a valid grep parameter; this would mean that next argument would be
interprered by grep as the regex, and if the argument after that would
be missing, grep would read stdin, resulting in data messup or grep
waiting
indefinitely.

See also:

    https://github.com/koalaman/shellcheck/issues/1342

Actually man 1.* does support local mode, we just have to pass pathname
(with slash), which can be easily worked around by using tempfile.

man version 1.x does not support local file mode.  sfdoc is mostly for
development purposes, so instead of jumping through hoops to make it
work; we assume user can view the pages in other format or on a less
obsolete distro.

Useful when working with a private set of modules; to see what's inside,
etc.

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.