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