Use colon to separate module and object in listing
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.)
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.
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.
Move SHELLFU_DEBUG* and SHELLFU_VERBOSE to pretty where they belong
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.
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.