[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
developers/htdocs.xml: 1.1 -> 1.9
以下のページの更新をしました。ツッコミをお願いします。
developers/htdocs.xml: 1.1 -> 1.9
木曜日までに異議がなければ、 commit します。
以下、訳と原文の差分です。
--- developers/htdocs.xml.orig Wed Feb 15 22:25:33 2006
+++ developers/htdocs.xml Wed Feb 15 22:25:33 2006
@@ -9,10 +9,10 @@
<webpage id="ja-htdocs">
<config param="desc" value="htdocsを編集する"/>
-<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.1 2004/11/15 23:15:53 jschauma Exp $"/>
+<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.9 2004/11/27 23:00:53 jschauma Exp $"/>
<!-- Based on english version: -->
-<!-- NetBSD: htdocs.xml,v 1.1 2004/11/15 23:15:53 jschauma Exp -->
-<config param="rcsdate" value="$Date: 2004/11/15 23:15:53 $"/>
+<!-- NetBSD: htdocs.xml,v 1.9 2004/11/27 23:00:53 jschauma Exp -->
+<config param="rcsdate" value="$Date: 2004/11/27 23:00:53 $"/>
<head>
<title>htdocsを編集する</title>
</head>
@@ -111,7 +111,7 @@
</para>
</sect3>
-<sect3 id="netbsd-org">
+<sect3 id="NetBSD-org">
<title>NetBSD.org の表記法</title>
<para>
リンク、 mailto その他の参照においては必ず NetBSD.org と書くようにし、
@@ -132,7 +132,7 @@
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 no obsolete, they should not be
+ 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>
@@ -178,10 +178,35 @@
XML 以外のファイルを編集する必要があるときは、編集と同時に XML に変換することになっています。
<code>htutils/scripts/list2xml</code> スクリプトは、通常の <code>.html</code>
ファイルの変換のほか、旧来の <code>.list</code> の変換にも役立つでしょう。
+ ただし、このスクリプトはタグの単純な置換をいくつかするだけであり、
+ 実行後に多くの手作業が必要ですので、どうぞご注意ください。
+ 特に、すべてのタグを適切な順序で閉じることが必要です。
+</para>
+<para>
+ <code>.xml</code> ファイルを生成あるいは変換した際には、各
+ <code><table></code> タグや <code><sect[1-4]></code> タグに
+ <quote>id</quote> 属性をつけたことを確認してください。これは、
+ <command>xsltproc</command> が独自に ID 属性を生成して、
+ <code>.html</code> ファイルを再生成する度に
+ ID 属性が更新されることがないようにするためです。
+</para>
+<para>
+ ある HTML タグを、等価な XML に変換する方法がわからない場合は、
+ システムにインストールされている <pkg>textproc/docbook-website</pkg>
+ のなかに便利な例があるかもしれません。そしてもちろん、
+ www@ メーリングリストに遠慮なく助けを求めていただいて結構です。
+</para>
+<para>
+ 目次を自動生成する場合は、 Makefile で目次の深さを (たとえば)
+ <code>TOC_LEVEL=3</code> のように指定する必要があります。
+ 目次に含めたくない節がある場合は、その節に
+ <code>role=<quote><emphasis>NotInToc</emphasis></quote></code> 属性をつけることができます。
+ <programlisting><sect2 id="not-in-toc" role="NotInToc"></programlisting>
</para>
<para>
ファイルを XML に変換した後は、そのファイルを <code>htdocs/layout.xml</code>
ファイルに書き加えて web サイトを再生成することを忘れないでください。
+ 詳細は<ulink url="#dotxml-files">この後の項目</ulink>をご覧ください。
</para>
</sect3>
@@ -294,21 +319,21 @@
<sect3 id="adding-news-items">
<title>ニュースの項目を追加する</title>
<para>
-ほとんどのニュース項目は<ulink url="../Changes/">htdocs/Changes/index.list</ulink>にあります
-(<ulink url="#dotlist-files">.list ファイル</ulink>に関する記述をごらんください) 。
+ほとんどのニュース項目は<ulink url="../Changes/">htdocs/Changes/index.xml</ulink>にあります
+(<ulink url="#dotxml-files">.xml ファイル</ulink>に関する記述をごらんください) 。
特定のポートに影響する変更はhtdocs/Port/*/にあるニュースの章からも
リンクをはってください。
</para>
<para>
重要なコードのニュース項目は
-<currentsrc>doc/CHANGES</currentsrc>
+<currentsrc>src/doc/CHANGES</currentsrc>
ファイルにも記述すべきです。
</para>
<para>せっかちな人向けのお手軽 ``howto'' (ただし、詳細な説明も読んでください):
<itemizedlist>
<listitem>cd htdocs/Changes</listitem>
<listitem>make update</listitem>
-<listitem>${EDITOR} index.list</listitem>
+<listitem>${EDITOR} index.xml</listitem>
<listitem>make</listitem>
<listitem>make MSG="I added important NEWS!" commit</listitem>
</itemizedlist>
@@ -317,36 +342,44 @@
<sect4 id="before-anything">
<title>htdocsに変更を加える前に:</title>
<orderedlist>
-<listitem><ulink url="#dotlist-files">.list ファイル</ulink>用にperlが
-インストールされていることを確認します。</listitem>
+<listitem><ulink url="#dotlist-files">.list ファイル</ulink>用に <pkg>lang/perl5</pkg> が
+ インストールされていることを確認します。<ulink url="#what-is-required">前の項目</ulink>もご覧ください。</listitem>
<listitem>CVSリポジトリーから<code>htdocs</code>をチェックアウトします。</listitem>
<listitem>htdocs ツリーのコピーがすでにある場合は、定期的に更新するように
してください。特に、ニュース項目を追加する際には、 gallery/events.*
も最新の状態になっていなければなりません。このファイルから今後のイベントを
-抜き出して利用しているからです。</listitem>
+抜き出して利用しているからです。以下のようにすれば一番よいでしょう。
+<programlisting>
+ $ cd htdocs
+ $ make update</programlisting>
+</listitem>
</orderedlist>
</sect4>
<sect4 id="change-entry">
<title>変更項目を付け加えるには:</title>
<orderedlist>
-<listitem>htdocs/Changes/index.listを編集し、<DATE>で始まる最初の行を
- 探します。</listitem>
-<listitem>以下の形式で新しい行を追加します
- <para><programlisting><DATE><emphasis>tag</emphasis> <emphasis>date</emphasis> - <emphasis>title</emphasis></programlisting></para>
- それぞれの項目は以下のように書きます
- <itemizedlist>
- <listitem><emphasis>タグ</emphasis> - 小文字/数字/ハイフンを識別します。例: 'new-xx-driver'</listitem>
- <listitem><emphasis>日付</emphasis> - DAY MONTH YEARの形式です。例: '23 Jan 1999'</listitem>
- <listitem><emphasis>タイトル</emphasis> - エントリータイトル用の自由形式のテキストです -
- 行末をエスケープするのに\を使えます。</listitem>
- </itemizedlist>
+<listitem>htdocs/Changes/index.xml を編集します</listitem>
+<listitem>目次に以下のような形式の行を追加します
+<programlisting>
+ <listitem><ulink url="#link-name">XX Mon XXX - FREEFORM TITLE</ulink></listitem></programlisting>
</listitem>
-<listitem>項目の本体を追加します。マニュアルページ (例: &man.ls.1;) とemailアドレス
- (例: <user@domain>) は自動的に展開されます。
- 自由にHTMLタグを使えますが、必須ではありません。</listitem>
+<listitem>目次より後の、適切な節に、以下のような形式で項目の本体を追加します
+ <programlisting>
+ <sect3 id="link-name>
+ <title>XX Mon XXX - 自由形式のタイトル (<ulink url="#monXXXX">top</ulink>)</title>
+ <para>
+ 項目の本文をここに書きます。マニュアルページは <quote>&man.command.X;</quote> として、
+ email アドレスは <email>full@address</email> として参照できます。
+ <para>
+ </sect3></programlisting>
+ </listitem>
<listitem>'<code>make</code>' を実行します。</listitem>
</orderedlist>
+<para>
+(www チームでは、目次の生成を自動化して項目追加が簡単にできるようにするため、
+作業中です。)
+</para>
</sect4>
<sect4 id="adding-links">
@@ -416,7 +449,7 @@
<para>
<programlisting>
cd .../htdocs/gallery
-$EDITOR events.list
+$EDITOR events.xml
make events</programlisting>
</para>
Index: developers/htdocs.xml
===================================================================
RCS file: /cvsroot/htdocs/developers/htdocs.xml,v
retrieving revision 1.1
retrieving revision 1.9
diff -u -r1.1 -r1.9
--- developers/htdocs.xml 15 Nov 2004 23:15:53 -0000 1.1
+++ developers/htdocs.xml 27 Nov 2004 23:00:53 -0000 1.9
@@ -9,8 +9,8 @@
<webpage id="htdocs">
<config param="desc" value="Editing htdocs"/>
-<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.1 2004/11/15 23:15:53 jschauma Exp $"/>
-<config param="rcsdate" value="$Date: 2004/11/15 23:15:53 $"/>
+<config param="cvstag" value="$NetBSD: htdocs.xml,v 1.9 2004/11/27 23:00:53 jschauma Exp $"/>
+<config param="rcsdate" value="$Date: 2004/11/27 23:00:53 $"/>
<head>
<title>Editing htdocs</title>
</head>
@@ -105,7 +105,7 @@
</para>
</sect3>
-<sect3 id="netbsd-org">
+<sect3 id="NetBSD-org">
<title>NetBSD.org naming scheme</title>
<para>
Make sure you use NetBSD.org and not any other scheme (Netbsd.org,
@@ -126,7 +126,7 @@
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 no obsolete, they should not be
+ 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>
@@ -172,11 +172,37 @@
file that needs to be edited shall be converted to XML at the same time.
You may find the script <code>htutils/scripts/list2xml</code> helpful to
initiate the conversion of the old <code>.list</code> as well as plain
- <code>.html</code> files.
+ <code>.html</code> files. Please note, however, that this script only
+ does a few simple replacements of tags, and you will need to do a lot by
+ hand after running it. In particular, you need to make sure that all
+ tags are closed in the proper order.
+</para>
+<para>
+ When creating or converting <code>.xml</code> files, please make sure to
+ add a <quote>id</quote> attribute to each <code><sect[1-4]></code>
+ 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.
+</para>
+<para>
+ If you are unsure how to convert a given HTML tag to the XML equivalent,
+ you may find some useful examples installed as part of the
+ <pkg>textproc/docbook-website</pkg> on your system. And of course you can
+ feel free to ask on the www@ list for help.
+</para>
+<para>
+ If you want an autogenerated TOC, you will need to set the depth of the
+ TOC you would like by specifing <code>TOC_LEVEL=3</code> (for example)
+ in the Makefile. If you wish to exclude sections from the TOC, you can
+ give them a <code>role=<quote><emphasis>NotInToc</emphasis></quote></code>
+ attribute:
+ <programlisting><sect2 id="not-in-toc" role="NotInToc"></programlisting>
</para>
<para>
After converting a file to XML, remember to add it to the
- <code>htdocs/layout.xml</code> file and regenerate the website.
+ <code>htdocs/layout.xml</code> file and regenerate the website. See
+ <ulink url="#dotxml-files">below</ulink> for details.
</para>
</sect3>
@@ -290,20 +316,20 @@
<title>Adding News Items</title>
<para>
Most news items go into <ulink
-url="../Changes/">htdocs/Changes/index.list</ulink> (see note on
-<ulink url="#dotlist-files">.list files</ulink>). Changes affecting a
+url="../Changes/">htdocs/Changes/index.xml</ulink> (see note on
+<ulink url="#dotxml-files">.xml files</ulink>). Changes affecting a
specific port should also be linked to from their htdocs/Port/*/ news section.
</para>
<para>
Important code news items should also be noted in the text
-<currentsrc>doc/CHANGES</currentsrc>
+<currentsrc>src/doc/CHANGES</currentsrc>
file.
</para>
<para>Quick ``howto'' for the impatient (but please do read on for details):
<itemizedlist>
<listitem>cd htdocs/Changes</listitem>
<listitem>make update</listitem>
-<listitem>${EDITOR} index.list</listitem>
+<listitem>${EDITOR} index.xml</listitem>
<listitem>make</listitem>
<listitem>make MSG="I added important NEWS!" commit</listitem>
</itemizedlist>
@@ -312,36 +338,45 @@
<sect4 id="before-anything">
<title>Before you do anything with htdocs:</title>
<orderedlist>
-<listitem>Ensure you have perl installed for the <ulink url="#dotlist-files">.list
- files</ulink>.</listitem>
+<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>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
gallery/events.* is up to date as well, as the events are pulled in from
-there!</listitem>
+there! This is best done by running
+<programlisting>
+ $ cd htdocs
+ $ make update</programlisting>
+</listitem>
</orderedlist>
</sect4>
<sect4 id="change-entry">
<title>To add a change entry:</title>
<orderedlist>
-<listitem>Edit htdocs/Changes/index.list and search for the first line
- starting <DATE>.</listitem>
-<listitem>Insert a new line of the form
- <para><programlisting><DATE><emphasis>tag</emphasis> <emphasis>date</emphasis> - <emphasis>title</emphasis></programlisting></para>
- where
- <itemizedlist>
- <listitem><emphasis>tag</emphasis> - A lowercase/number/hyphen identifier. eg: 'new-xx-driver'</listitem>
- <listitem><emphasis>date</emphasis> - In the form DAY MONTH YEAR. eg: '23 Jan 1999'</listitem>
- <listitem><emphasis>title</emphasis> - Freeform text for the entry title - can use \ to
- escape the end of line.</listitem>
- </itemizedlist>
+<listitem>Edit htdocs/Changes/index.xml</listitem>
+<listitem>Add a line in the TOC of the form
+<programlisting>
+ <listitem><ulink url="#link-name">XX Mon XXX - FREEFORM TITLE</ulink></listitem></programlisting>
</listitem>
-<listitem>Add the body of the item. manual pages (eg: &man.ls.1;), and email
- addresses (eg: <user@domain>) will be automatically expanded. Feel
- free to use HTML tags, though this is not compulsory.</listitem>
+<listitem>Further below, in the right section, add the actual entry of the
+form
+ <programlisting>
+ <sect3 id="link-name>
+ <title>XX Mon XXX - FREEFORM TITLE (<ulink url="#monXXXX">top</ulink>)</title>
+ <para>
+ Entry text goes here. Manual pages can be refered to as <quote>&man.command.X;</quote>,
+ email addresses as <email>full@address</email>.
+ <para>
+ </sect3></programlisting>
+ </listitem>
<listitem>Run '<code>make</code>'</listitem>
</orderedlist>
+<para>
+(The www team is working on simplifying this by automating the TOC
+generation.)
+</para>
</sect4>
<sect4 id="adding-links">
@@ -412,7 +447,7 @@
<para>
<programlisting>
cd .../htdocs/gallery
-$EDITOR events.list
+$EDITOR events.xml
make events</programlisting>
</para>