From owner-freebsd-doc@FreeBSD.ORG Mon Nov 29 06:03:26 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 D762316A4CE; Mon, 29 Nov 2004 06:03:26 +0000 (GMT) Received: from jc.ngo.org.uk (jc.ngo.org.uk [69.55.225.33]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0CB3043D46; Mon, 29 Nov 2004 06:03:26 +0000 (GMT) (envelope-from nik@crf-consulting.co.uk) Received: from crf-consulting.co.uk (82-44-220-218.cable.ubr10.haye.blueyonder.co.uk [82.44.220.218]) by jc.ngo.org.uk (8.12.11/8.13.1) with ESMTP id iAT63Oi2027058; Sun, 28 Nov 2004 22:03:25 -0800 (PST) (envelope-from nik@crf-consulting.co.uk) Received: from clan.nothing-going-on.org (clan.nothing-going-on.org [192.168.1.20])iAT63LpQ070918; Mon, 29 Nov 2004 06:03:21 GMT (envelope-from nik@catkin) Received: from clan.nothing-going-on.org (localhost [127.0.0.1]) iAT63L2S041770; Mon, 29 Nov 2004 06:03:21 GMT (envelope-from nik@clan.nothing-going-on.org) Received: (from nik@localhost) by clan.nothing-going-on.org (8.13.1/8.13.1/Submit) id iAT63LpF041769; Mon, 29 Nov 2004 06:03:21 GMT (envelope-from nik) Date: Mon, 29 Nov 2004 06:03:20 +0000 From: Nik Clayton To: "Simon L. Nielsen" Message-ID: <20041129060320.GA26868@clan.nothing-going-on.org> References: <20041128202656.GL750@zaphod.nitro.dk> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="azLHFNyN32YCQGCU" Content-Disposition: inline In-Reply-To: <20041128202656.GL750@zaphod.nitro.dk> User-Agent: Mutt/1.4.2.1i Organization: FreeBSD Project 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: Mon, 29 Nov 2004 06:03:27 -0000 --azLHFNyN32YCQGCU 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: > - 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... In case you're not aware, 'xml' is a supported output FORMAT. You should be able to do make FORMAT=3Dxml in any of the document directories and get book.xml or article.xml generated as appropriate. I strongly recommend that you do this and experiment with getting an XML/XSL toolchain in place *before* doing a full cutover to XML. You are also aware of doc/share/xsl, right? And that you can do: make STYLESHEET_TYPE=3Dxsl ... ? > - 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.. Don't do that. The point of the subdirectories is so that all the files associated with a chapter (images, example files, and so on) are kept together with that chapter. Otherwise you'll end up down the road with filenames like vinum-foo.png vinum-bar.png x11-foo.png x11-bar.png and so on. All you've done is swapped the '/' for a '-'. It also lets you split up the chapter.sgml files in to smaller files, with a single chapter.sgml 'driver' file (in the same way that things like book.sgml include all the chapter.sgml files). > - Redoing the build system (make files), because it clearly shows its > age and several things are broken, e.g. OBJDIR. Makes sense. I'd be happier seeing a comprehensive list of the things that are broken though, so we can measure the replacement and make sure it solves the problems. > - 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. Rather than branch it in CVS I'd say use Perforce for this work. > - 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 was suggested to handle this with (SG|X)ML attributes on like > done in the release documentation for different architectures. > simon was volunteered to implement this. The DocBook XSL stylesheets call this 'profiling'. See=20 http://docbook.sourceforge.net/release/xsl/current/doc/html/rn19.html for more details. All the changes discussed so far will also require updates to the Primer. Who volunteered to keep that up to date? N --=20 FreeBSD: The Power to Serve http://www.freebsd.org/ (__) FreeBSD Documentation Project http://www.freebsd.org/docproj/ \\\'',) \/ \= ^ --- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 --- .\._/= _) --azLHFNyN32YCQGCU Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.6 (FreeBSD) iD8DBQFBqruok6gHZCw343URAuQ5AKCLidW7gEoC3ijYNdWIjlLUmJ4DNwCfV4sG 8LxdoH2LQjTBddtZNbd+ANk= =TYLg -----END PGP SIGNATURE----- --azLHFNyN32YCQGCU--