Hi Henri. On 11/10/2011, Henri Kemppainen <ducl...@guu.fi> wrote: > > I agree this isn't ideal. On the other hand, having a system ship with > two overlapping & incompatible alternatives is a rather exceptional case, > and there's no way to automagically please everyone. One could suggest > renaming the manuals (and binaries?) and installing them both, but that's > nasty and ugly, and probably not worth it, if one of the daemons is to > be axed anyway. > > There's surely a good reason smtpd isn't the default yet, and there's > a good reason I kept hearing that smtpd isn't considered ready for > production yet, back when I started using it. The message is rather > clear to me: you may play with it, as long as you know what you're doing, > and are okay with the possibility of problems. Finding the manual is a > part of knowing what you're doing :-) I can see why one could get > confused though, even if the title lines for these (installed) manuals > contain "sendmail".
You are 100% correct about all of that. Including this ... "finding the manual is part of knowing what you're doing". It seems to me though, that unless people are actively looking through src for makemap(8) it will easily go unnoticed even for the patch senders. I've been through there maybe a hundred times in the last few months and never noticed it. I go there to look for something specific, find it, move on. Whenever I want documentation I start at man smtpd and go from there. Again though you are 100% correct and we've all been warned. This is why I've tried to understand the situation and tried to laugh about it. I've started drinking now which is helping somewhat ... >> If not, what can be done about users who read the man pages and have >> issues as a result? > > I don't know what can be done about users, but I know what the users can > do: try figure out what is lacking or misleading, maybe contact the > developer(s), and propose a change. Something like this: > > Index: makemap.8 > =================================================================== > RCS file: /cvs/src/usr.sbin/smtpd/makemap.8,v > retrieving revision 1.14 > diff -u -p -r1.14 makemap.8 > --- makemap.8 3 Sep 2010 11:22:36 -0000 1.14 > +++ makemap.8 10 Oct 2011 19:10:51 -0000 > @@ -90,11 +90,14 @@ accept for domain map "primary" deliver > .Ed > .Sh VIRTUAL DOMAINS > Virtual domains are kept in maps. > -To create single virtual address, add > -.Dq u...@example.com user > +To create a virtual domain, add > +.Dq example.com kittens > to the virtual map. > -To handle all mail destined to any user at example.com, add > -.Dq @example.com user > +To create a virtual address for one user under that domain, add > +.Dq u...@example.com user > +to the virtual map. > +To catch all mail destined to the domain, add > +.Dq @example.com user > to the virtual map. > .Pp > In addition to adding an entry to the virtual map, I'll have a look at that in a minute, well maybe after a good sleep but I don't see any reason not to make some adjustment to smtpd.conf(5) ... That's where the smtpd man pages start to go to makemap(8) ... The next best and as far as I can see other deviation into the Sendmail man pages is from smtpd(8) into mailwrapper. Changing /etc/mailer.conf is discussed there and I don't see any reason not to make it obvious not to follow the breadcrumbs too blindly (i.e.caveats) or maybe a BUGS section. I would like to see smtpd.conf include some "warning" also and I think it's warranted there more than anywhere. As you say smtpd is known non-production, transitional, so on. Under these circumstances it seems reasonable to me that this information is clearly outlined in all the smtpd specific man pages which it currently isn't. not in any of them that I can see. You and I know this but there are others. Whether or not that happens I see no reason under the same circumstance to be careful when pointing to other man pages that are irrelevant and/or harmful. For instance if I see smtpd and smtpd.conf man pages included can I assume that other included man pages they point to and reference without warning are pointed to and referenced for a reason ... That's what I've assumed. Absent input from Gilles I'll get up tomorrow and do this. It's 7am here ... > The need to have a value for the domain key is a bit ugly. I noticed > the stdio backend is happy with empty values, allowing for a pretty list > under a colon terminated domain name: > virtual.domain: > user1@virtual.domain user1 > user2@virtual.domain user2 > > another.domain: > user3@another.domain user3 > user4@another.domain user4 > .. > > Makemap doesn't like it, though. > > You're talking a very different language from me. These terms don't appear outside of makemap(8) and maybe newaliases(8) which again I notice is in src ... I pulled makemap(8) from the web last night and had a couple of reads but I really need to take my time with it ... ... but your previous examples were exactly my reaction ... I put this in a draft ... example.com us...@example.com user1 us...@example.com us...@other.domain.com OR domain-key example.com u...@example.com u...@other.domain.com ... but kept it to myself. After all I don't have to push the wheelbarrow. I sit back and watch Gilles do it. :] Your idea is probably better but I'm no programmer. Sticking my neck out regardless ... Surely it's not a case of ... "plain" doesn't currently do that and we want to support "plain" (which is obviously great) ... so lets rip that feature out for db also ... Surely it's more of a case that we already do this for db and we want to support "plain" so let's give plain a reserved word or something ... Yes, I noticed you were referencing the "real" makemap man page in your earlier mail but not until after I'd suggested you were in the same boat as me which you obviously aren't. Best wishes.
