Date: Mon, 12 Mar 2001 14:51:56 -0800 (PST) From: John Baldwin <jhb@FreeBSD.org> To: Nik Clayton <nik@FreeBSD.org> Cc: Chris Costello <chris@calldei.com>, Udo Erdelhoff <ue@nathan.ruhr.de>, doc@FreeBSD.org Subject: Re: Translators: Need feedback on FAQ reorganization Message-ID: <XFMail.010312145156.jhb@FreeBSD.org> In-Reply-To: <20010312213831.A74204@canyon.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 12-Mar-01 Nik Clayton wrote: > On Mon, Mar 12, 2001 at 11:21:36AM -0800, John Baldwin wrote: >> > I like the idea of a branch in the FAQ, because then no one has to do >> > anything different to get it -- supfiles will still work, and so on. >> >> A branch is painful. > > Why? I've used CVS branches before (outside FreeBSD) for just this > purpose. During the early SMPng work, we were keeping a patchset that floated around between the developers. It wasn't quite a side branch, but it was close. The problem was that other commits to the kernel kept conflicting, making our jobs trying to keep things in sync much more painful, and it wasn't even that big of a patch (400k). Had we actually committed it on a sidebranch, it would have been just as much non-fun. If it were still on a sidebranch right now then it would be unlivable. Keeping your development too far away makes keeping up with other changes more painful. And we won't even go into CVS braindeadedness and the repo bloat this will bring. :-P >> Since the FAQ shouldn't be broken, there's no reason to >> not just do this on HEAD. > > Not so much broken, but I expect there will be periods where it's very > confusing to readers as the content migrates all over the place. Nah. If the question isn't still in the main faq.sgml, it's in one of the chapter.sgml files, and the chapter name should easily help to lcoate it, along with grep -r if necessary. Heck, you'd have to use some kind of search in the editor to get to the point in faq.sgml where the question is anyway. So long as the same question isn't in two different places (which is easy enough to achieve) then there should be no problems. Besides, the actual content moving should probably only take a week at most. We aren't changing any markup or anything, just cut 'n' paste here. >> The DocBook -> LinuxDoc was a bit different, as in >> some of your steps it didn't build, IIRC. If that was not the case, then it >> should've been done in the tree with a checkin at each milestone as it were. > > It was done in the tree. We were able to do the Handbook in the tree > because the conversion coincided with moving the Handbook from one > directory in the tree to another. I just did all the work in the new > directory, and the handbook's old directory wasn't touched until the > conversion was over. Err, it wasn't all done in the tree. :) You had this long itemized list of steps that you took, and those list of steps aren't present as individual commits in the logs. :) >> Also, the merge to HEAD will be >> painful if other changes are committed to the FAQ during the move. > > Possibly I've got the wrong impression here, but I wasn't expecting this > to be an overnight job. I've assumed it will probably take a few days, > or a week, and that it's entirely possible Chris might go AWOL for a few > weeks due to real life (no slight on Chris intended, I've had to do > exactly the same myself). If this happens, the current FAQ needs to > remain accessible and understandable. As long as each piece is moved out atomically the FAQ will be in a fully usable state the entire time. This is not hard to achieve, and it results in no need to merge all the stuff back into HEAD later on and thus possibly losing intermediate changes, etc. > My assumption was that the people doing the work on FAQng would be > periodically pulling changes from the HEAD back on to their branch. We > might have a flag day in which the FAQ is frozen except to the FAQng > team to give them breathing space to do any last merges before replacing > HEAD, but that's about it. The change aren't that drastic. You pull up faq.sgml in one file. Highlight a "chapter". Do your editor's cut operation, pull up the appropriate chapter.sgml file, and do a paste. You then make a few tweaks to add a new entity for the file and include the file in faq.sgml and to add the source file to the Makefile. You then commit all this in one commit. The FAQ before and after is still qutie usable and buildable. Repeat until it's all split up. Aside from waiting forever on jade to do its test build, this might take 10 minutes per chapter. I think the bulk of the work in what Chris has done is in things like merging questions, rewriting, etc. and there's no reason that can't be committed in a normal fashion once the mostly mechanical operation of splitting up the big sgml file has been done. > If that's not the case, and we're talking about a mad flurry of > individual commits in the space of a night, then that's different. > >> Instead, >> commits during the move will be separate events that the translators can >> just >> treat as autonomous little events. > > If the commits leave the FAQ buildable (which I assume they will) and if > (and this is much more important) the individual commits leave the FAQ > usable to its audience. It will be just as usable as it will be when the transition is finished. If people can't grep through the sgml files when it is in transition, how will they find the questions once it is all split up? Doing a branch is extra work that I think you don't needs to be done. > N -- John Baldwin <jhb@FreeBSD.org> -- http://www.FreeBSD.org/~jhb/ PGP Key: http://www.baldwin.cx/~john/pgpkey.asc "Power Users Use the Power to Serve!" - http://www.FreeBSD.org/ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?XFMail.010312145156.jhb>