Date: Sun, 16 Jul 2006 16:21:11 +0200 From: =?ISO-8859-1?Q?G=E1bor_K=F6vesd=E1n?= <gabor@FreeBSD.org> To: Hiroki Sato <hrs@FreeBSD.org> Cc: doc@FreeBSD.org Subject: Re: www/ cleanup patch Message-ID: <44BA4B57.7060602@FreeBSD.org> In-Reply-To: <20060716.204810.57466384.hrs@allbsd.org> References: <20060716.204810.57466384.hrs@allbsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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: > > <!ENTITY % include.nav.FOO "INCLUDE"> > > 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 > "<!ENTITY % includes SYSTEM "includes.sgml"> %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 <xsl:variable> 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 <categories> in the XML databases, and @continent > of <entry> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?44BA4B57.7060602>