I think man pages should be written originally not in wiki format, but in
some
format made for unix documentation.
Is there a way to do these manpages in mdoc in a team? How can we stop
doing them on the wiki website but still do them as a team?
IMHO doing a man page for every ~control file is better, it'll be more
easy to
find.
If you want to teach people about the architecture, I'd extend "The big
qmail
picture" and turn it into a more in depth qmail-ldap architecture doc.
We should think in making life easier for new people and sysadmins. Most
people will not look for man pages in wiki, but in shell.
Thanks Omar, and I was thinking the same last night. I had a new idea, tell
me what you think about it:
Stock Qmail already has 29 control files, they are listed in the following
table:
badmailfrom (none) qmail-smtpd
badmailpatterns (none) qmail-smtpd
badrcptto (none) qmail-smtpd
bouncefrom MAILER-DAEMON qmail-send
bouncehost me qmail-send
concurrencylocal 10 qmail-send
concurrencyremote 20 qmail-send
defaultdomain me qmail-inject
defaulthost me qmail-inject
databytes 0 qmail-smtpd
doublebouncehost me qmail-send
doublebounceto postmaster qmail-send
envnoathost me qmail-send
helohost me qmail-remote
idhost me qmail-inject
localiphost me qmail-smtpd
locals me qmail-send
morercpthosts (none) qmail-smtpd
percenthack (none) qmail-send
plusdomain me qmail-inject
qmqpservers (none) qmail-qmqpc
queuelifetime 604800 qmail-send
rcpthosts (none) qmail-smtpd
smtpgreeting me qmail-smtpd
smtproutes (none) qmail-remote
timeoutconnect 60 qmail-remote
timeoutremote 1200 qmail-remote
timeoutsmtpd 1200 qmail-smtpd
virtualdomains (none) qmail-send
In Qmail the control files are documented inside the program that uses it.
For example, the control file "timeoutconnect" is used by qmail-remote, so
it is documented in qmail-remote's manpage.
Following this logic, whenever in qmail-ldap one control file is used by
just one program, we should do the manpage for this control file inside
that program's manpage. For example, rbllist and smtpcert are used just by
qmail-smtpd, so they should be documented inside qmail-smtpd's manpage.
Do we agree on this issue? (i hope so)
And for the 19 control files that are used by more than one program, and
here resides the problem, I thought about creating a manpage for each of
them in section 9, and the manpages would have the exact name of the
control file, this way, the manpages could be accessed by, say, "man
ldaprebind", as you and Claudio prefer (and now i think everybody agree).
So, why not to create them in section 5, that is supposed the be the
section for control files?
Because there are already 10 important manpages in this section, like
addresses(5), envelopes(5), dot-qmail(5), etc. Creating new 19 manpages
there will let that section confusing, specially when browsing on the
manpages (I always browse the manpages on the website, that's why I
concern).
Section 9 is not actually used in Qmail (if you check Qmail documentation
you're going to realize that Section 9 is made of repeated manpages). So I
prefer to put the manpages here.
If you think that section 9 it's ok, It's great!
If you think that the 19 manpages of the shared control files should be in
section 5, I suggest to create the manpages with a "qmail-control" radical
in their names, like "qmail-control-ldaprebind", this is to differentiate
them to the other manpages.
Finally, if you think that the 19 new manpages should be indeed on the
section 5, amongst the existing ones, and you hate this "qmail-control"
idea, I will accept it too and will do it happily.
So Omar, what do you think?
Claudio, what do you think?
Regards,
bnegrao
