Should we simplify the AWFFull man page, and leave all config file options documented in the sample.conf file?
Submitted by Steve on February 5, 2008 - 2:09pm.
Yes
29% (2 votes)
No
57% (4 votes)
Maintain as it currently is
0% (0 votes)
Whatever
0% (0 votes)
Steve you're such a legend, whatever you feel like doing is fine with me.
14% (1 vote)
Total votes: 7
(Poll closed, but my answer'd be: No!)
This would actually be the exact opposite of what one would expect those two things stand for.
In a sample configuration -- as the name obviously already tells, I'd expect a working config file I can use as a base. It would be heavily bloated and, well, just a sample, so nothing that'd be for use as in a prodcution environmnent. But the _documentation_ for config files? 'Why the hell is the documentation in a sample file?', would be the question raised when someone would tell me about that. Oh, well, yeah. It is raised. The man-page is the place where one would expect the documentation to be. The man-page is the place where actually all programs put in their documentation and uhm..
oh gad.. documentation in a man-page?! Captain Obvious, come save us all!
Shortly put, that's blatant inconsistency. man-page for documentation, sample config for sample config.
Another probable solution would be an .html documentation [here on the page and downloadable] -- yeah. Still I expect documentation to be in the man-page :P
so far, Shimmy
RTFM
The manpage is great because it is immutable and clearly states what are the default values, and it should always match the installed version. Therefor the manpage is much more usefull when upgrading unless you rewrite your configuration from the new sample.conf.
The sample config file is already quite big, i use much more simpler configurations files, with only option that have non-default values. (That's why i was concerned about loading a system config then the user config, because the system config may already provide non-default values, so when you upgrade the system settings, it can break all the adhoc configs.)
As long as default values changes are announced and options values are backward compatible, we're safe.
In the poll the option to
In the poll the option to use a wiki page for the documentation is missing :-)
wiki page option?
The option to buy Steve a beer was missing too. ;-)
Been doing a few updates to
Been doing a few updates to awffull lately - pretty much have 3.9.x ready to roll as a beta. Poss alpha...
But the docco concerns me. My normal mode is to update the sample.conf file for new configuration changes; and then "port" essentially the same words into the man page.
Which is... not terribly optimal in many ways.
I'd like to explore the idea with you all of simplifying the man page down to just the command line options; and leave all the config file docco in the sample.conf file.
ANYONE who selects the last option (in the above poll) will receive access to a freely available copy of the AWFFull source code. Signed with my GPG key!!! WOW! Does it get any better than that!