SDB:Howto

移動先: 案内, 検索


概要

このSDB (サポートデータベース) 文書では、どのようにしてSDB文書を書くのかについて説明をしています。

手順

SDB文書は、SUSE Linuxで発生した何らかの問題について解決法を与えるだけでなく、特定の題材についてより細かい説明を与えることを目指して記述しているものです。もしも誰かがSUSE Linuxで何か問題を抱えているのなら、SDBは助けを得るために最初に参照される場所であるべきです。

1つのSDB文書は以下のような項目から構成されるべきものです:

  • 状況
  • 手順
  • 関連文書

または

  • 問題
  • 原因
  • 解決法
  • 関連文書

ここで注意しておいて欲しいのは、SDB文書はできる限り簡単な解決方法を示したものであるべきということです。しかしながら、簡単な方法とともにコマンドライン(シェル)を利用したり設定ファイルを操作したりなどの手順で示した手っ取り早い解決方法も示してあることが望ましいです。この場合は、「解決法」の項目をいくつかに分割するとよいでしょう。文法について説明する前に、まずは以下の例を読んでください (以下は mediawiki の文法で書いてあります。表示例を見るには SDB:Changing NTP Server - SDB Example を参照してください)。

文書例

<!-- SDB information
SDB:title: NTPサーバの変更方法 - SDB文書例
SDB:author: mlasars
SDB:date: 2005-10-17 -->

 Version: 9.0

[[Category:SDB:Network|N]]
[[Category:SDB:9.0|N]]

この記事はSDB記事を書くための例です。

== 状況 ==

あるNTPサーバを利用して時刻を同期するよう設定してありますが、
そのNTPサーバはすでに稼働していない状況にあるものとします。

== 手順 ==

いくつかの解決方法があります。

=== YaST2を使う ===

YaST2を開始し、「ネットワークサービス」→「NTPクライアント」を選びます。
そこから「選択」ボタンを押すと表示される「公開NTPサーバ」のサブメニューを選択してください。
表示されるダイアログボックスであなたが今いる国(または近くの国)とサーバを選んでください。
「テスト(T)」ボタンを押してNTPサーバとの接続を確認したら、最後に「完了(F)」ボタンを押して終了です。

=== コマンドラインを使う ===

設定ファイル <code>/etc/sysconfig/ntp</code> を開き、設定値 <code>NTPD_INITIAL_NTPDATE=""</code> を変更してください。
変更が終わったら以下のようにNTPを再起動します。

 rcntpd restart

== 関連文書 ==
[[SDB:ネットワークを利用した時刻同期]]

<keyword>ntp,xntp,time,synchronize,時刻,同期</keyword>
[[en:SDB:ntp_server_change(example)]]

新しい記事を作成する

あなたがお使いのブラウザで、URL欄に "SDB:" に続いて新しい記事のタイトルを入力してください。その記事が存在していなければ "編集" ボタンで作成・編集を行なってください。 記事の上書きは避けてください。もし必要であればバージョン番号や "(new)" などの記述をタイトルに入れてください。

すべてのSDB文書は "SDB:" で始まっていなければなりません。このことでWiki内の構成管理を行なっているためです。

結果

履歴

文書の編集を終えたら、その内容をSDB:Historyに追加してください。 記述方法は以下の通りです: 

YYYYMMDD [[SDB:<articlename>]]

たとえば: 

20051016 [[SDB:Howto]]

のようになります。 日付は国際標準の書式を利用してください。一覧は降順に並べ、新しい文書が一覧の先頭に来るようにしてください。

新しいバージョンへの更新など文書に大きな変更を加えた場合は、履歴にその旨を記載してください。小さな変更や追加などは履歴に追加すべきではありません。

翻訳

現時点でopenSUSE wikiは英語・ドイツ語・フランス語・スペイン語・日本語に対応しています。もしもあなたがこれらの言語に精通していれば、記事の翻訳をしていただけると助かります。そうでなくて外国語に不慣れな場合はopensuse-wikiメーリングリストで誰かに記事の翻訳をお願いしてみてください。

もしもあなたがある記事を翻訳した場合は、文書の終わりにある "Interwiki" リンクに追加を行なってください。たとえばあなたがドイツ語から日本語に翻訳を行なった場合、ドイツ語の文書の終わりに以下を追加します: 

[[ja:SDB:<記事名>]]

翻訳を行なったほうの日本語文書には、以下を追加します: 

[[de:SDB:<記事名>]]

現時点では以下の言語名がサポートされています: 

de ドイツ語
en 英語
fr フランス語
es スペイン語
ja 日本語

既存の記事を変更する

SDBがopenSUSE Wikiに統合されたことにより、すべての文書を編集することができるようになりました。もしもあなたが大まかな変更を加えたいと考えているのであれば、元の著者と議論をするのがよいでしょう。記事の終わりにある「ノート」リンクを利用してください。

これは強制ではありませんが、Wikiでの共同制作をより簡単に楽しく行なうことができるでしょう。もしもこの議論で解決をみない場合は、opensuse-wikiメーリングリストにメールを送れば助けになるでしょう。

小さな変更は議論なしで行なわれるかもしれません。

SDB タグ

目次

文書に3つ以上の項目 (=== Section ===で記述されるもの) が作成されると、wikiソフトウエアは自動的に目次を生成します。SDB文書の標準に従って「状況」「手順」「関連文書」を作成すれば項目が3つになりますから、自動で目次が生成されることになります。


SDB メタ情報

以下のように文書の冒頭にメタ情報を入れてください。この内容は表示されません。 

<!-- SDB information
SDB:title: NTPサーバの変更方法 - SDB文書例
SDB:author: mlasars
SDB:date: 2005-10-17 -->

ある記事に大きな変更を加えた場合、著者の欄にコンマ区切りであなたの名前を入れてください。その他のメタ情報、特に SDB:date は変更しないでください。すべての文書変更は「履歴」で見ることができます。メタ情報は将来発生するシステムの再構成の際に重要なデータとなります。

バージョン

記事の冒頭にはその内容が有効となるSUSE Linuxのバージョンを定義してください。これにはいくつかの書き方があります: 

Version: 8.0
Version: - 8.0
Version: 8.0 -
Version: 8.0 - 8.1

もしも特定のバージョンについての記事でなければ、バージョンの欄は省略してください。もしも特定のアーキテクチャや形態について適用されるものであれば、以下のようにしてください: 

Version: 9.2 x86_64
Version: 9.1 DVD
Version: 10.0 ppc

現時点ではSUSE Linuxは以下のアーキテクチャをサポートしています: i386, x86_64 (64bit環境, AMD64かIntel EM64T), ppc (PowerPC (Mac)).

形態については以下のものがあります: Box (製品版), FTP, CD, DVD and OSS.

これらのタグはある問題が特定の状況下で発生する場合にのみ追加してください。

注意: バージョン表記の周囲に枠を表示させるため、バージョン情報の行頭には半角スペースを入れてください。

分類(カテゴリ)

それぞれのSDB文書は分類を通じてアクセスできるようにすべきです。現在までに用意されている分類は Category:SDB から参照できます。記事に分類を追加するには、記事の冒頭に: 

[[Category:SDB:8.0|N]]
[[Category:SDB:Network|N]]

を追加してください。

分類表記には縦棒 (パイプ)文字を続け、文書タイトルの最初の1文字を入れてください。 上記の例では「NTPサーバの変更方法」の記事についてですから、縦棒 (パイプ)文字に続いて「N」を記入します。

キーワード

文書の終わりにはその文書に関連するキーワードをすべて指定します: 

<keyword>ntp,time,xntp,synchronize,時刻,同期</keyword>

キーワードはどんな文字列でもかまいません。

文法

Wiki (日本語) Wiki (英語) の文法とは違い、MediaWikiは通常のHTMLタグをサポートしています。 できるかぎりWikiの記述方法を使うものとして、文書のソースコードを読みやすく／編集しやすくしてください。 よく使われる記述方法については以下に示しますが、より詳しい情報を得るには以下のサイトを参照してください。 http://ja.wikipedia.org/wiki/Wikipedia:編集の仕方 (日本語) http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page (英語)


セクション

  • レベル1: == トップレベルヘッダ == ("状況", "手順", "関連" など)
  • レベル2: === サブヘッダ === (YaST2の操作手順やコマンドライン表記など)
  • レベル3: ==== 1レベル下 ==== (より細かい記述、たとえば別のやり方など)

"状況" や "手順" は常にトップレベルヘッダとして見えるべきで、他の項目などはそれ以下にあるべきです。

フォーマット

段落を記述するとき、HTMLの書式でいう <p>段落</p> のような書き方をする必要はありません。段落は2行分の空行があれば自動で生成されます。

Wiki Markup Display 
  
こちらは1つめの段落です。
複数の行にまたがって書くことができます。


こちらは2つめの段落です。

こちらは1つめの段落です。 複数の行にまたがって書くことができます。


こちらは2つめの段落です。

テキスト (強調, 斜字, コード表記)

段落や単語を強調したい場合、以下のような文法を用いてください:

スタイル 記述方法 表示
強調 '''重要な段落や単語に限って使ってください''' 重要な段落や単語に限って使ってください
斜字 ''斜字体の例です'' 斜字体の例です
コード表記 コマンドや変数などにはこれを使ってください: <code>rcapache2</code> コマンドや変数などにはこれを使ってください: rcapache2

列挙／一覧

何かの内容を羅列したい場合は以下のようになります:

記述方法 表示 
* 惑星
** 火星
** 地球
*** 月
  • 惑星
    • 火星
    • 地球
      • 月
#旅行
## 航空機
## 車
### タクシー
  1. 旅行
    1. 航空機
    2. 車
      1. タクシー

文書の終わりに記載する関連文書の表示は細分化せず * 関連 を使ってください。

コマンドや設定ファイルの引用

単一行のコマンドを含む行の冒頭は半角スペースを入れてください。 

rcapache2 restart

このことでコマンド表記を目立たせることができます。ふつうの文章の中にコマンド表記を入れるには <code>command</code> のような表記を使ってください。

ソースコードや設定ファイルの表記には以下のような文法を利用してください:

記述方法 表示 
<pre>
## Path:        Network/Remote access/SSH
## Description: SSH server settings
## Type:        string
## Default:     ""
## ServiceRestart: sshd
#
# Options for sshd
#
SSHD_OPTS=""
<nowiki>
</nowiki>

</pre> 

## Path:        Network/Remote access/SSH
## Description: SSH server settings
## Type:        string
## Default:     ""
## ServiceRestart: sshd
#
# Options for sshd
#
SSHD_OPTS=""

nowiki

特定の状況下でwiki表記を無効化したい場合は、以下の文法を利用してください:

記述方法 表示 nowikiを利用しない場合

<nowiki>'''強調''' も ''斜字'' も使いません</nowiki>

'''強調''' も ''斜字'' も使いません

強調 も 斜字 も使いません

関連

他のSDB文書とリンクを張るには、 "SDB:" を利用して [[SDB:howto]] のように書き、リンクラベルを書く必要はありません。ある文書の特定の場所にリンクを張るには、 [[SDB:howto#Stil]] のように書くと SDB:howto#Stil のようにして表示されます。もしも文書の特定のキーワードから直接リンクしたい場合は、このような書式が便利でしょう: [[SDB:howto#Stil|Stil]] 。この形式ではこのように表示されます Stil.

外部サイトへのリンクは、それが明らかである場合を除いてリンクラベルを書いてください。このことでリンクを短く表示することができます。

たとえば [http://www.suse.de SUSE] のように記述すると、 SUSE のように表示されます。この場合、リンクとリンクラベルは単純に半角スペースで区切ってください。

なお、外部サイトへのリンクに際しては国内の法律に違反していないかどうか注意してください。たとえばドイツでは不正コピー防止技術を回避するために用いられるソフトウエアへのリンクは違法です。もしも外部サイトへのリンクをするのに不安な場合はopensuse-wikiメーリングリストで尋ねてみてください (Communicate を参照)。

表組み

以下を参照してください http://ja.wikipedia.org/wiki/Wikipedia:表の作り方 (日本語版) または shttp://en.wikipedia.org/wiki/Wikipedia:How_to_use_tables (英語版)

画像

現在までにおいてSDB文書に画像は使われていません。レイアウトや文章の流れを乱さぬよう、どうしても画像が必要な場合に限って使ってください。 もし可能であれば、文書の右余白に画像のプレビュー (縮小表示) だけを置いてください。 より詳しい情報は http://ja.wikipedia.org/wiki/Wikipedia:画像の表示 (日本語版) または http://en.wikipedia.org/wiki/Wikipedia:Image_markup (英語版) を参照してください。

スタイル

読み手に宛てるために

ドイツ語のSDB文書では技術文書の標準的な作法に従い、 "Sie" ("you", 「あなた」) という言葉を使って丁寧な表現をしています。あなたがお使いの言語でそのような表現があれば、そちらを使ってください。英語では "you" しかないので問題になりませんが ;-)。

用語と外国語について

英語以外の言語では、英語の技術用語なしで話を進めるのは難しい場合があります。数多くのSDB利用者に便利になるような書き方を心がけてください。逆に英語による用語が一般に普及し理解されている場合は翻訳しないでおいてください。両方を括弧書きで併記するこのような妥協案もあります: "2番目のコンソール (コマンドライン) に移動するには、CTRL-ALT-F2を押します"

親切に！

シェルを使うということは、特にあなたにとって簡単なことなのでしょうが、できればLinux初心者のことを考慮してYaST2やその他のツールで解決する方法を併せて説明しておいてください。

良いSDB文書はそれぞれの段階をきちんと説明するものです。ですから、以下のような書き方ではいけません: 

/etc/inittabで既定のランレベルを3にする

このような書き方が良いでしょう: 

rootでログインを行ない、/etc/inittab をエディタで開きます
(エディタはお好きなものでかまいません、viだろうとpicoだろうと)。
そして、 "id:5:initdefault:" と書いてある行を "id:3:initdefault:"
に修正すればGUIが起動しなくなります。

これは強制ではありません! ですがLinux初心者もSUSE Linuxを使っていることを忘れないでください。

メンテナンス

SDB文書を新しいバージョンのSUSE Linuxに合わせたり、重要な部分が変更されたために新しい文書を書き起こしたりするということはたびたび必要になる作業です。SDB文書の保守をしてください。たとえば、最新のSUSE Linuxには当てはまらない文書であれば、"version" の欄を修正して当てはまらない旨を明記してください。

関連文書

「https://ja.opensuse.org/index.php?title=SDB:Howto&oldid=307」から取得