Date: Sun, 28 Nov 2004 22:14:44 +0100 From: Marc Fonvieille <blackend@FreeBSD.org> To: "Simon L. Nielsen" <simon@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: Doc BoF at EuroBSDCon Message-ID: <20041128211444.GC6664@abigail.blackend.org> In-Reply-To: <20041128202656.GL750@zaphod.nitro.dk> References: <20041128202656.GL750@zaphod.nitro.dk>
next in thread | previous in thread | raw e-mail | index | archive | help
--nFreZHaLTZJo0R7j Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sun, Nov 28, 2004 at 09:26:57PM +0100, Simon L. Nielsen wrote: [...] >=20 > Discussed: >=20 > - Changing doc from SGML to XML (yes, really do it this time) >=20 > - des agreed to make a script for the actual conversion of the files > from SGML to XML. >=20 > - With SGML -> XML conversion we will loose the "IGNORE" > functionality from SGML, but it is not widely used, and where such > functionality is needed it can e.g. be handled in other ways. > This is used to be able to build sub directories in the Handbook, > but this has been broken for a while and nobody has complained > about that yet... >=20 Why? Why a move to XML? > - It was suggested to move chapter files to the main directory e.g. > en_US.ISO8859-1/books/handbook/x11/chapter.sgml -> > en_US.ISO8859-1/books/handbook/x11.sgml, since there does not seem > to a big point in all the sub directories, and make does not like > the sub directories well.. >=20 > - Redoing the build system (make files), because it clearly shows its > age and several things are broken, e.g. OBJDIR. >=20 > - To be as little disruptive as possible to normal doc work it was > suggested to branch the doc/ tree for the work, and do the work in a > separate branch, to be merged into the main branch later again. >=20 > - Handling multiple FreeBSD release branches (4.X/5.X/6.X) in Handbook > to get rid of notes about "For 4.X do....". There should be > multiple build Handbook versions on website, and perhaps one > complete one with "This section is for 4.X only..." and so on > automatically added. >=20 [...] It's true that when a new major version appears there are problems of multiple syntaxes, procedures for the same thing, etc. This multiple branches scheme seems to be really difficult to manage especially for persons who write the docs, I can't imagine the pain of having to deal with 3 versions of the same document because the reality is not so simple: a text cannot be simply divided in 3 versions or divided in a general overview part then in major version parts. I see one important thing missing in this list, an important thing for the reader: the merge of the FAQ in the Handbook. I'd put that on top of the list, very important informations are in the FAQ and people often miss them cause they are in another document, etc. Marc --nFreZHaLTZJo0R7j Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.4 (FreeBSD) iD8DBQFBqj/C81T1MWxkgcoRAjYIAJ42pUPrBg2XTZZIo65jUXEbIAEAPQCghIo3 eXzc8zB0cJMlzDMkJ+Ea3pQ= =zdXC -----END PGP SIGNATURE----- --nFreZHaLTZJo0R7j--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20041128211444.GC6664>