HEADS UP: www cleanup mega-patch will be committed soon (Re: www/ cleanup patch)

[Hiroki Sato]

Hi all,

Hiroki Sato <hrs at freebsd.org> wrote
  in <20060716.204810.57466384.hrs at 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.

-------------- 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/20060819/6b7311e5/attachment.sig>