On 3/18/2013 11:37 AM, Timo Sirainen wrote:
So basically you're saying that the major documentation improvement = an index listing/describing all settings. Sure, would be useful, but I don't see having time to write that anytime soon.
The time issue is perfectly understandable Timo.
My suggestion may not be the gold or platinum improvement to the docs, but I think it would help a lot of people, especially since most using Dovecot are also using Postfix, and since man is the standard UNIX documentation format/interface. I think some similarity/consistency would help quite a bit as many people are so used to this format.
Do you have a way to simply dump all the current conf file parameter names from 2.x into a single column text file? I'll sort it and start adding the legal parameter values and writing the parameter definitions from information currently available in source and wiki pages. When I hit the point I can't find reference material for the rest of the parameters, we can dump it to a wiki page or similar so others with the knowledge can jump in and help finish it. Once it's done, myself, or someone else if they already have the experience, can create the man page from this to be included in the source. And you can create an update mechanism/batch process so that updating the 'master' document automatically updates the source man page and other published versions, making documentation updates simple when you add/change parameters.
We could do the wiki bazaar style editing from the beginning, but I'd rather not. I'd like to get it started with a framework/layout and style of prose typical of UNIX documentation, for other editors to follow. The definition text prose needs to be consistent all the way through, or readers may be confused by the different writing styles of ~50 different people who may speak different 'dialects' of English or have different writing styles. This consistency is one of the hallmarks of good technical writing.
Like I said previously, the one thing I'm able to contribute more than anything at this point is time. And my writing skills aren't completely horrible--I have been published, FWIW, but not recently. But my knowledge of the parameters, and a lot of Dovecot features in general is lacking. So if others are willing to contribute where I fall short, I'd be glad to give this a go and get it started, and hopefully put a decent sized dent in it so there's not so much left for others to do. Obviously you have final review/edit authority, and if you have a particular preference on writing style, etc, I'll certainly honor that.
If this is acceptable to you Timo, let me know. If so send me the aforementioned file, any preferences/thoughts you have, and I'll get started on the first draft.
-- Stan