Skip site navigation (1)Skip section navigation (2) 
Date:      Thu, 07 Aug 2003 22:12:04 +0900 (JST)
From:      Hiroki Sato <hrs@eos.ocn.ne.jp>
To:        simon@FreeBSD.org
Cc:        cvs-all@FreeBSD.org
Subject:   Re: cvs commit: doc/en_US.ISO8859-1/articles/5-roadmap article.sgml doc/en_US.ISO8859-1/articles/checkpoint article.sgml doc/en_US.ISO8859-1/articles/committers-guide article.sgml doc/en_US.ISO8859-1/articles/contributing article.sgml doc/en_US.ISO8859-1/articles/contributors article.sgml doc/en_US.ISO8859-1/share/sgml catalog trademarks.ent
Message-ID:  <20030807.221204.35461928.hrs@eos.ocn.ne.jp>
In-Reply-To: <20030807120540.GB388@FreeBSD.org>
References:  <20030807.091621.59658151.hrs@eos.ocn.ne.jp> <20030807113201.GA388@FreeBSD.org> <20030807120540.GB388@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help 
"Simon L. Nielsen" <simon@FreeBSD.org> wrote
  in <20030807120540.GB388@FreeBSD.org>:

simon> In share/sgml/catalog there is :
simon> 
simon> PUBLIC  "-//FreeBSD//ENTITIES DocBook Author Entities//EN"
simon>         "../../en_US.ISO8859-1/share/sgml/authors.ent"

 SGML catalog/entity resolution is performed on a "first match" basis.
 So this declaration is used if a localized SGML catalog does not declare
 "-//FreeBSD//ENTITIES DocBook Author Entities//EN".

simon> In en_US.ISO8859-1/share/sgml/catalog there is :
simon> 
simon> PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN"
simon> 	"mailing-lists.ent"

 All docs in en_US.ISO8859-1/ always honor this declaration.  This is
 because ${CATALOGS} in doc.docbook.mk is defined as follows:

 .for c in ${LANGUAGECATALOG} ${FREEBSDCATALOG} ${DSSSLCATALOG} ${ISO8879CATALOG}
  ${DOCBOOKCATALOG} ${JADECATALOG} ${EXTRA_CATALOGS} ${CATALOG_PORTS_SGML}
 .if exists(${c})
 CATALOGS+=      -c ${c}
 .endif
 .endfor

 and due to the first match rule.  The resolution order is:

  1) <langcode>/share/sgml/catalog
  2) share/sgml/catalog
  3) ${PREFIX}/share/sgml/docbook/dsssl/modular/catalog
  ....

 If we put the localized version of a file and the same declaration
 into <langcode>/share/sgml, the localized one has priority.
 This, however, can only be used to replace a file entirely.
 Now we have to replace a part of entities in a file.  To realize it, define
 localized entity set like ja_JP.eucJP/share/sgml/authors.ent.

 ja_JP.eucJP/share/sgml/authors.ent is not a true counterpart in
 en_US.ISO8859-1/.  The file includes Japanese committers' name only which
 is written in Japanese.  And, in ja_JP.eucJP/share/sgml/catalog 

 PUBLIC  "-//FreeBSD//ENTITIES DocBook Author Entities//JA"
         "authors.ent"

 is declared, and both of the English and the localized version

 <!ENTITY % ja-authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//JA">
 %ja-authors;
 <!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
 %authors;

 are used in books/handbook/book.sgml.  To do so, the entities in %ja-authors;
 partly override ones in %authors;.

 Consequently, I suggest the following:

 1) move trademarks.ent to share/sgml/.

 2) declare

    PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN"
            "trademarks.ent"

    in share/sgml/catalog.  At this point, all of the docs can use 
    the entities using

    <!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN">
    %trademarks;.

 3) for the localized docs, translators have to declare

    PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//XX"
            "trademarks.ent"

    in <langcode>/share/sgml/catalog and put the localized subset of
    trademarks.ent into in <langcode>/share/sgml/.  "XX" should be
    replaced the langcode like JA, FR, and so on.  And use

    <!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//XX">
    %xx-trademarks;.
    <!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN">
    %trademarks;.

    to override the entities in %trademarks; with ones in %xx-trademarks;.

    If the localized declaration does not exist, the English version is
    used naturally.


 Probably l10n.ent is another good example.  When we need to replace
 a file entirely, declare the same PI (Public Identifier) in the localized
 catalog, and when we need to replace a part of the entities, declare the
 localized PI in the localized catalog and take the both of them in the
 localized docs to override.

-- 
| Hiroki SATO  <hrs@eos.ocn.ne.jp> / <hrs@FreeBSD.org>

Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030807.221204.35461928.hrs>