From owner-freebsd-doc@FreeBSD.ORG Tue Aug 21 00:16:33 2012 Return-Path: Delivered-To: doc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 6AFAB106564A; Tue, 21 Aug 2012 00:16:33 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 0DBC28FC0C; Tue, 21 Aug 2012 00:16:32 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.5/8.14.5) with ESMTP id q7L0GWn3085076; Mon, 20 Aug 2012 18:16:32 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.5/8.14.5/Submit) with ESMTP id q7L0GWdo085073; Mon, 20 Aug 2012 18:16:32 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Mon, 20 Aug 2012 18:16:32 -0600 (MDT) From: Warren Block To: Gabor Kovesdan In-Reply-To: <5032C4BE.5080209@FreeBSD.org> Message-ID: References: <50326A70.5020009@FreeBSD.org> <5032C4BE.5080209@FreeBSD.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed 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: Tue, 21 Aug 2012 00:16:33 -0000 On Tue, 21 Aug 2012, Gabor Kovesdan wrote: > 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. Agreed. I think the primary benefit would be taking advantage of a toolchain that someone else maintains. I don't know how well it would work for us. The nice thing is that with DocBook XML, the choice becomes available. > 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. With OpenJDK, Java is a lot less of a hassle than previously. > 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 >