From owner-freebsd-doc@FreeBSD.ORG Sun Jul 16 14:21:33 2006 Return-Path: X-Original-To: doc@FreeBSD.org Delivered-To: freebsd-doc@FreeBSD.ORG Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 4D68A16A4DD; Sun, 16 Jul 2006 14:21:33 +0000 (UTC) (envelope-from gabor@FreeBSD.org) Received: from server.t-hosting.hu (server.t-hosting.hu [217.20.133.7]) by mx1.FreeBSD.org (Postfix) with ESMTP id C22DB43D46; Sun, 16 Jul 2006 14:21:29 +0000 (GMT) (envelope-from gabor@FreeBSD.org) Received: from localhost (localhost [127.0.0.1]) by server.t-hosting.hu (Postfix) with ESMTP id 983B099AEF8; Sun, 16 Jul 2006 16:21:27 +0200 (CEST) X-Virus-Scanned: amavisd-new at t-hosting.hu Received: from server.t-hosting.hu ([127.0.0.1]) by localhost (server.t-hosting.hu [127.0.0.1]) (amavisd-new, port 10024) with LMTP id ZXkGs51x3DLC; Sun, 16 Jul 2006 16:21:19 +0200 (CEST) Received: from [192.168.2.186] (catv-50635cb6.catv.broadband.hu [80.99.92.182]) by server.t-hosting.hu (Postfix) with ESMTP id 1795099AEE8; Sun, 16 Jul 2006 16:21:19 +0200 (CEST) Message-ID: <44BA4B57.7060602@FreeBSD.org> Date: Sun, 16 Jul 2006 16:21:11 +0200 From: =?ISO-8859-1?Q?G=E1bor_K=F6vesd=E1n?= User-Agent: Thunderbird 1.5.0.4 (Windows/20060516) MIME-Version: 1.0 To: Hiroki Sato References: <20060716.204810.57466384.hrs@allbsd.org> In-Reply-To: <20060716.204810.57466384.hrs@allbsd.org> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Cc: doc@FreeBSD.org Subject: Re: www/ cleanup patch X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: gabor@t-hosting.hu List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 16 Jul 2006 14:21:33 -0000 Hiroki Sato wrote: > Hi all, > > I am working on unifying of duplicated information between doc/www > or SGML/XML such as developers.sgml, but upon doing the work > I notice that we need some cleanups of the build infrastructure. > > A work-in-progress patch can be found at: > > http://people.allbsd.org/~hrs/FreeBSD/www_cleanup-20060716.tar.gz > > and the changes attached at the end of this email. Basically > it is for improving consistency and maintainability of our SGML and > XML docs, and does not involve almost no content change. > > Comments? While I am still working on this including necessary > changes for translation, I would like your comments on my basic > idea if you have. This is a big sweeping change, so I will send > the ready-to-commit patch set again before the actual commit. Thanks. > > -- > | Hiroki SATO > > (from README in the tarball) > > - Add "make lint" for validating XML files in $XMLDOCS. > > - Restructure various include files: > > * lang/includes.nav*.sgml --> share/sgml/navibar.ent > > To activate the side navigation bar, we need the following line > only in the DOCTYPE declaration now: > > > > Actually FOO is replaced with "about", "community", "developers", > and so on. > This is a great idea, but how this applies to translations? Do they still need a bunch of custom include files or can we add files like navibar.lang.ent to share/sgml? > * includes.sgml in various location --> share/sgml/common.ent > > Scattered includes.sgml have been integrated. Please do not > add this sort of files anymore. It makes maintenance and > translation very difficult. > > - Switch to custom DTDs > > Now we use "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension" > for HTML docs, which is HTML 4.01 + some entities previously pulled via > " %includes;" line. > The location of entity file will be resolved by using catalog file. > > Also, DTDs for XML databases and XSLT stylesheets have been added. > These DTDs makes the following possible: > > * Removal of {$foo} and &foo; pairs which have duplicate information > > Most of developers believe &foo; cannot be used in an XML file, > and should be used in XSLT, but it is a wrong idea. > A lot of duplicated {$foo} have been removed since &foo; can be > used even when in an XML file now. > > * &#nnn; v.s. &symbolic; > > We can now use &symbolic; like á even in an XML file. > This should improve the maintainability and useful for Latin > characters. Please make sure that textproc/xmlcharent is installed > in your system before trying. I will add it to the dependency > of the docproj port. > > Probably most of numeric references should be replaced > if there is no specific reason. > Great! As I am translating the webpages to Hungarian, using character codes instead of á é etc. was a headache to me. > - commercial/*.xml handling > > The *.xsl files have been rewritten and unified. It uses > a new element in the XML databases, and @continent > of is deprecated. I think the *.xml and > the new xsl file should be in share/sgml, and > I will implement partial translation like newsflash into it, too. > > - events/*.xml handling > > curdate.xml has been removed and exslt:date extension is > used instead. events.dtd has been moved to share/sgml. > > - news/* > > Automatic replace of $base in news.xml has been removed > because we can now use &base; straightforward. > There is still room for improvement; more reuse of > XML stylesheet, database unification, and so on. > > For these tree sections, is there a good way to use the English xml files in translations? Since some translations have very limited human resources, translated news is hard to keep up-to-date. The Hungarian translation will be such thing, since only I am working on that, and we don't even have a Hungarian committer. I looked at the French codebase, they just take the English xml from the Makefile: newsflash.html: newsflash.xsl news.xml\ includes.xsl ${XML_INCLUDES} ${XSLTPROC} ${XSLTPROCOPTS} -o ${.TARGET} \ --param "news.project.xml-master" "'${XML_NEWS_NEWS_MASTER}'" \ --param "news.project.xml" "'${XML_NEWS_NEWS}'" \ --param "transtable.xml" "'${XML_TRANSTABLE}'" \ ${.CURDIR}/newsflash.xsl ${.CURDIR}/news.xml Accordingly, the French webpages have to be rebuilt always when somebody commits some news to www/en to be up-to-date. Do you have any idea how this can be done better? -- Cheers, Gabor