From owner-freebsd-doc Sun Aug 22 15:17:22 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 82796155F6; Sun, 22 Aug 1999 15:15:41 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id WAA87731; Sun, 22 Aug 1999 22:14:07 +0100 (BST) (envelope-from nik) Date: Sun, 22 Aug 1999 22:14:07 +0100 From: Nik Clayton To: Satoshi - Ports Wraith - Asami Cc: Nik Clayton , doc@freebsd.org Subject: Re: Default FDP docs installation directory? Message-ID: <19990822221406.A80051@catkin.nothing-going-on.org> References: <19990818121931.A4266@kilt.nothing-going-on.org> <19990819131224.A844@kilt.nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: ; from Satoshi - Ports Wraith - Asami on Sun, Aug 22, 1999 at 02:43:33AM -0700 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org [ I'd dearly, dearly love to be able to say that I've redirected all followups to this message to the freebsd-navel-gazing list. Unfortunately, we don't have one, so it's stuck here in -doc. I'd quite like to take this to personal e-mail, but I can hear the chants of "Why won't he discuss this in public? FreeBSD is too cliquey, we want to know what's going on!" ringing in my ears, so I haven't. My apologies. But, if you're reading this for the humour value, take my advice and go straight to the last page -- there's a corker waiting for you. ] On Sun, Aug 22, 1999 at 02:43:33AM -0700, Satoshi - Ports Wraith - Asami wrote: > * I get the impression that some -doc subscribers have the wrong idea about > * what it is that I'm doing as the Doc. Proj. Manager, and what my role > * actually is. > : > * But in doing this, I'm no different from any other contributor to this list > * (well, every contributor that's also a committer, and I'm pleased to report > * that the number of FDP related committers is growing nicely at the moment). > > So you are not the one that makes the decisions when people don't > agree? That's good to hear. :) That depends :-) I'm trying hard not to have to make specific decisions, because I'm trying to make sure that there's enough discussion that the right choice falls out of the discussion. As I said in the previous message, some times there are no obvious right or wrong choices to make, and it's only when people start asking questions in the discussion that pointers to the right answer come up. Having said that, I get personal e-mail every day from people who read -doc, both committers and non-committers, asking whether they should do 'x' or 'y', and I answer them as best I can. Where possible I cc: my replies back to -doc so that (1) my response gets in the archives, and (2) people who might know more about it than I do can respond if they see the message. Sometimes I can't answer the question at all, and just point them at people who I hope can answer the question. And I imagine that one day there will be two committers who both want to commit different variants on the same change, and I'll get asked to choose between them. But as I say, I'll try and *not* say "Do it this way!", but I'll ask questions about both approaches to see if one way is better than another. > I had the distinct impression that you are the manager that we need to > convince, and you are a very hard person to convince once you make up > your mind (which is usually very early). I guess I was wrong. Yeah. I don't normally take a lot of convincing if something's a bad idea. Take the "/usr/local/share/doc/fdp/" thing. That was discussed, and turned around in roughly 24 hours. *24* hours. That's practically no time at all, particularly when I do all my e-mail reading in blocks of time that are roughly 12 hours apart. (i.e., at t+0 I post the message, at t+12 the first responses have come in, some making points that I'd considered, which I responded to countering those points, some making points that I hadn't considered, and I start thinking "Hmm, maybe this isn't such a great idea", and t+24 more responses have come in, almost all of them pointing out problems, and I drop the idea.) Notice, incidentally, that I don't just drop the idea, but I say so publically, and in a message to the list, which means that this all gets archived. I'm not interested in trying to hide mistakes that I might have made. > * To try and illustrate this, lets look at three different examples from the > * relatively recent past: > > There's another one. You converted the documents from Linuxdoc to > Docbook, arguing it's better. Honestly, I still don't see why it was > necessary. These are in no particular order of significance; 1. LinuxDoc is dying. SGMLTools, the main 'wrapper' around it in the Linux world has switched to DocBook, and the Linux Documentation Project is moving towards it (although not as quickly as we have -- this is mostly because we have less documentation to convert). 2. DocBook is a far better designed DTD. Yes, there's more to learn about it (which is why I wrote, and continue to write, the primer), but it's more extensible, more flexible and more widely supported. 3. DocBook as a DTD promotes consistency in the choice of markup. This is a good thing, as it (a) makes the job of marking things up easier, (b) allows more consistency in the output, giving a strong sense of 'family' between the documents, (c) prevents the author having to worry about what their document will look like, and instead concentrate on marking up their documentation accurately. 4. DocBook is a "richer" markup model, so our documents will be easier to downgrade to other markup models (like, for example, HTML, or PilotDoc). There are others, and I suspect that there's about to be slew of messages from DocBook supporters, so I'll wait and see what points they make, before following up with anything they've missed. > The few documents I care about (handbook's ports chapter) > is much harder to read in HTML after the conversion with all the > numbers gone from the section headers. Edit freebsd.dsl, and put this code fragment; (define %section-autolabel% ;; Are sections enumerated? #t) somewhere between the markers. Then take two aspirin and call me in the morning if the problem persists. If people think that should go in freebsd.dsl shipped by the FDP then say so -- I'm agnostic about the issue, but if people want it in then it can go in. What you're describing is an issue with the formatting, which is (unlike LinuxDoc) much removed from the markup language itself. Yours is the first time I can recall seeing anyone on this list mention this as being a problem -- note that I'm not saying it's the first time anyone's mentioned it, but it's the first time I've noticed it as a problem. > The sgml files are harder to edit too, but that might be because we've > been using Linuxdoc for a long time. Harder to edit how? You've got a consistent set of indentation for the first time, making it much easier to see the structure of the document? And if you mean that DocBook is hard because you don't know DocBook then I'd appreciate comments on the Primer so that I can improve it for people. > Also, the Japanese PS and PDF handbook generation is still broken > since the Linuxdoc -> Docbook switchover. It is? Define broken? I know that there were problems, but I was under the impression that Jun Kuriyama had fixed them, updated the port, and forwarded them on to Norm Walsh. > Is anyone going to fix that? They will if you let me know what they are. A quick % cd /usr/gnats/docs % grep dsssl * didn't show up anything, so I guess people don't care enough to send in a PR about it. I can't fix stuff (or at least, investigate) stuff I don't know about. > I'm not saying you should fix it, but since you are the one > that proposed the switch and the one that implemented it, you should > at least make sure you have someone signed up to fix it (ideally > before the switchover). It's obviously escaped your attention, but I am doing stuff to fix it. People commented that they didn't like the way the FAQ was coming out. I had a patch back to the list within 12 hours or so -- so far, just one person has bothered to comment on it. Since they said they liked it, it's gone in to my queue of things to commit -- it'll take a few days, because I've mailed my patch back to the original author for comments, because I'm not convinced my patch is the right way to do it. > * One thing that should be made clear -- just because it was committed as > * such does not mean (and should never mean) that I'm not flexible in > * changing it at the first opportunity as necessary. > > That's good to hear. But to avoid any further misunderstandings, > please don't commit things if it's already surrounded by controversy. At that point it wasn't surrounded by controversy. > * For the future, I'm going to try and make sure that my suggestions are > * marked as such (and not "commandments handed down from the Doc. Proj. > * Manager"), so that they're less likely to cause what seems to have been > * some offense. > > Then it might help if you don't post messages with subjects like: > > Resolution: FDP reorganisation > > right when the discussion started. That's called pushing the wrong > button. I think you might have a loose SIMM somewhere. The "Resolution" message was posted after we'd already had one long round of discussion on the topic, and two posted drafts of the plan for doing it. I thought that after the amount of time it had been discussed every objection had either been discussed, and realised that it wasn't a problem, or discussed, and incorporated in to the plan. It was only after the "Resolution" message was posted that a set of fresh problems and concerns were raised. More specifically: my first message was posted on 4th May (subject line was "doc//books/*, doc//articles/*, and docs.freebsd.org". That discussion had 4 distinct contributors, and carried on until the 15th May. It slowed down over the last two days, so on May 13th I posted a revised version of the plan, with the subject line "FDP Directory Reorganisation". People seemed to wake up at this point, and we carried on until June 26th. During that discussion I was amending and posting amendments to the plan as we went along, and as with the previous discussion, it petered out towards the end, which is why I posted the "Resolution" message in June 23rd. You might think that a message posted in June 23rd to a discussion that was kick-started on the 4th May is "right when the discussion started", but I've got a hard time following that train of thought I'm afraid. This thread devolved in to three main discussions: 1. The first was about the name of the Japanese directory. I'd mistakenly thought that the Japanese consensus was for ja_JP.EUC-JP. You bought the fact that I'd made a mistake about this to my attention, and I immediately changed it the ja_JP.eucJP you requested. That's a non-issue. 2. The merits of repository copies, whether or not commit histories needed to be maintained, and the tags. I was quite happy to let this discussion carry on without much input from me -- I didn't completely follow the points the Japanese team were making, didn't have much time to, but trusted that between yourselves and JDP you would come to an arrangement. As far as I can tell, it was all resolved amicably. 3. The third, and by far longest sub-thread was sparked by Motoyuki Konno, who asked why we were doing this at all. This then triggered a re-run of large chunks of the two earlier threads on this, with the same arguments back and forth. > Then there's the matter of trust (as a human being). Honestly, there > is very little trust in you, especially among the Japanese people. Christ, I've offended a whole nation :-) OK, seriously, for a moment: if you felt the need to write that then something has gone seriously wrong. I'd like to hear from the members of the Japanese Doc. Proj. (in private mail please, not withstanding the disclaimer at the start of this message, I don't think we need to subject -doc to the rest of this) so we can discuss this a little more slowly and a little more calmly. I mean no offense to you Satoshi, but until this little blow-up my contact with the Japanese translators was Jun Kuriyama, and he's been conspicuously absent from this thread. I'm also going to commit the third cardinal sin of e-mail discussion netiquette: I've had private mail from members of a couple of the other translation teams asking me what the hell is going on here, and why are we getting so uptight about this, so there's at least some remnants of trust left lying around. > I asked you twice about who in the Japanese translation team you talked > to about the FAQ Docbook conversion. Will you please answer my > question? Sorry for the delay. Going through 7.8MB of outgoing mail file takes some time, particularly when you have to spend so much of that time writing long and involved e-mails to mailing lists because some people just won't let some issues wither and die. Jun Kuriyama, personal e-mail, subject line "Re: FDP Directory Reorganisation", message ID <19990607235712.A35217@catkin.nothing-going-on.org> It was in one message to Jun, talking about plans for after the conversion. With hindsight I think it's clear how Jun could have ignored it, or put it on the "to think about later" pile, and not got around to it. The error is still mine. > If I don't get an answer this time, I will assume you lied the first > time around and in fact didn't talk to anybody on the Japanese team. I love comments like this in e-mail. It always leaves the recipient in such a dilemma. Should I delete it, and pretend I never saw it? Should I rise to the bait, start foaming at the mouth, and flame you with 15 screenfulls of invective? Should I instead try and pick it apart, refute it at length, bore the audience with carefully argued debate. Should I just make fun of it? I just can't decide. Tell you what, since this is the new happy, shiny, FDP organisation, where consensus rules, I'll throw this one out to the assembled masses. Hey guys, if you're reading this, and you've got a strong opinion as to which of the options above I should take (or if you've got a new one) please e-mail me directly and let me know. I'll summarise the responses back to the list (unless, of course, most of the responses are "No, please, stop talking about this, we're very bored of it, and would just like to get on writing some documentation in peace and quiet please."). Cheers, N PS: Oh, one more thing. I'm going to be over for FreeBSD Con. in October, and I understand that some of the Japanese translation team are going to be there as well -- could we maybe postpone this whole thing until we can sit down and talk about it face to face? I'm a lovely guy in person, willing to stand my own round of drinks, and I can probably bore you all with pictures of my girlfriend. PPS: I wonder if there's any statistical correlation between the fluctuation in length of my e-mail messages and the times that my girlfriend spends on holiday. PPPS: OK, seriously for a moment again. "Jun Kuriyama". Am I right in using "Jun" in the same way other people would refer to me as "Nik", or have I got it backwards? I've asked about this before, but I think it got lost in the noise, and the last time the topic came up (on another mailing list as it happens) I don't recall any clear consensus -- thanks. -- [intentional self-reference] can be easily accommodated using a blessed, non-self-referential dummy head-node whose own object destructor severs the links. -- Tom Christiansen in <375143b5@cs.colorado.edu> To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message