From owner-freebsd-doc@FreeBSD.ORG Mon Aug 20 23:14:13 2012 Return-Path: Delivered-To: doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 68496106564A; Mon, 20 Aug 2012 23:14:13 +0000 (UTC) (envelope-from gabor@FreeBSD.org) Received: from server.mypc.hu (server.mypc.hu [87.229.73.95]) by mx1.freebsd.org (Postfix) with ESMTP id 14D448FC0A; Mon, 20 Aug 2012 23:14:12 +0000 (UTC) Received: from server.mypc.hu (localhost [127.0.0.1]) by server.mypc.hu (Postfix) with ESMTP id A4D9714E7F69; Tue, 21 Aug 2012 01:14:11 +0200 (CEST) X-Virus-Scanned: amavisd-new at server.mypc.hu Received: from server.mypc.hu ([127.0.0.1]) by server.mypc.hu (server.mypc.hu [127.0.0.1]) (amavisd-new, port 10024) with LMTP id Ur77P1NUAQX5; Tue, 21 Aug 2012 01:14:07 +0200 (CEST) Received: from [192.168.1.101] (D94162B4.catv.pool.telekom.hu [217.65.98.180]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (No client certificate requested) by server.mypc.hu (Postfix) with ESMTPSA id 7BF8D14E7F6B; Tue, 21 Aug 2012 01:14:07 +0200 (CEST) Message-ID: <5032C4BE.5080209@FreeBSD.org> Date: Tue, 21 Aug 2012 01:14:06 +0200 From: Gabor Kovesdan User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:13.0) Gecko/20120614 Thunderbird/13.0.1 MIME-Version: 1.0 To: Warren Block References: <50326A70.5020009@FreeBSD.org> In-Reply-To: X-Enigmail-Version: 1.4.3 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Cc: doceng@freebsd.org, doc@freebsd.org, www@freebsd.org Subject: Re: [CALL FOR REVIEW] doc and www converted to XML X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 20 Aug 2012 23:14:13 -0000 Em 21-08-2012 00:46, Warren Block escreveu: > First, a question: will the .sgml filenames be changed to .xml? Yes but maintaining a branch with full of renamed files is more messy than later renaming them in head. Probably we'll lock the tree for a very short time and do a bunch rename. > Second, a note on related software: a couple of days ago, Steve Wills > was gracious enough to make a port of Publican. Publican is the RedHat > doc tool, which takes XML DocBook 4.5 and renders them to HTML or PDF or > other formats. It has support for .po and .pot translation files. I > have not given it a serious test, but it may be useful now that we have > XML files. What benefits does it give us over directly calling the underlying tools? I see it uses XSLT to render HTML and it relies on FOP for PDF. This can be done with slight modifications of our Makefiles. Is it worth adding one more layer? It would mean more vendor dependency and performance penalty. From the documentation, my first impression is that it also introduces lots of proprietary things: directory layout, config files, commands and command-line parameters. [1] I think you can achieve the same things by our simple Makefile macros and direct editing of the XML files, which is not a high expectation towards doc committers but requiring to learn a totally proprietary system may not be that welcome. The translation support would be interesting but first we should evaluate if such a method is appropriate for us (having a small demo would be nice with a sample source and a sample translation file) and if so, we can very well "extract" the way it is done in Publican without having to adopt the whole system with the complexities and lots of dependencies. [2] Anyway, FOP is the best free renderer out for PDF but it depends on Java. Publican also uses FOP. Personally, I think we should get a compromise and depend on Java or otherwise we never will have modern features and outlook in our PDF documents. But some people will object so if we want quality we will have to convince them whether we use Publican or not. [1] http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Files_in_the_book_directory [2] https://fedorahosted.org/publican/wiki/Installing Gabor