www/ cleanup patch

[Hiroki Sato]

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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20060716/a7fd0cc6/attachment.sig>