Date: Sat, 19 Aug 2006 02:56:54 +0900 (JST) From: Hiroki Sato <hrs@FreeBSD.org> To: doc@FreeBSD.org Subject: HEADS UP: www cleanup mega-patch will be committed soon (Re: www/ cleanup patch) Message-ID: <20060819.025654.124039241.hrs@allbsd.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
----Security_Multipart(Sat_Aug_19_02_56_54_2006_045)-- Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Hi all, Hiroki Sato <hrs@freebsd.org> wrote in <20060716.204810.57466384.hrs@allbsd.org>: hr> I am working on unifying of duplicated information between doc/www hr> or SGML/XML such as developers.sgml, but upon doing the work hr> I notice that we need some cleanups of the build infrastructure. hr> hr> A work-in-progress patch can be found at: hr> hr> http://people.allbsd.org/~hrs/FreeBSD/www_cleanup-20060716.tar.gz A complete patch including changes for non-English parts has been ready. It can be found at: http://people.allbsd.org/~hrs/FreeBSD/www-cleanup-20060819.tar.gz I am planning to commit this within the next 48 hours if there is no objection. Basically there is no content change in the build results, but 76 files which have duplicated information in some way will be removed. Please note that this patch needs >docproj-1.16. To doc committers who are working on translation: Please review this, especially a part of this patch related to your work area. Note that after applying it we do not always have 1:1 relationship between an original and the translated file, so some "original revision" lines will be meaningless. Also, some translated parts might be regressed; some parts might be replaced with sentences in the English counterpart, I mean. I will fix them individually after the commit if any. If you have comments/suggestions/objections about this patch, please let me know. Thanks. -- | Hiroki SATO (from README in the tarball) Changes include: - Add "make lint" for validating XML files in $XMLDOCS. - Restructure various include files: * lang/includes.nav*.sgml --> share/sgml/navibar.ent lang/share/sgml/navibar.l10n.ent To activate the side navigation bar, we need the following line only in the DOCTYPE declaration now: <!ENTITY % navinclude.FOO "INCLUDE"> Actually FOO is replaced with "about", "community", "developers", and so on. navibar.l10n.ent is for full/partial translation. * includes.sgml in various location --> share/sgml/common.ent share/sgml/header.ent lang/share/sgml/l10n.ent lang/share/sgml/header.l10n.ent Scattered includes.sgml have been integrated. Please do not add this sort of files anymore. It makes maintenance and translation very difficult. l10n.ent is for full/partial translation. * XSLT libraries --> share/sgml/*.xsl share/sgml/libcommon.xsl lang/share/sgml/libcommon.xsl Most of XSLT stylesheet can be shared between the English document and the translation, so move them to the language independent directory. lang/share/sgml/libcommon.xsl is for full/partial translation. - 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 wrongly believe &foo; cannot be used in an XML file, and <xsl:variable> should be used in XSLT, but it is not correct. 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. For translation we do not need to stick to using entity references for Latin characters, but in English documents expression in ASCII characters only are preferred. - 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. - gnome/*, platforms/ia64 Similar changes to news/* has been applied, but probably the news.xml can be integrated into news/news.xml and stylesheets in news/ can be reused. I am still working on such cleanups. - future plans for various news.xml-like files I am planning to unify such files by adding a tag for categorization to each item. ----Security_Multipart(Sat_Aug_19_02_56_54_2006_045)-- Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (FreeBSD) iD8DBQBE5f9qTyzT2CeTzy0RAhzLAJ9kJt+a+sJOccIX0O4NVHbGLZ0TKgCfUWhq 2n8g3KQ/Dl91WIz6rZXZjKc= =qwJ3 -----END PGP SIGNATURE----- ----Security_Multipart(Sat_Aug_19_02_56_54_2006_045)----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060819.025654.124039241.hrs>