Date: Mon, 29 Nov 2004 06:03:20 +0000 From: Nik Clayton <nik@FreeBSD.org> To: "Simon L. Nielsen" <simon@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: Doc BoF at EuroBSDCon Message-ID: <20041129060320.GA26868@clan.nothing-going-on.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
--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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20041129060320.GA26868>