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
Hiroki Sato
hrs at eos.ocn.ne.jp
Thu Aug 7 06:13:56 PDT 2003
"Simon L. Nielsen" <simon at FreeBSD.org> wrote
in <20030807120540.GB388 at 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 at eos.ocn.ne.jp> / <hrs at FreeBSD.org>
More information about the cvs-doc
mailing list