Bruno Negrão wrote: >> 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: > > [...] > > 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)
No. If I want to know something about a specific control file, usually that means, that I don't know anything or much about it - so I also don't know which program it uses. It makes the thing just harder to document these control files inside the manpage for the program that uses it. > > 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). It's not confusing if you want to find something and not only browse through the qmail-manpages if you don't have anything else to do. Our goal has to be to make the information as easy to find as possible, and the ONLY (and easiest) way to do that is to have one man-page for each control file. It does NOT matter how many manpages we create, it matters, how easy they are to find. > > 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. It's not neccessary, as there is only one file called ldapprebind etc. in the whole file system usually, so there is no need to use a prefix to make clear that it comes from qmail-ldap. Finally, I don't care about which section they are in, I always just type man XXX. Philipp
