Documentation-time logic

Document! But do not take this task as an addition to developing. Here is an example of an integrated way of developing and socumenting at the same time.

The example shows a script which includes its own documentation. With simple tools, we generate man documentation from its output.

First of all, you need this formatted output: --version and --help. This example applies the "fortunes" script written in a previous post.

[rodolfoap] /home/rodolfoap > fortunes --version
GNU fortunes v0.1

Copyright (C) 1999 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Written by Rodolfo Alcazar <rodolfoap@hotmail.com>
[rodolfoap] /home/rodolfoap > fortunes --help
GNU fortunes is a personal fortunes engine organizer, written in bash.

Usage: fortunes [OPTION]

Options:
-e edit fortunes file
-l enters learning mode
-m enters multiline-learning mode
--help shows this help
--version shows version

Examples:

fortunes --help shows this help
fortunes -e edits fortunes file
fortunes generates a random fortune
fortunes -l starts learning mode

Report bugs to rodolfoap@hotmail.com

Start documentation process:

[rodolfoap] /home/rodolfoap > help2man fortunes|gzip -f>fortunes.1.gz

User just access the man page. In this case, the man page is not stored in its proper location.

[rodolfoap] /home/rodolfoap > man ./fortunes.1.gz