www/ cleanup patch

[Gábor Kövesdán]

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