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
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.
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.
Alois Mahdal
Alois Mahdal
Alois Mahdal