Date: Mon, 12 Mar 2001 15:37:31 -0800 (PST) From: John Baldwin <jhb@FreeBSD.org> To: Nik Clayton <nik@FreeBSD.org> Cc: doc@FreeBSD.org, Udo Erdelhoff <ue@nathan.ruhr.de>, Chris Costello <chris@calldei.com> Subject: Re: Translators: Need feedback on FAQ reorganization Message-ID: <XFMail.010312153731.jhb@FreeBSD.org> In-Reply-To: <20010312231347.B75170@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 02:51:56PM -0800, John Baldwin wrote:
>> >> 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.
>
> I'll leave it up to Chris and the folks doing the work as to whether or
> not they think the FAQ will be confusing to readers during the
> transition.
Fair enough, they were just soliciting opinions anyways, and now they've heard
both of ours.
>
>> > 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. :)
>
> Oh yes it was. ("Oh no it wasn't!" "Oh yes it was!"). I have the RSI to
> prove it.
I have the bad memory to prove, uh, that, uh... :-P I just recalled seeing the
README thrown up somewhere on a website for reference after the fact and
confusedly thought that all of the work was OOB and committed when it was done.
*sigh* Your set of commits is exactly what it desired, but since we aren't
changing markup just physical location of chunks of text, I think we don't need
to do this on the side.
>> 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.
>
> Chris?
Chris Costello. He's already split up the FAQ and done all this rewriting
work, etc. He's the one asking for how to do this. :) The only trick is that
he has content changes mixed in with the moving bits around part, so he can't
just do one mega commit. Instead, he needs to basically redo the moving bits
around part first as a set of commits (possibly one gigantic commit if he's
really a glutton for punishment) and once that is done start folding in the
content changes he has in his local tree.
>> 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?
>
> I'm not concerned about the authors, it's the people reading the FAQ on
> the website that I'm worried about. Is there going to a period of time
> during which the FAQ is difficult for them to use? Chris is the person
> best placed to answer that.
Err, he's just changing the layout in SGML for the first step, it should have
zero effect on what the FAQ looks like once it is formatted. This allows all
the translators to know where to split it up into their respective individual
files. Once the actual split up is done, each of the chapters can be committed
to with the normal rules. Think of the faq.sgml split up as a bunch of
whitespace commits.
--
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.010312153731.jhb>