Creating an Admin Handbook
Hiroki Sato
hrs at FreeBSD.org
Sat Jul 24 09:39:33 UTC 2004
Hi,
Hiroki Sato <hrs at freebsd.org> wrote
in <20040724.021023.78760665.hrs at eos.ocn.ne.jp>:
hrs> I will work on the issue this weekend, so could you please
hrs> wait? Thanks.
Patches are attached. In doc-relative-urls.diff,
articles/checkpoint is used for an example.
It defines &doc.langcode; in l10n.ent, and it is used
for series of the entites &url.books.*; and &url.articles.*;
defined in urls.ent. As a result, &url.books.handbook; always
points the localized handbook. Since the translation teams often
use a link to the original document, &url.books.*.en; are also defined.
Comments? What we need to do are:
1) Define doc.langcode in <langcode>/share/sgml/l10n.ent.
When it is not defined, en_US.ISO8859-1 is used by default.
(in the case of ja_JP.eucJP, for example, the changes are
something like doc-relative-urls-ja.diff).
2) Add URL_RELPREFIX in the Makefile. When it is not defined,
absolute URLs are always used.
3) Add l10n.ent and urls.ent in the document preamble.
4) Use &url.*; to point documents in doc/.
--
| Hiroki SATO
-------------- next part --------------
Index: en_US.ISO8859-1/articles/checkpoint/Makefile
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/checkpoint/Makefile,v
retrieving revision 1.6
diff -d -u -I\$FreeBSD:.*\$ -I\$NetBSD:.*\$ -I\$OpenBSD:.*\$ -I\$DragonFly:.*\$ -I\$Id:.*\$ -I\$hrs:.*\$ -r1.6 Makefile
--- en_US.ISO8859-1/articles/checkpoint/Makefile 6 Apr 2004 16:10:02 -0000 1.6
+++ en_US.ISO8859-1/articles/checkpoint/Makefile 24 Jul 2004 08:58:14 -0000
@@ -13,5 +13,6 @@
SRCS= article.sgml
IMAGES_EN= networks.pic
+URL_RELPREFIX?= ../../..
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"
Index: en_US.ISO8859-1/articles/checkpoint/article.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/checkpoint/article.sgml,v
retrieving revision 1.20
diff -d -u -I\$FreeBSD:.*\$ -I\$NetBSD:.*\$ -I\$OpenBSD:.*\$ -I\$DragonFly:.*\$ -I\$Id:.*\$ -I\$hrs:.*\$ -r1.20 article.sgml
--- en_US.ISO8859-1/articles/checkpoint/article.sgml 23 Jul 2004 10:43:21 -0000 1.20
+++ en_US.ISO8859-1/articles/checkpoint/article.sgml 24 Jul 2004 09:08:17 -0000
@@ -35,6 +35,10 @@
<!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN">
%trademarks;
+<!ENTITY % l10n.ent PUBLIC "-//FreeBSD//ENTITIES DocBook Language Specific Entities//EN">
+%l10n.ent;
+<!ENTITY % urls.ent PUBLIC "-//FreeBSD//ENTITIES DocBook URL Entities//EN">
+%urls.ent;
]>
<article>
@@ -125,7 +129,7 @@
options IPSEC_DEBUG</programlisting>
<para>For instructions on building a custom kernel, refer to the
- <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html">FreeBSD
+ <ulink url="&url.books.handbook;/kernelconfig.html">FreeBSD
handbook</ulink>. Please note that <acronym>IP</acronym>
protocol 50 (<acronym>ESP</acronym>) and <acronym>UDP</acronym>
port <literal>500</literal> must be open between the <trademark class='registered'>Firewall-1</trademark>
@@ -421,7 +425,7 @@
<itemizedlist>
<listitem>
<para>The FreeBSD Handbook: VPN over IPsec.
- <ulink url="http://www.FreeBSD.org/handbook/ipsec.html"></ulink></para>
+ <ulink url="&url.books.handbook;/ipsec.html"></ulink></para>
</listitem>
<listitem>
Index: en_US.ISO8859-1/share/sgml/l10n.ent
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/share/sgml/l10n.ent,v
retrieving revision 1.1
diff -d -u -I\$FreeBSD:.*\$ -I\$NetBSD:.*\$ -I\$OpenBSD:.*\$ -I\$DragonFly:.*\$ -I\$Id:.*\$ -I\$hrs:.*\$ -r1.1 l10n.ent
--- en_US.ISO8859-1/share/sgml/l10n.ent 19 Apr 2003 11:39:28 -0000 1.1
+++ en_US.ISO8859-1/share/sgml/l10n.ent 24 Jul 2004 09:09:44 -0000
@@ -7,3 +7,6 @@
<!-- docformat navi -->
<!ENTITY docnavi.single-html "Single HTML">
<!ENTITY docnavi.split-html "Split HTML">
+
+<!ENTITY doc.langcode.en "en_US.ISO8859-1">
+<!ENTITY doc.langcode "&doc.langcode.en;">
Index: share/sgml/urls.ent
===================================================================
RCS file: /home/ncvs/doc/share/sgml/urls.ent,v
retrieving revision 1.4
diff -d -u -I\$FreeBSD:.*\$ -I\$NetBSD:.*\$ -I\$OpenBSD:.*\$ -I\$DragonFly:.*\$ -I\$Id:.*\$ -I\$hrs:.*\$ -r1.4 urls.ent
--- share/sgml/urls.ent 7 Jul 2004 11:23:16 -0000 1.4
+++ share/sgml/urls.ent 24 Jul 2004 09:03:40 -0000
@@ -37,16 +37,119 @@
<!ENTITY url.relprefix "../../../../../../../..">
]]>
-<!-- Do not edit: end here -->
-
<![ %freebsd.urls.absolute; [
-<!-- put absolute urls here -->
-
-<!ENTITY url.main "http://www.FreeBSD.org">
<!ENTITY url.base "http://www.FreeBSD.org">
]]>
+<!ENTITY url.base "&url.relprefix;">
-<!-- put relative urls here -->
+<!ENTITY doc.langcode.en "en_US.ISO8859-1">
+<!ENTITY doc.langcode.default "en_US.ISO8859-1">
+<!ENTITY doc.langcode "&doc.langcode.default;">
-<!ENTITY url.main "&url.relprefix;">
-<!ENTITY url.base "&url.relprefix;">
+<!ENTITY url.doc.base "&url.base;/doc">
+<!ENTITY url.doc.langbase "&url.doc.base;/&doc.langcode;">
+<!ENTITY url.doc.langbase.en "&url.doc.base;/&doc.langcode.en;">
+
+<!-- Do not edit: end here -->
+
+<!-- for doc//langcode//books -->
+
+<!ENTITY url.books.arch-handbook "&url.doc.langbase;/books/arch-handbook">
+<!ENTITY url.books.arch-handbook.en "&url.doc.langbase.en;/books/arch-handbook">
+<!ENTITY url.books.bibliography "&url.doc.langbase;/books/bibliography">
+<!ENTITY url.books.bibliography.en "&url.doc.langbase.en;/books/bibliography">
+<!ENTITY url.books.corp-net-guide "&url.doc.langbase;/books/corp-net-guide">
+<!ENTITY url.books.corp-net-guide.en "&url.doc.langbase.en;/books/corp-net-guide">
+<!ENTITY url.books.developers-handbook "&url.doc.langbase;/books/developers-handbook">
+<!ENTITY url.books.developers-handbook.en "&url.doc.langbase.en;/books/developers-handbook">
+<!ENTITY url.books.faq "&url.doc.langbase;/books/faq">
+<!ENTITY url.books.faq.en "&url.doc.langbase.en;/books/faq">
+<!ENTITY url.books.fdp-primer "&url.doc.langbase;/books/fdp-primer">
+<!ENTITY url.books.fdp-primer.en "&url.doc.langbase.en;/books/fdp-primer">
+<!ENTITY url.books.handbook "&url.doc.langbase;/books/handbook">
+<!ENTITY url.books.handbook.en "&url.doc.langbase.en;/books/handbook">
+<!ENTITY url.books.porters-handbook "&url.doc.langbase;/books/porters-handbook">
+<!ENTITY url.books.porters-handbook.en "&url.doc.langbase.en;/books/porters-handbook">
+
+<!-- for doc//langcode//articles -->
+
+<!ENTITY url.articles.5-roadmap "&url.doc.langbase;/articles/5-roadmap">
+<!ENTITY url.articles.5-roadmap.en "&url.doc.langbase.en;/articles/5-roadmap">
+<!ENTITY url.articles.checkpoint "&url.doc.langbase;/articles/checkpoint">
+<!ENTITY url.articles.checkpoint.en "&url.doc.langbase.en;/articles/checkpoint">
+<!ENTITY url.articles.committers-guide "&url.doc.langbase;/articles/committers-guide">
+<!ENTITY url.articles.committers-guide.en "&url.doc.langbase.en;/articles/committers-guide">
+<!ENTITY url.articles.console-server "&url.doc.langbase;/articles/console-server">
+<!ENTITY url.articles.console-server.en "&url.doc.langbase.en;/articles/console-server">
+<!ENTITY url.articles.contributing "&url.doc.langbase;/articles/contributing">
+<!ENTITY url.articles.contributing.en "&url.doc.langbase.en;/articles/contributing">
+<!ENTITY url.articles.contributors "&url.doc.langbase;/articles/contributors">
+<!ENTITY url.articles.contributors.en "&url.doc.langbase.en;/articles/contributors">
+<!ENTITY url.articles.cvs-freebsd "&url.doc.langbase;/articles/cvs-freebsd">
+<!ENTITY url.articles.cvs-freebsd.en "&url.doc.langbase.en;/articles/cvs-freebsd">
+<!ENTITY url.articles.cvsup-advanced "&url.doc.langbase;/articles/cvsup-advanced">
+<!ENTITY url.articles.cvsup-advanced.en "&url.doc.langbase.en;/articles/cvsup-advanced">
+<!ENTITY url.articles.dialup-firewall "&url.doc.langbase;/articles/dialup-firewall">
+<!ENTITY url.articles.dialup-firewall.en "&url.doc.langbase.en;/articles/dialup-firewall">
+<!ENTITY url.articles.diskless-x "&url.doc.langbase;/articles/diskless-x">
+<!ENTITY url.articles.diskless-x.en "&url.doc.langbase.en;/articles/diskless-x">
+<!ENTITY url.articles.euro "&url.doc.langbase;/articles/euro">
+<!ENTITY url.articles.euro.en "&url.doc.langbase.en;/articles/euro">
+<!ENTITY url.articles.explaining-bsd "&url.doc.langbase;/articles/explaining-bsd">
+<!ENTITY url.articles.explaining-bsd.en "&url.doc.langbase.en;/articles/explaining-bsd">
+<!ENTITY url.articles.fbsd-from-scratch "&url.doc.langbase;/articles/fbsd-from-scratch">
+<!ENTITY url.articles.fbsd-from-scratch.en "&url.doc.langbase.en;/articles/fbsd-from-scratch">
+<!ENTITY url.articles.filtering-bridges "&url.doc.langbase;/articles/filtering-bridges">
+<!ENTITY url.articles.filtering-bridges.en "&url.doc.langbase.en;/articles/filtering-bridges">
+<!ENTITY url.articles.fonts "&url.doc.langbase;/articles/fonts">
+<!ENTITY url.articles.fonts.en "&url.doc.langbase.en;/articles/fonts">
+<!ENTITY url.articles.formatting-media "&url.doc.langbase;/articles/formatting-media">
+<!ENTITY url.articles.formatting-media.en "&url.doc.langbase.en;/articles/formatting-media">
+<!ENTITY url.articles.freebsd-questions "&url.doc.langbase;/articles/freebsd-questions">
+<!ENTITY url.articles.freebsd-questions.en "&url.doc.langbase.en;/articles/freebsd-questions">
+<!ENTITY url.articles.hats "&url.doc.langbase;/articles/hats">
+<!ENTITY url.articles.hats.en "&url.doc.langbase.en;/articles/hats">
+<!ENTITY url.articles.hubs "&url.doc.langbase;/articles/hubs">
+<!ENTITY url.articles.hubs.en "&url.doc.langbase.en;/articles/hubs">
+<!ENTITY url.articles.ipsec-must "&url.doc.langbase;/articles/ipsec-must">
+<!ENTITY url.articles.ipsec-must.en "&url.doc.langbase.en;/articles/ipsec-must">
+<!ENTITY url.articles.java-tomcat "&url.doc.langbase;/articles/java-tomcat">
+<!ENTITY url.articles.java-tomcat.en "&url.doc.langbase.en;/articles/java-tomcat">
+<!ENTITY url.articles.laptop "&url.doc.langbase;/articles/laptop">
+<!ENTITY url.articles.laptop.en "&url.doc.langbase.en;/articles/laptop">
+<!ENTITY url.articles.mailing-list-faq "&url.doc.langbase;/articles/mailing-list-faq">
+<!ENTITY url.articles.mailing-list-faq.en "&url.doc.langbase.en;/articles/mailing-list-faq">
+<!ENTITY url.articles.mh "&url.doc.langbase;/articles/mh">
+<!ENTITY url.articles.mh.en "&url.doc.langbase.en;/articles/mh">
+<!ENTITY url.articles.multi-os "&url.doc.langbase;/articles/multi-os">
+<!ENTITY url.articles.multi-os.en "&url.doc.langbase.en;/articles/multi-os">
+<!ENTITY url.articles.new-users "&url.doc.langbase;/articles/new-users">
+<!ENTITY url.articles.new-users.en "&url.doc.langbase.en;/articles/new-users">
+<!ENTITY url.articles.pam "&url.doc.langbase;/articles/pam">
+<!ENTITY url.articles.pam.en "&url.doc.langbase.en;/articles/pam">
+<!ENTITY url.articles.portbuild "&url.doc.langbase;/articles/portbuild">
+<!ENTITY url.articles.portbuild.en "&url.doc.langbase.en;/articles/portbuild">
+<!ENTITY url.articles.pr-guidelines "&url.doc.langbase;/articles/pr-guidelines">
+<!ENTITY url.articles.pr-guidelines.en "&url.doc.langbase.en;/articles/pr-guidelines">
+<!ENTITY url.articles.problem-reports "&url.doc.langbase;/articles/problem-reports">
+<!ENTITY url.articles.problem-reports.en "&url.doc.langbase.en;/articles/problem-reports">
+<!ENTITY url.articles.pxe "&url.doc.langbase;/articles/pxe">
+<!ENTITY url.articles.pxe.en "&url.doc.langbase.en;/articles/pxe">
+<!ENTITY url.articles.relaydelay "&url.doc.langbase;/articles/relaydelay">
+<!ENTITY url.articles.relaydelay.en "&url.doc.langbase.en;/articles/relaydelay">
+<!ENTITY url.articles.releng "&url.doc.langbase;/articles/releng">
+<!ENTITY url.articles.releng.en "&url.doc.langbase.en;/articles/releng">
+<!ENTITY url.articles.releng-packages "&url.doc.langbase;/articles/releng-packages">
+<!ENTITY url.articles.releng-packages.en "&url.doc.langbase.en;/articles/releng-packages">
+<!ENTITY url.articles.serial-uart "&url.doc.langbase;/articles/serial-uart">
+<!ENTITY url.articles.serial-uart.en "&url.doc.langbase.en;/articles/serial-uart">
+<!ENTITY url.articles.solid-state "&url.doc.langbase;/articles/solid-state">
+<!ENTITY url.articles.solid-state.en "&url.doc.langbase.en;/articles/solid-state">
+<!ENTITY url.articles.storage-devices "&url.doc.langbase;/articles/storage-devices">
+<!ENTITY url.articles.storage-devices.en "&url.doc.langbase.en;/articles/storage-devices">
+<!ENTITY url.articles.vinum "&url.doc.langbase;/articles/vinum">
+<!ENTITY url.articles.vinum.en "&url.doc.langbase.en;/articles/vinum">
+<!ENTITY url.articles.vm-design "&url.doc.langbase;/articles/vm-design">
+<!ENTITY url.articles.vm-design.en "&url.doc.langbase.en;/articles/vm-design">
+<!ENTITY url.articles.zip-drive "&url.doc.langbase;/articles/zip-drive">
+<!ENTITY url.articles.zip-drive.en "&url.doc.langbase.en;/articles/zip-drive">
-------------- next part --------------
Index: ja_JP.eucJP/share/sgml/l10n.ent
===================================================================
RCS file: /home/ncvs/doc/ja_JP.eucJP/share/sgml/l10n.ent,v
retrieving revision 1.1
diff -d -u -I\$FreeBSD:.*\$ -I\$NetBSD:.*\$ -I\$OpenBSD:.*\$ -I\$DragonFly:.*\$ -I\$Id:.*\$ -I\$hrs:.*\$ -r1.1 l10n.ent
--- ja_JP.eucJP/share/sgml/l10n.ent 19 Apr 2003 11:39:30 -0000 1.1
+++ ja_JP.eucJP/share/sgml/l10n.ent 24 Jul 2004 08:52:57 -0000
@@ -7,3 +7,6 @@
<!-- docformat navi -->
<!ENTITY docnavi.single-html "???">
<!ENTITY docnavi.split-html "???">
+
+<!ENTITY doc.langcode.ja "ja_JP.eucJP">
+<!ENTITY doc.langcode "&doc.langcode.ja;">
-------------- 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/20040724/6645f792/attachment.sig>
More information about the freebsd-doc
mailing list