[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
developers/htdocs.xml: 1.16 -> 1.25
以下のページの更新をしました。ツッコミをお願いします。
developers/htdocs.xml: 1.16 -> 1.25
月曜日までに異議がなければ、 commit します。
原文の更新への追従のほか、
これまで未訳のままだった dotlist-files を訳しました。
以下、訳と原文の差分です。
--- developers/htdocs.xml.orig 2006-03-18 15:23:26.000000000 +0900
+++ developers/htdocs.xml 2006-03-18 15:23:26.000000000 +0900
@@ -1,18 +1,14 @@
<?xml version="1.0" encoding="ISO-2022-JP"?>
<!DOCTYPE webpage
- PUBLIC "-//Norman Walsh//DTD Website V2.2//EN"
- "http://docbook.sourceforge.net/release/website/2.2/website.dtd" [
-
-<!ENTITY % man-refs.ent SYSTEM "../../share/xml/man-refs.ent"> %man-refs.ent;
-
-]>
+ PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
+ "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
<webpage id="ja-htdocs">
<config param="desc" value="htdocsを編集する"/>
-<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.16 2005/01/22 18:44:55 jschauma Exp $"/>
+<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.25 2005/06/28 11:47:59 darcy Exp $"/>
<!-- Based on english version: -->
-<!-- NetBSD: htdocs.xml,v 1.16 2005/01/22 18:44:55 jschauma Exp -->
-<config param="rcsdate" value="$Date: 2005/01/22 18:44:55 $"/>
+<!-- NetBSD: htdocs.xml,v 1.25 2005/06/28 11:47:59 darcy Exp -->
+<config param="rcsdate" value="$Date: 2005/06/28 11:47:59 $"/>
<head>
<title>htdocsを編集する</title>
</head>
@@ -49,9 +45,10 @@
</listitem>
<listitem><pkg>meta-pkgs/netbsd-www</pkg> をインストールします。これにより、
web サイトの構築に必要な道具がインストールされます。最低限、
- <pkg>textproc/docbook-xsl</pkg> >= 1.67.0 が必要です (<pkg>meta-pkgs/netbsd-www</pkg> 1.2
- が依存していますが、これより前のバージョンではもっと古いバージョンの
- docbook-xsl も許容していました)。
+ <pkg>textproc/docbook-xsl</pkg> >= 1.68.1 および
+ <pkg>textproc/docbook-website</pkg> >= 2.5.0 が必要です (<pkg>meta-pkgs/netbsd-www</pkg> 1.3
+ が依存していますが、これより前のバージョンではもっと古いバージョンの
+ docbook-xsl も許容していました)。
</listitem>
<listitem>CVSROOTを指定通りに設定し、
<para><programlisting>cvs checkout htdocs</programlisting></para> を実行してください。
@@ -98,58 +95,10 @@
<sect3 id="dotlist-files">
<title>.listファイルとは何者か?</title>
<para>
- <emphasis role="bold">The <code>.list</code> files are
- obsolete!</emphasis><html:br/>
- Please see <ulink url="#dotxml-files">this section</ulink> for details.
- The paragraphs below still apply to the currently existing <code>.list</code>
- files.
-</para>
-<para>
- A <code>.list</code> file contains standard HTML with additional special
- tags to simplify formatting. It used to be processed by <code><ulink
- url="../list2html.pl">list2html.pl</ulink></code> into the desired .html
- file. Since the <code>.list</code> files are now obsolete, they should
- not be edited anymore. If they need to be changed, they should be <ulink
- url="#convert-to-xml">converted to XML</ulink>.
-</para>
-<para>
- There should be a Makefile in each directory which handles processing
- the .list files into .html, and will recurse into any subdirs
- containing Makefiles.
-</para>
-<para>
- Continuation lines are understood (useful for the special tags).
-</para>
-<para>
- If you do not have CVS access and wish to submit changes, you
- can check out htdocs via anonymous CVS (see the <ulink
- url="cvs-repos/cvs_intro.html">NetBSD CVS HOWTO</ulink>). The best
- approach is usually to:
- <orderedlist>
- <listitem>Checkout the <emphasis>htdocs</emphasis> module
- <para><programlisting>cvs checkout htdocs</programlisting></para>
- </listitem>
- <listitem>Edit the desired file. Most FAQ-style documents are
- generated from <code>.list</code> files, so it is best to check
- before editing.
- </listitem>
- <listitem>
- Run 'make' if you have edited .list or similar files.
- </listitem>
- <listitem><ulink url="#validate-html">Validate</ulink> the HTML.
- (Repeat these three steps as necessary).
- </listitem>
- <listitem>Submit a diff to <email>www@NetBSD.org</email>
- using <emphasis role="bold">cvs diff</emphasis>, eg.
- <para>
- <programlisting>cvs diff -u <emphasis>htdocs/path/to/file.list</emphasis></programlisting>
- </para>
- </listitem>
- </orderedlist>
-</para>
-<para>
- You should run <emphasis role="bold">make</emphasis> before committing.
- You will need <pkg>lang/perl5</pkg> installed.
+ <emphasis role="bold"><code>.list</code>
+ ファイルは過去の遺物です!</emphasis><html:br/>
+ 既存の <code>.list</code> ファイルはすべて XML に変換してください。
+ 詳細は<ulink url="#convert-to-xml">この節</ulink>をご覧ください。
</para>
</sect3>
@@ -172,6 +121,7 @@
<command>xsltproc</command> が独自に ID 属性を生成して、
<code>.html</code> ファイルを再生成する度に
ID 属性が更新されることがないようにするためです。
+ また、 <quote>&</quote> は <quote>&amp;</quote> に置きかえてください。
</para>
<para>
ある HTML タグを、等価な XML に変換する方法がわからない場合は、
@@ -190,6 +140,16 @@
ファイルに書き加えて web サイトを再生成することを忘れないでください。
詳細は<ulink url="#dotxml-files">この後の項目</ulink>をご覧ください。
</para>
+<!--
+XXX: put back when we do switch
+<para>
+ Finally, remember that as of 2005-02-05 file generated
+ <emphasis>from</emphasis> XML need no longer be added to CVS, as these
+ files are generated <ulink url="#webserver">on nbwww</ulink>. In fact,
+ these <quote>object files</quote> will likely be removed from CVS control
+ altogether.
+</para>
+-->
</sect3>
<sect3 id="dotxml-files">
@@ -198,22 +158,17 @@
.xml ファイルから .html ファイルを構築するためには、少なくとも
<pkg>textproc/libxslt</pkg> と <pkg>textproc/docbook-website</pkg>
をインストールしておく必要があります。これらは <pkg>meta-pkgs/netbsd-www</pkg> に含まれています。
- <pkg>meta-pkgs/netbsd-www</pkg> のバージョンが 1.2 であることを確認してください
- (1.2 は、最新の安定版の pkgsrc-2004Q4 枝で提供されています)。
+ <pkg>meta-pkgs/netbsd-www</pkg> のバージョンが 1.3 であることを確認してください。
</para>
<para>
- .html ファイルを生成するには、 htdocs/ に cd して
- <para><programlisting>make ./autolayout.xml</programlisting></para>
- を実行します。それから、対象のディレクトリーで <code><emphasis role="bold">make</emphasis></code>
- を実行します。
+ .html ファイルを生成するには、対象のディレクトリーで
+ <code><emphasis role="bold">make</emphasis></code> を実行するだけです。
+ .html ファイルに正しい "Generated from" が含まれるようにするため、
+ 必ず、 .xml ファイルを commit した後に .html ファイルを生成してください。
</para>
<para>
- <command>make</command> 実行時に
- <programlisting>
- Warning! layout.xml has changed. The whole website needs to be rebuilt.</programlisting>
- と表示された場合は、htdocs の最上層で <command>make</command> を実行する必要があります。
- <command>xsltproc</command> がメモリー不足で失敗した場合は、
- シェルのデータセグメントの ulimit を増やします。
+ <filename>layout.xml</filename> にファイルを追加した場合は、
+ htdocs の最上層で <command>make</command> を実行する必要があります。
</para>
</sect3>
@@ -276,8 +231,12 @@
セキュリティー上の理由から、この htdocs リポジトリーは、毎時間ごとに
www.NetBSD.org に (rsync を使って) コピーされ、
そのコピーからローカルにチェックアウトされています。
- チェックアウトされたツリーは "<code>/NetBSD-www</code>" にあります。
- このリポジトリーの更新とチェックアウトは、毎時 40 分ごろに行われます。
+ <!-- As of 2005-02-05, nbwww builds the
+ website from the CVS checkout in a staging directory, then copies any
+ modified files into the live website under
+ <quote><code>/NetBSD-www</code></quote>. -->
+ これをおこなうスクリプトは <filename>htutils/scripts/update.http</filename>
+ にあり、毎時 40 分ごろに実行されます。
htdocs をコミットすると、
それが公開されるまでに最大一時間かかることになります。
</para>
@@ -344,9 +303,8 @@
<sect4 id="before-anything">
<title>htdocsに変更を加える前に:</title>
<orderedlist>
- <listitem><ulink
- url="#dotlist-files">.list ファイル</ulink>用に <pkg>lang/perl5</pkg> がインストールされていることを確認します。<ulink
- url="#what-is-required">前の項目</ulink>もご覧ください。</listitem>
+ <listitem><pkg>meta-pkgs/netbsd-www</pkg> がインストールされていることを確認します。
+ <ulink url="#what-is-required">前の項目</ulink>もご覧ください。</listitem>
<listitem>CVSリポジトリーから<code>htdocs</code>をチェックアウトします。</listitem>
<listitem>htdocs ツリーのコピーがすでにある場合は、定期的に更新するように
してください。特に、ニュース項目を追加する際には、 gallery/events.*
@@ -417,8 +375,7 @@
<orderedlist>
<listitem>変更したファイルの<ulink url="#validate-html">HTML
をチェック</ulink>します。</listitem>
- <listitem>ファイルをチェックインします - <code>.list</code> ファイルを更新して一致する
- <code>.html</code> にし忘れないでください。 htdocs 最上層のディレクトリーで
+ <listitem>ファイルをチェックインします。 htdocs 最上層のディレクトリーで
'make commit' コマンドを実行すると、メインの index ページ、
Changes/index.* と翻訳されている各言語の index ページが、
デフォルトメッセージ "NEWS; regen" でコミットされます。
Index: developers/htdocs.xml
===================================================================
RCS file: /cvsroot/htdocs/developers/htdocs.xml,v
retrieving revision 1.16
retrieving revision 1.25
diff -u -r1.16 -r1.25
--- developers/htdocs.xml 22 Jan 2005 18:44:55 -0000 1.16
+++ developers/htdocs.xml 28 Jun 2005 11:47:59 -0000 1.25
@@ -1,16 +1,12 @@
<?xml version="1.0"?>
<!DOCTYPE webpage
- PUBLIC "-//Norman Walsh//DTD Website V2.2//EN"
- "http://docbook.sourceforge.net/release/website/2.2/website.dtd" [
-
-<!ENTITY % man-refs.ent SYSTEM "../share/xml/man-refs.ent"> %man-refs.ent;
-
-]>
+ PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
+ "http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
<webpage id="htdocs">
<config param="desc" value="Editing htdocs"/>
-<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.16 2005/01/22 18:44:55 jschauma Exp $"/>
-<config param="rcsdate" value="$Date: 2005/01/22 18:44:55 $"/>
+<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.25 2005/06/28 11:47:59 darcy Exp $"/>
+<config param="rcsdate" value="$Date: 2005/06/28 11:47:59 $"/>
<head>
<title>Editing htdocs</title>
</head>
@@ -45,9 +41,10 @@
</listitem>
<listitem>Install <pkg>meta-pkgs/netbsd-www</pkg>, which provides the tools
required to build the web site. Please make sure that you have at
- least <pkg>textproc/docbook-xsl</pkg> >= 1.67.0 (automatically
- requried by <pkg>meta-pkgs/netbsd-www</pkg> 1.2, but earlier versions
- also accepted earlier versions of docbook-xsl).
+ least <pkg>textproc/docbook-xsl</pkg> >= 1.68.1 and
+ <pkg>textproc/docbook-website</pkg> >= 2.5.0 (automatically
+ required by <pkg>meta-pkgs/netbsd-www</pkg> 1.3, but earlier
+ versions also accepted earlier versions of docbook-xsl).
</listitem>
<listitem>Set your CVSROOT as indicated and run
<para><programlisting>cvs checkout htdocs</programlisting></para>
@@ -94,56 +91,8 @@
<para>
<emphasis role="bold">The <code>.list</code> files are
obsolete!</emphasis><html:br/>
- Please see <ulink url="#dotxml-files">this section</ulink> for details.
- The paragraphs below still apply to the currently existing <code>.list</code>
- files.
-</para>
-<para>
- A <code>.list</code> file contains standard HTML with additional special
- tags to simplify formatting. It used to be processed by <code><ulink
- url="../list2html.pl">list2html.pl</ulink></code> into the desired .html
- file. Since the <code>.list</code> files are now obsolete, they should
- not be edited anymore. If they need to be changed, they should be <ulink
- url="#convert-to-xml">converted to XML</ulink>.
-</para>
-<para>
- There should be a Makefile in each directory which handles processing
- the .list files into .html, and will recurse into any subdirs
- containing Makefiles.
-</para>
-<para>
- Continuation lines are understood (useful for the special tags).
-</para>
-<para>
- If you do not have CVS access and wish to submit changes, you
- can check out htdocs via anonymous CVS (see the <ulink
- url="cvs-repos/cvs_intro.html">NetBSD CVS HOWTO</ulink>). The best
- approach is usually to:
- <orderedlist>
- <listitem>Checkout the <emphasis>htdocs</emphasis> module
- <para><programlisting>cvs checkout htdocs</programlisting></para>
- </listitem>
- <listitem>Edit the desired file. Most FAQ-style documents are
- generated from <code>.list</code> files, so it is best to check
- before editing.
- </listitem>
- <listitem>
- Run 'make' if you have edited .list or similar files.
- </listitem>
- <listitem><ulink url="#validate-html">Validate</ulink> the HTML.
- (Repeat these three steps as necessary).
- </listitem>
- <listitem>Submit a diff to <email>www@NetBSD.org</email>
- using <emphasis role="bold">cvs diff</emphasis>, eg.
- <para>
- <programlisting>cvs diff -u <emphasis>htdocs/path/to/file.list</emphasis></programlisting>
- </para>
- </listitem>
- </orderedlist>
-</para>
-<para>
- You should run <emphasis role="bold">make</emphasis> before committing.
- You will need <pkg>lang/perl5</pkg> installed.
+ You should convert any existing <code>.list</code> files to XML.
+ Please see <ulink url="#convert-to-xml">this section</ulink> for details.
</para>
</sect3>
@@ -166,7 +115,8 @@
as well as each <code><table></code> tag: this will prevent
<command>xsltproc</command> to generate an ID
itself, which would require an update of the resulting <code>.html</code>
- file after each regeneration.
+ file after each regeneration. Also remember to replace each
+ <quote>&</quote> with <quote>&amp;</quote>.
</para>
<para>
If you are unsure how to convert a given HTML tag to the XML equivalent,
@@ -186,6 +136,16 @@
<code>htdocs/layout.xml</code> file and regenerate the website. See
<ulink url="#dotxml-files">below</ulink> for details.
</para>
+<!--
+XXX: put back when we do switch
+<para>
+ Finally, remember that as of 2005-02-05 file generated
+ <emphasis>from</emphasis> XML need no longer be added to CVS, as these
+ files are generated <ulink url="#webserver">on nbwww</ulink>. In fact,
+ these <quote>object files</quote> will likely be removed from CVS control
+ altogether.
+</para>
+-->
</sect3>
<sect3 id="dotxml-files">
@@ -194,22 +154,18 @@
In order to build .html files from .xml files, you will need at
least <pkg>textproc/libxslt</pkg> and <pkg>textproc/docbook-website</pkg>
installed. These are installed as part of <pkg>meta-pkgs/netbsd-www</pkg>.
- Please make sure that you have <pkg>meta-pkgs/netbsd-www</pkg> version 1.2
- (which is in the latest stable branch, pkgsrc-2004Q4).
+ Please make sure that you have <pkg>meta-pkgs/netbsd-www</pkg> version
+ 1.3.
</para>
<para>
- To regenerate, cd to htdocs/ and run
- <para><programlisting>make ./autolayout.xml</programlisting></para>
- Then run <code><emphasis role="bold">make</emphasis></code> in the target
- directory.
+ To regenerate, just run
+ <code><emphasis role="bold">make</emphasis></code> in the target directory.
+ You must do this after committing the .xml file so that the .html file
+ will include the proper "Generated from" statement.
</para>
<para>
- If <command>make</command> complains
- <programlisting>
- Warning! layout.xml has changed. The whole website needs to be rebuilt.</programlisting>
+ If you added a new file to <filename>layout.xml</filename>,
then you do need to run <command>make</command> in the htdocs top level.
- If <command>xsltproc</command> fails and complains about running out of
- memory, then you should increase the data segment ulimit of your shell.
</para>
</sect3>
@@ -270,10 +226,13 @@
<para>
The NetBSD webpages are stored in CVS in the "htdocs" repository.
For security reasons, the htdocs repository is copied (via rsync)
- to www.NetBSD.org each hour, and the a local checkout is done from
- that copy of the repository. The checked out tree can be found in
- "<code>/NetBSD-www</code>". The repository is updated and checked out
- every hour, about 40 minutes after the full hour (*:40). If you
+ to www.NetBSD.org each hour, and then a local checkout is done from
+ that copy of the repository. <!-- As of 2005-02-05, nbwww builds the
+ website from the CVS checkout in a staging directory, then copies any
+ modified files into the live website under
+ <quote><code>/NetBSD-www</code></quote>. -->The script performing this
+ functionality is <filename>htutils/scripts/update.http</filename> and it
+ is run about 40 minutes after the full hour (*:40). If you
make a commit to htdocs, it will take up to an hour before the
changes show up.
</para>
@@ -340,9 +299,8 @@
<sect4 id="before-anything">
<title>Before you do anything with htdocs:</title>
<orderedlist>
- <listitem>Ensure you have <pkg>lang/perl5</pkg> installed for the <ulink
- url="#dotlist-files">.list files</ulink>. Also, see <ulink
- url="#what-is-required">above</ulink>.</listitem>
+ <listitem>Ensure you have <pkg>meta-pkgs/netbsd-www</pkg> installed.
+ Also, see <ulink url="#what-is-required">above</ulink>.</listitem>
<listitem>Check out <code>htdocs</code> from the CVS repository.</listitem>
<listitem>If you already have a copy of htdocs in your tree, make sure you
update it regularly. In particular, when adding news items, make sure that
@@ -413,8 +371,7 @@
<orderedlist>
<listitem>You may want to <ulink url="#validate-html">validate the
HTML</ulink> in your modified files.</listitem>
- <listitem>Check in the files - do not forget any <code>.list</code> files will
- update the matching <code>.html</code>. The command 'make commit', when
+ <listitem>Check in the files. The command 'make commit', when
issued from the htdocs toplevel directory, will commit the main
index-page, Changes/index.* and all the translations index pages with
a default message of "NEWS; regen". If you would like to add a more