Date: Mon, 12 Mar 2001 00:35:18 +0100 From: Udo Erdelhoff <ue@nathan.ruhr.de> To: doc@FreeBSD.org Subject: Re: Translators: Need feedback on FAQ reorganization Message-ID: <20010312003518.A77178@nathan.ruhr.de> In-Reply-To: <20010311125040.E31751@holly.calldei.com>; from chris@calldei.com on Sun, Mar 11, 2001 at 12:50:40PM -0600 References: <20010311125040.E31751@holly.calldei.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Chris, On Sun, Mar 11, 2001 at 12:50:40PM -0600, Chris Costello wrote: > Currently, the FreeBSD FAQ is just one big SGML file. I've > been breaking it up and making the document structure more like > the structure of the Handbook. I've just downloaded the (rather old) snapshot of your work from your homepage at people.freebsd.org and I'll just that snapshot as the base for my comments. I've noticed a couple of things that worry me: 1) Most questions didn't have an SGML id. Please do not remove the ids, they are extremly valuable to point users into the right direction. 2) Please do not use the <name>/chapter.sgml structure of the handbook. make is perfectly capable of handling more than one source file in a directory. We don't need all those additional subdirectories and they make it easier to become lost in the sources. Imaging having 5 or 6 editor windows (or screens, in my case), all editing "chapter.sgml". 3) Please try to keep the SGML sources free of tabs. See the last commit to the original FAQ. > This has required me to move and rewrite some questions and answers. > However, a lot of the text is essentially the same. At the same time, > though, I'm adding some new questions and answers, combining some of > them, and removing others. And that's the real problem. The policy for changing the documentation is quite simple: "Do not mix content and whitespace changes." Moving the questions into different source files is a whitespace change, rewriting existing answers and adding new entries is a content change. > I'm open to any ideas that you may have--what should I do? We (the translators) will have to make the same changed you make and you should make it possible for us to recreate your work. The easiest way to achieve this is to set up a seperate CVS repository[0] that writes a logfile of the commits, makes this logfile available to the translation teams, and gives the translators read-only access. Check in the current version of the FAQ as Revision 1.1. Start moving the questions, one target a file at a time. In other words, if you create application.sgml, move all the questions about applicaitons into that file, add the neccessary SGML glue, and commit that change to your local repository. Do not rewrite the existing questions, do not add new questions. Just a simple move. Repeat the process until you've redistributed all the existing questions to your satisfaction. Start adding the new questions and commit them one question at a time. This way, the translations teams can easily split the work. Now you can start editing/rewording questions. Group your changes into logical blocks, modify only one file at a time, and commit each block seperately. /s/Udo [0] It might be possible to use the "our" repository (i.e. that of the FreeBSD German Documentation Project) for this purpose. I'll talk to Alexander Langer (alex@big.endidan.de) about it, it's his box. -- Abandon the search for Truth; settle for a good fantasy. 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?20010312003518.A77178>