[Dovecot] RTFM: Manual pages for Dovecot v2.0
Hello Dovecot admins.
I've started writing manual pages for Dovecot v2.0. I'm sure they are not perfect yet. I'd like to ask you all to read the manual pages. It would be nice to get some ideas/suggestions/improvements. So that that the Dovecot v2.0.0 release could be distributed with /fine manuals/.
The manual pages are available at: http://wiki2.dovecot.org/ManPages This is also the intended place for 'discussions' about the man pages.
Regards, Pascal
The trapper recommends today: cafebabe.1007713@localdomain.org
I've spent some time for the fine manual. Whats new?
Location: http://hg.localdomain.org/dovecot-2.0-man So I don't have to flood the wiki with attachments. As soon as the manual pages are complete, they will be included in the Dovecot source tree.
Additional manual pages: * doveconf(1) * dovecot-lda(1) * dsync(1)
Points for clarification: Currently all man pages are slated for section 1. I'm sure that's not correct. Which man pages should be moved to section 8?
There are many subsections w/o 'XXX', 'FIXME', '$DESCRIPTION' or similar notes/placeholders. Please let me know what's missing. What could be improved? Each suggestion is very welcome.
Perhaps one of you has more experience with writing manual pages. So feedback about the '*roff style' is also welcome. Note: The resulting man pages should be usable on any system.
Regards, Pascal
The trapper recommends today: cafefeed.1015207@localdomain.org
Pascal,
On 5/31/10 11:40 PM, "Pascal Volk" <user+dovecot@localhost.localdomain.org> wrote:
I've spent some time for the fine manual. Whats new?
Location: http://hg.localdomain.org/dovecot-2.0-man So I don't have to flood the wiki with attachments. As soon as the manual pages are complete, they will be included in the Dovecot source tree.
This is fantastic. When I get a moment, I'll definitely read them over. I spent a good bit of time getting a Dovecot 2.0 test system set up this weekend and I found myself flipping back and forth between Timo's release announcements, sample configurations in the tarball, and the raw source code. Doveconf in particular doesn't even seem to provide help text listing available command line flags, so a man page is very welcome.
Documentation of what configuration options work where would also be particularly nice to see. The new syntax is incredibly powerful but also very complex. It appears that there are some things that will pass doveconf checks but will either cause errors or be ignored by the actual code at runtime.
-Brad
On 06/01/2010 08:51 AM Brandon Davidson wrote:
This is fantastic. When I get a moment, I'll definitely read them over. I spent a good bit of time getting a Dovecot 2.0 test system set up this weekend and I found myself flipping back and forth between Timo's release announcements, sample configurations in the tarball, and the raw source code. Doveconf in particular doesn't even seem to provide help text listing available command line flags, so a man page is very welcome.
doveconf.1 needs still some improvements.
Documentation of what configuration options work where would also be particularly nice to see. The new syntax is incredibly powerful but also very complex. It appears that there are some things that will pass doveconf checks but will either cause errors or be ignored by the actual code at runtime.
dovecot.conf.5 or similar is not planned, afaik. The configuration documentation is included in the example config. hm
Regards, Pascal
The trapper recommends today: deadbeef.1015209@localdomain.org
participants (2)
-
Brandon Davidson
-
Pascal Volk