From owner-freebsd-doc@FreeBSD.ORG Wed Jan 30 20:30:39 2013 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id BF2FA9DC; Wed, 30 Jan 2013 20:30:39 +0000 (UTC) (envelope-from hrs@FreeBSD.org) Received: from mail.allbsd.org (gatekeeper.allbsd.org [IPv6:2001:2f0:104:e001::32]) by mx1.freebsd.org (Postfix) with ESMTP id 6CC04367; Wed, 30 Jan 2013 20:30:39 +0000 (UTC) Received: from alph.allbsd.org (p1137-ipbf1505funabasi.chiba.ocn.ne.jp [118.7.212.137]) (authenticated bits=128) by mail.allbsd.org (8.14.5/8.14.5) with ESMTP id r0UKUMiN073281 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 31 Jan 2013 05:30:32 +0900 (JST) (envelope-from hrs@FreeBSD.org) Received: from localhost (localhost [127.0.0.1]) (authenticated bits=0) by alph.allbsd.org (8.14.5/8.14.5) with ESMTP id r0UKUKhp068012; Thu, 31 Jan 2013 05:30:22 +0900 (JST) (envelope-from hrs@FreeBSD.org) Date: Thu, 31 Jan 2013 05:12:15 +0900 (JST) Message-Id: <20130131.051215.1551317688782223614.hrs@allbsd.org> To: gabor@FreeBSD.org Subject: Re: RFC: Dealing with version-specific docs From: Hiroki Sato In-Reply-To: <51065CFC.5090803@FreeBSD.org> References: <51065CFC.5090803@FreeBSD.org> X-PGPkey-fingerprint: BDB3 443F A5DD B3D0 A530 FFD7 4F2C D3D8 2793 CF2D X-Mailer: Mew version 6.5 on Emacs 23.4 / Mule 6.0 (HANACHIRUSATO) Mime-Version: 1.0 Content-Type: Multipart/Signed; protocol="application/pgp-signature"; micalg=pgp-sha1; boundary="--Security_Multipart(Thu_Jan_31_05_12_15_2013_220)--" Content-Transfer-Encoding: 7bit X-Virus-Scanned: clamav-milter 0.97.4 at gatekeeper.allbsd.org X-Virus-Status: Clean X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7 (mail.allbsd.org [133.31.130.32]); Thu, 31 Jan 2013 05:30:32 +0900 (JST) X-Spam-Status: No, score=-97.6 required=13.0 tests=CONTENT_TYPE_PRESENT, FAKEDWORD_ATMARK, ONLY1HOPDIRECT, SAMEHELOBY2HOP, USER_IN_WHITELIST autolearn=no version=3.3.2 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on gatekeeper.allbsd.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: Wed, 30 Jan 2013 20:30:39 -0000 ----Security_Multipart(Thu_Jan_31_05_12_15_2013_220)-- Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Gabor Kovesdan wrote in <51065CFC.5090803@FreeBSD.org>: ga> Hi, ga> ga> as you may know, the printed edition of FreeBSD Handbook is being ga> worked. In our current Handbook version, we have version-specific ga> information for different major releases, while the printed edition ga> shall concentrate on 9.X. We cannot just drop the parts that detail ga> older releases since they haven't yet reached EOL and there are people ga> out there still using these. So we have to deal somehow with this ga> situation. Fortunately, DocBook provides a mechanism, called ga> profiling, which we could use. It would also be beneficial for later ga> cleanup work since finding outdated information that has to do with ga> unsupported releases always requires big effort. I've made a draft ga> about how it could be done in a practical way: ga> https://wiki.freebsd.org/VersionSpecificDocs ga> ga> Please read it and if you have doubts, concerns or better suggestions, ga> please share them. I have no objection to use @os (or some other attrs) for conditional text, but it may need an attention that profiling feature of DocBook XSLT is exclusive, IIRC. What I mean by "exclusive" is that it works for elements for each version like this: 8.X specific 9.X specific 10.X specific but we cannot write the common part like this: 8.X and 9.X specific 10.X specific In a past, I created and used a patch (for another project) to support multiple keywords and negation (condition="!print" for ignoring it only in printable formats) in an attr for profiling because some more flexibility was needed. However, in this case there is another drawback that validation is not possible and a typo in the profiling attr, "freedsb8" for example, is silently ignored. There is no problem with marking a part of documents by using attrs as long as it is in a consistent way. -- Hiroki ----Security_Multipart(Thu_Jan_31_05_12_15_2013_220)-- Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (FreeBSD) iEYEABECAAYFAlEJfp8ACgkQTyzT2CeTzy2u6gCgoR/bzCwADAiWXWjOCEL2NSW2 QWAAoKllKGNxxJou2ucKQLyx/VlylqJE =EtOW -----END PGP SIGNATURE----- ----Security_Multipart(Thu_Jan_31_05_12_15_2013_220)----