Date: Thu, 2 Dec 2004 21:49:48 +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: <20041202204948.GC78684@abigail.blackend.org> In-Reply-To: <20041202195739.GK753@zaphod.nitro.dk> References: <20041128202656.GL750@zaphod.nitro.dk> <20041128211444.GC6664@abigail.blackend.org> <20041202195739.GK753@zaphod.nitro.dk>
next in thread | previous in thread | raw e-mail | index | archive | help
--BOKacYhQ+x31HxR3 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Thu, Dec 02, 2004 at 08:57:39PM +0100, Simon L. Nielsen wrote: > >=20 > > Why? Why a move to XML? >=20 > 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. >=20 > Also it's really nice to be able to do preprocessing using XSLT, which > is, while not perfect, far less painful that DSSSSSSL/Scheme. > You're right, DSSSL is not easy to deal with, I don't know if a XSLT solution can replace our DSSSL system. > > > - 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. >=20 > Well, I don't know how many places it would apply, but what I was > thinking of was doing someting like this : >=20 > <para>To restart sshd run:</para> >=20 > <screen rel=3D"4">kill -HUP `cat /var/run/sshd.pid`</screen> >=20 > <screen rel=3D">4">/etc/rc.d/sshd reload</screen> >=20 > 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. >=20 [...] I just had a look to 2 recent/rewritten sections that I know a bit (the sound card one and the scanner one), and I ended to this opinion: it's possible to do "release versions" without pain when text is written in a clean way (by "clean" I mean in thinking about branches version). For example with the scanner section, it's really easy cause I tried to write it in separating the specific release version informations. With the sound card section we will end up to quite 2 differents sections. So most of time it should be easy to do release versions of docs. I think we will also need to be able to specify the release version for some inline element like filename etc. Marc --BOKacYhQ+x31HxR3 Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.4 (FreeBSD) iD8DBQFBr3/q81T1MWxkgcoRAslTAJ93yrFucClkxa2+puH1I/+/CchWBgCeJQ0A 2ke8h6ywANd1fCo6MzBrCUY= =DdXU -----END PGP SIGNATURE----- --BOKacYhQ+x31HxR3--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20041202204948.GC78684>