From owner-freebsd-doc@FreeBSD.ORG Thu Dec 2 20:50:33 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 5797B16A4E1; Thu, 2 Dec 2004 20:50:33 +0000 (GMT) Received: from abigail.blackend.org (blackend.org [212.11.35.229]) by mx1.FreeBSD.org (Postfix) with ESMTP id DD0FA43D53; Thu, 2 Dec 2004 20:50:31 +0000 (GMT) (envelope-from marc@blackend.org) Received: from abigail.blackend.org (localhost [127.0.0.1]) iB2Knmm1081596; Thu, 2 Dec 2004 21:49:49 +0100 (CET) (envelope-from marc@abigail.blackend.org) Received: (from marc@localhost) by abigail.blackend.org (8.12.11/8.12.11/Submit) id iB2KnmxJ081595; Thu, 2 Dec 2004 21:49:48 +0100 (CET) (envelope-from marc) Date: Thu, 2 Dec 2004 21:49:48 +0100 From: Marc Fonvieille To: "Simon L. Nielsen" Message-ID: <20041202204948.GC78684@abigail.blackend.org> References: <20041128202656.GL750@zaphod.nitro.dk> <20041128211444.GC6664@abigail.blackend.org> <20041202195739.GK753@zaphod.nitro.dk> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="BOKacYhQ+x31HxR3" Content-Disposition: inline In-Reply-To: <20041202195739.GK753@zaphod.nitro.dk> User-Agent: Mutt/1.4.2.1i X-Useless-Header: blackend.org X-Operating-System: FreeBSD 4.10-PRERELEASE cc: freebsd-doc@FreeBSD.org Subject: Re: Doc BoF at EuroBSDCon X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 02 Dec 2004 20:50:33 -0000 --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 > To restart sshd run: >=20 > kill -HUP `cat /var/run/sshd.pid` >=20 > 4">/etc/rc.d/sshd reload >=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--