Date: Thu, 31 Jan 2013 05:12:15 +0900 (JST) From: Hiroki Sato <hrs@FreeBSD.org> To: gabor@FreeBSD.org Cc: doc@FreeBSD.org Subject: Re: RFC: Dealing with version-specific docs Message-ID: <20130131.051215.1551317688782223614.hrs@allbsd.org> In-Reply-To: <51065CFC.5090803@FreeBSD.org> References: <51065CFC.5090803@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
----Security_Multipart(Thu_Jan_31_05_12_15_2013_220)-- Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Gabor Kovesdan <gabor@freebsd.org> 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: <para os="freebsd8" >8.X specific</para> <para os="freebsd9" >9.X specific</para> <para os="freebsd10">10.X specific</para> but we cannot write the common part like this: <para os="freebsd8 freebsd9">8.X and 9.X specific</para> <para os="freebsd10">10.X specific</para> 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)----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20130131.051215.1551317688782223614.hrs>