From owner-freebsd-doc@FreeBSD.ORG Tue Feb 5 10:20:45 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 6BECFCFA; Tue, 5 Feb 2013 10:20:45 +0000 (UTC) (envelope-from gkeramidas@gmail.com) Received: from mail-bk0-f46.google.com (mail-bk0-f46.google.com [209.85.214.46]) by mx1.freebsd.org (Postfix) with ESMTP id CD476B16; Tue, 5 Feb 2013 10:20:44 +0000 (UTC) Received: by mail-bk0-f46.google.com with SMTP id j5so3184823bkw.5 for ; Tue, 05 Feb 2013 02:20:38 -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=CfkkPkUa9nKXz0DJK0G3mwH9Jm64sbNLpmXcSq83Yag=; b=diMj7FjM6nLxZ4G9QyIFt+1M4SKmMuCOXo5kkOvg6+9Z2HxYR4ioBnucZhW9HEsHoe Fd7ZwZYrdQXXroTzxXZX2tuhNLvFORI+kQETR3GskYhpN3+Nx9Gzumdl9sP5TUvQJVGn ChBqiB4NNwut2nb3aTBNQLB+njJR+Mcg6uc7Ahfr5T78esE24GCXUgrO/5PqQUoZqiMV S75hnyzONsp5JnUGdo8RhAp5BlE2nT2zYzZbAhnFfREm2GBAb4FaRPR18bc5jcf5RqYI 0Yreo9ZcmEM05HKgxc3o+DcHHbmeX7L6HYn/SYteJlJTVWpSULfIDJUv2pTc1DHP6wbX 2dQA== X-Received: by 10.204.147.143 with SMTP id l15mr6478527bkv.28.1360059638440; Tue, 05 Feb 2013 02:20:38 -0800 (PST) Received: from saturn (217-162-217-29.dynamic.hispeed.ch. [217.162.217.29]) by mx.google.com with ESMTPS id x18sm2233710bkw.4.2013.02.05.02.20.37 (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Tue, 05 Feb 2013 02:20:37 -0800 (PST) Sender: Giorgos Keramidas Date: Tue, 5 Feb 2013 11:20:35 +0100 From: Giorgos Keramidas To: Gabor Kovesdan Subject: Re: RFC: Dealing with version-specific docs Message-ID: <20130205102033.GA28045@saturn> References: <51065CFC.5090803@FreeBSD.org> <20130204041717.GA68155@kobe> <510F7E82.9000708@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <510F7E82.9000708@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: Tue, 05 Feb 2013 10:20:45 -0000 On 2013-02-04 10:25, Gabor Kovesdan wrote: >Em 04-02-2013 05:17, Giorgos Keramidas escreveu: >> 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? > > Theoretically, we could render the marked sections differently and > then it would not require duplicated information. But in practice, > this requires heavy customization of our build process. We have to > customize different things: > > - The XSLT stylesheets used for XHTML output. This is quite easy, I > can do it without problems. > > - Either we keep using Jade for PS/PDF generation and then we have > to customize the DSSSL stylesheets. DSSSL is a dead and badly > documented standard and I practically don't know anything about it > so we need to find someone, who is willing to do it. It is not easy > because it never became widely used and there is no free reference > or documentation about it. It also raises the question whether it is > worth investing time and effort in something that is so outdated. > > - Or we allow Java dependency just for the printed output formats > (XHTML would still be generated without Java) and then we need to do > the customizations in XSLT/XSL FO, which is much easier and I can do > it myself. I think it's a worthy goal to avoid the huge size of Java dependency for a while, and I've seen that there are efforts to write alternatives to tools like Saxon. For example there was a time that I saw even xmlroff being discussed for PDF output. I don't recall right now if it was you, Gabor, that brought xmlroff to my attention. Modernizing the entire toolchain behind textproc/docproj is a large project though. It may require a great upfront investment of time and effort. So I'm not sure if it makes sense to gate other work on this being completed first. If we can do our work with the current tools, even if it means we have a bit of duplication like the one you proposed, I think we should go for this instead of going the Java way. Then if we can find a PDF output toolchain better than DSSSL (for values of 'better' like 'more modern', 'easier to grok', 'faster' or some other possibility) we can adapt the tools later. > I mentioned these problems at EuroBSDCon but people were quite > reluctant about the Java dependency even though the XHTML part would > still work without Java. I think that I have to raise this issue > again. I've been working on improving the doc tree to use up to date > and better standards than the earlier ones and now I have a branch > with some important updates. I've maintained compatibility with Jade > but sooner or later we'll have to move away from it. The trivial way > is using Fop (a Java-based XSL FO renderer), which all other open > source projects do that use XML-based documentation. > Some people suggested generating PDF from XHTML which imho is a bad > option since XHTML is not a paper-oriented markup so we loose features > in that way, so I don't believe in its success and I'm not really > willing to work on botches. Now I'll bring the tree technologically up > to date until the point where we can avoid Java but then we will have > to choose how to go beyond. XHTML is definitely a very bad option as an intermediate format for PDF output. PDF has all these typographically appealing capabilities that we instantly lose just by going through XHTML. It would make more sense to transform docbook-xml to some other intermediate format, e.g. even plain LaTeX, or even to explore the possibility of using ConTeXt for XML->PDF output: http://wiki.contextgarden.net/XML I admit I have only done very simple things with ConTeXt and XML, so it's probably a wild idea. I'm just mentioning it as a more output-quality oriented way of producing PDF output, instead of losing pretty much everything in an XHTML temporary stage.