Date: Sun, 16 Jul 2006 20:48:10 +0900 (JST) From: Hiroki Sato <hrs@FreeBSD.org> To: doc@FreeBSD.org Subject: www/ cleanup patch Message-ID: <20060716.204810.57466384.hrs@allbsd.org>
next in thread | raw e-mail | index | archive | help
----Security_Multipart(Sun_Jul_16_20_48_10_2006_626)-- Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit 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. * 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. - 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. ----Security_Multipart(Sun_Jul_16_20_48_10_2006_626)-- Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (FreeBSD) iD8DBQBEuid6TyzT2CeTzy0RAgN9AKC7uWaGTrfntJ7+8j3zfxpblUFcYQCeIixK 7KS8DFfRwkded8Al1hfbXYo= =wtRg -----END PGP SIGNATURE----- ----Security_Multipart(Sun_Jul_16_20_48_10_2006_626)----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060716.204810.57466384.hrs>