From owner-freebsd-doc@FreeBSD.ORG Mon Feb 4 04:17:24 2013 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 9EFC6F29; Mon, 4 Feb 2013 04:17:24 +0000 (UTC) (envelope-from gkeramidas@gmail.com) Received: from mail-ea0-f169.google.com (mail-ea0-f169.google.com [209.85.215.169]) by mx1.freebsd.org (Postfix) with ESMTP id 03275B6A; Mon, 4 Feb 2013 04:17:23 +0000 (UTC) Received: by mail-ea0-f169.google.com with SMTP id d13so2626249eaa.28 for ; Sun, 03 Feb 2013 20:17:22 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=x-received:sender:date:from:to:cc:subject:message-id:references :mime-version:content-type:content-disposition:in-reply-to; bh=06fZ5CkCDu9yZQrYu6q+NvKA0LyMLM5yF1lz+ykS8Vo=; b=W7ODA78uN0DgDdvYvOE2YktOEiz7TDNYP2OazEO5RPVsjE31IuTg5hLUet90I0PPOR lBO8Vfp/I0dqSB63yG/ujU/pAJbGf54sFlf0mHpwO/e4b3gIvCj1nuglnfZRq/JyyXDk YIfmH7CfRDYNDZegr8l0F1WQOBvVbksX1lnlFW2tmXNxjqJLIr/dKoopjDs3vK1oi15O E61MMqLDIjyaQW4v1COLqccDW8LHKOlkoJYllWJmJX62MpSk4lmHTGwkGXZtFjNqHmk8 kjTtHElQmK2MRskZw++LDeE5W5ZFECbVoxq8uf04Xw2x07YjIa5FrNXZvZbxTIPY6lIP fJhw== X-Received: by 10.14.198.198 with SMTP id v46mr67433616een.4.1359951442690; Sun, 03 Feb 2013 20:17:22 -0800 (PST) Received: from kobe (217-162-217-29.dynamic.hispeed.ch. [217.162.217.29]) by mx.google.com with ESMTPS id 3sm25193841eej.6.2013.02.03.20.17.21 (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Sun, 03 Feb 2013 20:17:21 -0800 (PST) Sender: Giorgos Keramidas Date: Mon, 4 Feb 2013 05:17:18 +0100 From: Giorgos Keramidas To: Gabor Kovesdan Subject: Re: RFC: Dealing with version-specific docs Message-ID: <20130204041717.GA68155@kobe> References: <51065CFC.5090803@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <51065CFC.5090803@FreeBSD.org> Cc: doc@FreeBSD.org X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 04 Feb 2013 04:17:24 -0000 On 2013-01-28 12:11, Gabor Kovesdan wrote: > Hi, > > as you may know, the printed edition of FreeBSD Handbook is being > worked. In our current Handbook version, we have version-specific > information for different major releases, while the printed edition > shall concentrate on 9.X. We cannot just drop the parts that detail > older releases since they haven't yet reached EOL and there are > people out there still using these. So we have to deal somehow with > this situation. Fortunately, DocBook provides a mechanism, called > profiling, which we could use. It would also be beneficial for later > cleanup work since finding outdated information that has to do with > unsupported releases always requires big effort. I've made a draft > about how it could be done in a practical way: > https://wiki.freebsd.org/VersionSpecificDocs > > Please read it and if you have doubts, concerns or better > suggestions, please share them. I like the use of os= attributes, but I feel a bit at odds with the requirement to duplicate version information in the XML attribute *and* the contained text, e.g.: To do foobar on &os; 8.X, type bar. To do foobar on &os; 9.X, type baz. We are typing version numbers twice here, and this introduces both the possibility for error and the chance for missing important mismatches in XML attributes vs. actual text. Is there any way we can avoid typing the version numbers twice?