71 lines
2.4 KiB
Markdown
71 lines
2.4 KiB
Markdown
_This documentation file was extracted from `dddoc.sh` using the following
|
|
command:_
|
|
|
|
./dddoc.sh -d . dddoc.sh && mv dddoc.sh.md README.md
|
|
|
|
dddoc -- Double-Dièse Documentation extractor
|
|
=============================================
|
|
|
|
This script is designed to extract inline documentation from shell scripts
|
|
or libraries, or any other language using the sharp (#) as a comment mark.
|
|
It follows the tradition of POD (Plain Old Documentation), but permits an
|
|
easier-to-read syntax, allowing you to use the markup language that suits
|
|
you (such as MarkDown, txt2tags, etc.).
|
|
|
|
The only pre-requisite is that the comment lines to be extracted start with
|
|
two sharps (##), hence the name of this script ("dièse" stands for "sharp"
|
|
in French). The two sharps must be followed by at least one space or an end
|
|
of line for the line to be extracted; for instance, lines starting with
|
|
three sharps won't be extracted. Both sharps starting the line, and exactly
|
|
one space (if any) will be stripped.
|
|
|
|
Each output file bares the name of the corresponding input file, with a
|
|
user-defined suffix (`-s` switch), that defaults to "md".
|
|
|
|
The input file hierarchy is respected, and this script is best used along
|
|
with `find` and `xargs`, for instance:
|
|
|
|
cd /project/path
|
|
find * -type f -print0 | xargs -0 dddoc /path/to/destdir
|
|
|
|
The destination directory could be a clone of a GitLab wiki (or Gitea, or
|
|
GitHub...), which will allow you to easily publish a nice-looking set of
|
|
docs.
|
|
|
|
License
|
|
=======
|
|
|
|
Copyright 2018 Matteo Cypriani <mcy@lm7.fr>
|
|
|
|
This program is free software. It comes without any warranty, to the extent
|
|
permitted by applicable law. You can redistribute it and/or modify it under
|
|
the terms of the Do What The Fuck You Want To Public License, Version 2, as
|
|
published by Sam Hocevar. See http://sam.zoy.org/wtfpl/COPYING for more
|
|
details.
|
|
|
|
Globals
|
|
=======
|
|
|
|
This section and the followings document `dddoc.sh`; they are not
|
|
particularly interesting, but are meant as a demonstration and documenting
|
|
guide.
|
|
|
|
- `PROGNAME`: this script's name
|
|
- `DESTDIR`: output directory
|
|
- `VERBOSE`: verbose level
|
|
- `SUFFIX`: suffix (extension) of output files
|
|
- `REGEX`: the regular expression that determines which lines will be
|
|
extracted from input files
|
|
|
|
Functions
|
|
=========
|
|
|
|
print_usage()
|
|
-------------
|
|
Prints the usage message.
|
|
|
|
bad_usage()
|
|
-----------
|
|
Prints the usage message to the standard error and exits with an error code.
|
|
|