From owner-freebsd-doc Tue Oct 26 14:36:49 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 35F0314D2F for ; Tue, 26 Oct 1999 14:36:40 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18]) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id WAA49964 for ; Tue, 26 Oct 1999 22:31:26 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Received: (from nik@localhost) by kilt.nothing-going-on.org (8.9.3/8.9.3) id WAA20848 for doc@freebsd.org; Tue, 26 Oct 1999 22:21:11 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Date: Tue, 26 Oct 1999 22:21:11 +0100 From: Nik Clayton To: doc@freebsd.org Subject: [bortzmeyer@debian.org: Re: DOCBOOK: DocBook-XML and conditional sections] Message-ID: <19991026222111.A19720@kilt.nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i Organization: Nik at home, where there's nothing going on Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org I'm forwarding this (somewhat late) as requested. Stephane's on holiday at the moment, and back at the beginning of November. I like the solution though, and think it's something we should probably adopt to solve our versioning problems. I've asked Stephane to consider making the attribute names OS neutral (i.e., osversionmin, and so on) so that documents are more easily portable between us. I would have no qualms about recommending that we write something like The foo was is called bar in FreeBSD 2.2.2. or similar. That's a bit of a mouthful to write, and we could use general entities relatively easily, something like ... ... What's also nice about this is that we can put constraints in (our) DTD (which can be turned on or off with a parameter entity) to ensure that mistakes like (i.e., a typo in the attribute value) are spotted by the SGML parser and flagged as errors. Thoughts? Assuming everyone likes this I'll wait for Stephane to get back from holiday, check out the issues above, and then commit something that implements it. N ----- Forwarded message from Stephane Bortzmeyer ----- From: Stephane Bortzmeyer To: Nik Clayton Subject: Re: DOCBOOK: DocBook-XML and conditional sections Date: Thu, 30 Sep 1999 12:24:56 +0200 [You can forward that on freebsd-doc if you think it's worth it.] On Thursday 30 September 1999, at 0 h 18, the keyboard of Nik Clayton wrote: > Our docs are under revision control, but we don't branch them with the OS. > There's too much common documentation, and you'd end up doing frequent > merges from one branch to another. Well, Debian has several branches and the documentation manager merges them from time to time. But I wanted to try a pure SGML solution. > I don't think this scales well, and it makes it difficult to pull out > a version of the documentation which (for example) only contains text > appropriate for version 3.1 or 2.2.8. I finally added THREE attributes: debianversionequal, debianversionmin and debianversionmax. The first one is for info which depends on one specific release, the other two (which can be combined) is for more traditional info ("Starting from 2.2...", "Until version 1.1"). In the filtering program, you just have to write a comparison function which works for you (RELENG_3 > RELENG_22, despite what the math says). > A pre-processor would go through the SGML, leaving only those elements > that either have no OS attribute, or have a specific value in it. I have written such a pre-processor, if you like (a few lines of Perl + XML::DOM). > 3. Use parameter entities; Does not allow ranges, such as 2.2 < version < 3.1. > and so on. Still quite cumbersome, but doesn't need a pre-processor > to strip out elements with the wrong OS attribute value. And do not work with XML. ----- End forwarded message ----- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message