|Matteo Cypriani 7e3d60ad25 Add dddoc/||8 months ago|
|README.md||8 months ago|
|dddoc.sh||8 months ago|
This documentation file was extracted from
dddoc.sh using the following
./dddoc.sh -d . dddoc.sh && mv dddoc.sh.md README.md
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
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.
Copyright 2018 Matteo Cypriani email@example.com
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.
This section and the followings document
dddoc.sh; they are not
particularly interesting, but are meant as a demonstration and documenting
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
Prints the usage message.
Prints the usage message to the standard error and exits with an error code.