Date: Thu, 2 Dec 2004 20:57:39 +0100 From: "Simon L. Nielsen" <simon@FreeBSD.org> To: Marc Fonvieille <blackend@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: Doc BoF at EuroBSDCon Message-ID: <20041202195739.GK753@zaphod.nitro.dk> In-Reply-To: <20041128211444.GC6664@abigail.blackend.org> References: <20041128202656.GL750@zaphod.nitro.dk> <20041128211444.GC6664@abigail.blackend.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--5cSRzy0VGBWAML+b Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On 2004.11.28 22:14:44 +0100, Marc Fonvieille wrote: > 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 >=20 > Why? Why a move to XML? The main reason would be that a lot of new tools work with XML. We already use some e.g. for the mirror section, and having the DocBook as real XML should make it less painful to add more like that. Also, rumor has it that the XML based DocBook tools is a lot faster. Also it's really nice to be able to do preprocessing using XSLT, which is, while not perfect, far less painful that DSSSSSSL/Scheme. > > - 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 > [...] >=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. Well, I don't know how many places it would apply, but what I was thinking of was doing someting like this : <para>To restart sshd run:</para> <screen rel=3D"4">kill -HUP `cat /var/run/sshd.pid`</screen> <screen rel=3D">4">/etc/rc.d/sshd reload</screen> Or something like that. When we don't want to support a release more it should be trivial to remove stuff for an old branch. > 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. Well, this was a list of stuff we talked about, not prioritized and certainly not a complete doc TODO. That said, I agree the FAQ is something that should be dealt with. --=20 Simon L. Nielsen --5cSRzy0VGBWAML+b Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.6 (FreeBSD) iD8DBQFBr3Ozh9pcDSc1mlERApzOAKCrdONzMsf3F5N8/po9Lo97YHnCLwCfZpnp lUPtJ2kpdrzj5Crng+0f4Ro= =ChZm -----END PGP SIGNATURE----- --5cSRzy0VGBWAML+b--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20041202195739.GK753>