手引きの書き方

1.概要

ここでは「みんなのための・みんなによる手引集」の制作活動に参加してくれる人に 知っておいて欲しい、各ドキュメントの統一書式規格と、準拠する際の具体的な方法を紹介します。


2.統一書式規格

(2.1) 目的

各ドキュメントの書式をある程度統一することで、表記の違いによる混乱を減らし、 多くの人に読みやすい情報を提供する。

(2.2) 書式規格

(2.2.1) 表題

表題は左上に記し、リンク元と必ず揃える。 ただし、タイトルバーに表示されるものはこの限りではない。

例１

(2.2.2) 見出し

見出しは大きめの文字で。必要ならば数字を付ける。過度の装飾は避ける。

(2.2.3) 本文

本文は基本的にインデントする（左側に余白を含ませる）。 程度にもよるが、読みやすくするために、複数行に渡る長文は避ける。 どうしても必要な場合は適切に行間をあける。

なお、各ドキュメントの冒頭には、そのドキュメントの概要が記されていると 親切かもしれない。

(2.2.4) コマンド

文中でコマンドを紹介する場合は、以下のスタイルで行う。 

$ command variable
command ユーザが入力するうち、状況に依存しない部分。 決まっているコマンドや、既に広く一般的になっている引数などが、 これに該当する。
ex.) vi, ls, /var/qmail/bin/maildirmake, public_html
variable ユーザが入力するうち、状況に依存するため、例としての文字列を表現する部分。 実際はユーザ毎に適切な文字・数字・記号等を入力する。
「いくらなんでもそりゃないだろ」的言葉が誤解を生まず望ましい。
ex.) hogehoge, sampletext

※但し、そこに一定の書式が求められる場合は （IP アドレスや MAC アドレス等）、 それが類推できる範囲で抽象化するべきである。
ex.) 123.456.789.001

(2.2.5) 引用文

編集するファイル内容などを例として引用する場合は、以下のスタイルで行う。

例：
AuthType Basic
AuthName The-T-Directory
AuthUserFile /home/hoge/.users
<Limit GET POST>
order deny,allow
deny from all
allow from xxx.xx.xx.xx
</Limit>

ユーザが入力するうち状況に依存する部分は、 /home/hoge/.users のように他と書き分ける。

(2.2.6) 更新日と著者名

ドキュメントの更新日と著者名は、末尾左部に記載する。 筆者氏名にメールアドレスは使わない。 問い合わせ情報はドキュメントには記載せず、 質問等は EPnetFaN 側で受け付けるため。

例：   最終更新日：2001/01/01（筆者氏名）

(2.2.7) 著作権情報

本手引きに寄せられたドキュメント（他サイトへのリンクを除く）は 全て EPnetFaN に帰属するものとし、ドキュメント末尾右部に その旨、提示する。

例：   Copyright © 2000 EPnetFaN

(2.2.8) その他

ブラウザの「戻る」ボタンを使わないでも、 前のドキュメントに戻るようにしておくと親切かもしれない。 このページも表題をクリックすると、前に戻ることができる。


3.この規格に準拠して作るには

統一書式規格（規格と言うほど厳密なものではありませんが）に合わせて ドキュメントを書く際、自分で零から書いて下さっても結構ですが、 労力を軽減すべく、テンプレートを用意しました。

ただし、このテンプレートを使って書く場合、幾つかのお約束を 守って頂かなければなりません。以下では、テンプレートと、 それに纏わるルールを紹介します。

(3.1) テンプレート

テンプレートは下記の通りです。これを元に内容を書き加えてゆくと、 規格に沿ったドキュメントを比較的手軽に作成することができます。

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
    <TITLE> 表題</TITLE>
    <LINK REL ="stylesheet" TYPE="text/css" HREF="css/tebiki.css">
</HEAD>
<BODY>

<H1><A HREF="index.html" CLASS="H1">
    表題
</A></H1>
<HR><DIV CLASS="MAIN">






-- ここにドキュメントの内容を書きます --






</DIV><HR>
<TABLE WIDTH="100%"><TR><TD><SMALL>最終更新日：
<!-- 更新日 情報
????/??/??（筆者氏名）
-->
2000/01/01（林田昭之助）
</SMALL></TD><TD ALIGN="right"><SMALL> Copyright © 2000 EPnetFaN </SMALL></TD></TR></TABLE>
</BODY>
</HTML>

これをコピー＆ペーストして使うか、もしくは red の /home/epnetfan/public_html/tebiki/template/template.html をコピーして使います。

青い文字はドキュメント毎に適切に変更して下さい。

赤い文字はリンク関係です。 ドキュメント毎にパスが異なるかもしれないので、適切に変更して下さい。 デフォルトではドキュメントが手引きの index.html と同じディレクトリにあると仮定しています。 特に最初の <LINK REL ="stylesheet" TYPE="text/css" HREF="css/tebiki.css"> でのパス指定が不正だと、当規格に全然そぐわない形で表示されてしまいます。

(3.2) ルール

(3.2.1) 使ってはいけないタグ

次に示すタグを内容記述の際に使用すると、スタイルが崩れることがあります。

<DIV>, 単品の<P>

(3.2.2) やってはいけないこと

現在確認できている事項は、次の通りです。

(3.2.3) コマンドの表記法

文中でコマンドを紹介する場合は、以下を参考にしてください。

スタイル：TYPE A
説明：     一行のコマンドを表すのに適しています。

<PRE CLASS="line">

-- ここに内容を書きます --

</PRE>

例：

<PRE CLASS="line">
$ <KBD>mkdir <VAR>somefolder</VAR></KBD>
</PRE>

見え方： 
$ mkdir somefolder
スタイル：TYPE B
説明：     複数のコマンドと複数行にわたる応答などを表すのに適しています。

<TABLE CLASS="PRE"><TR><TD><PRE>



-- ここに内容を書きます --



</PRE></TD></TR></TABLE>

例：

<TABLE CLASS="PRE"><TR><TD><PRE>
$ <KBD>/var/qmail/bin/maildirmake ~/Maildir/</KBD>
$ <KBD>ls ~/Maildir/ -al</KBD>
total 4
drwx--S---    5   kyoma    kyoma     1024  Jul 26 20:03 .
drwxr-xr-x    10   kyoma    kyoma     1024  Jul 27 23:14 ..
drwx--S---    2   kyoma    kyoma     1024  Jul 27 16:53 cur
drwx--S---    2   kyoma    kyoma     1024  Jul 27 16:53 new
drwx--S---    2   kyoma    kyoma     1024  Jul 27 16:52 tmp
</PRE></TD></TR></TABLE>

見え方： 
$ /var/qmail/bin/maildirmake ~/Maildir/
$ ls ~/Maildir/ -al
total 4
drwx--S---   5 kyoma    kyoma        1024 Jul 26 20:03 .
drwxr-xr-x  10 kyoma    kyoma        1024 Jul 27 23:14 ..
drwx--S---   2 kyoma    kyoma        1024 Jul 27 16:53 cur
drwx--S---   2 kyoma    kyoma        1024 Jul 27 16:53 new
drwx--S---   2 kyoma    kyoma        1024 Jul 27 16:52 tmp
内容表現：ユーザが入力するもののうち、状況に依存しない部分
<KBD>   -- ここに内容を書きます --   </KBD>

※例と見え方は、上のスタイルを参考にしてください。
内容表現：ユーザが入力するうち、状況に依存する部分
<VAR>   -- ここに内容を書きます --   </VAR>

※例と見え方は、上のスタイルを参考にしてください。


(3.2.4) 引用文の表記法

編集するファイル内容などを例として引用する場合は、以下を参考にしてください。

スタイル：
<BLOCKQUOTE CLASS="sample">



-- ここに内容を書きます --



</BLOCKQUOTE>

例：

<BLOCKQUOTE CLASS="sample">
AuthType Basic<BR>
AuthName The-T-Directory<BR>
AuthUserFile <VAR>/home/hoge/.users</VAR><BR>
&lt;Limit <VAR>GET POST</VAR>&gt;<BR>
order deny,allow<BR>
deny from all<BR>
allow from <VAR>xxx.xx.xx.xx</VAR><BR>
&lt;/Limit&gt;<BR>
</BLOCKQUOTE>

見え方：
AuthType Basic
AuthName The-T-Directory
AuthUserFile /home/hoge/.users
<Limit GET POST>
order deny,allow
deny from all
allow from xxx.xx.xx.xx
</Limit>
内容表現：ユーザが入力するうち、状況に依存する部分
<VAR>   -- ここに内容を書きます --   </VAR>

※例と見え方は、上のスタイルを参考にしてください。


4.参考文献

「詳細 HTML & JavaScript 辞典」（岡崎 桂子／長谷川 豊／半場 方人：秀和システム）

※けっこう間違いもありますが、よく纏まっているので重宝しています。 現在はもっと良い本が出ていると思います。

最終更新日： 2000/07/28（河野仁之） Copyright © 2000 EPnetFaN