Documentation blues

[Ben Finney]

--DocE+STaALJfprDB
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On 24-Jun-2003, FRANK D. HUBENY wrote:
> You wrote in part:
> [...]
> My response:
> [...]

(Please follow the email convention of quoting the message with '> ' at
the start of each line, to make it obvious at a glance which part is
yours and which part is quoted.)

> I do have a highly commented " gpg.conf " file that I use.  I would be
> glad to send it to you to use or modify as you wish.  I suppose an
> off-list request would be the way to go, as I understand long posts
> are frowned apon.

Thanks for offering to share your config file.

Even better would be if you could post this on your website -- after
obfuscating anything you consider to be sensitive information, of
course.  That way you can refer anyone to it with the URL and they can
grab it at leisure.

> I try to cut and past from the " gpg.man ", or " gpg.txt".

I'm starting to change my opinion to one *against* heavily-commented
config files.

The problem with them is that as program features change, the config
file comments become out-of-date; the comments are a disparate form of
documentation that must be maintained.

Currently I am experimenting on some new machines with stripping out all
comments longer than a single line, and having a "Man page: foo.conf(5)"
referring to the documentation for the command (or, preferably, the man
documentation specifically for the config file) in the top comment
block.

This way, I'm forced to think of a succinct description of each option
in the file, that will fit on a single line; and my config files are
much less likely to have voluble descriptions that are subtly (or
markedly) different to how the current version of the program operates.

Why single-line comments?  Because the point of the config file's
comments, I believe, is to act as a handy *reminder* of the commands and
options.  If it can't be expressed simply on one line, it is likely
complex enough to *require* looking up in the documentation.

I also try to make the per-option comments independent of the current
value of the option.  E.g., if an option can be set to enable or disable
the foo setting, I dont' have a comment saying "Disable the foo
setting", since that comment will be confusing if I ever decide to
enable it; rather, "Enable the foo setting?" or "Determine the foo
setting" allow the value to be changed without the comment becoming
incorrect.

Anyone got opinions on these issues?

--=20
 \     "We used to laugh at Grandpa when he'd head off and go fishing. |
  `\      But we wouldn't be laughing that evening when he'd come back |
_o__)           with some whore he picked up in town."  -- Jack Handey |
bignose@zip.com.au  F'print 9CFE12B0 791A4267 887F520C B7AC2E51 BD41714B

--DocE+STaALJfprDB
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (GNU/Linux)

iEYEARECAAYFAj7457YACgkQt6wuUb1BcUs+/gCffboNXeDCSEz+ghJEnAlzadRL
CqQAnRxnCRZrJUOkh87H1nAIAAPzDw5I
=+A+I
-----END PGP SIGNATURE-----

--DocE+STaALJfprDB--