| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Texinfoドキュメントを書くための助言として以下をあげます．
異なる方法で多くの索引項目を書いてください．読者は索引が好きです．それら は役に立ち便利です．
テキストの本体に書くように索引項目を書くのが最も簡単ですが，項目を後で書 くのを好む人もいます．どちらの場合でも，現れる段落の前に項目を書いてくだ さい．この方法では，索引項目はページを跨ぐ段落の最初のページを示します．
我々が貴重だと分かったより多くのヒントには以下のものがあります．
以下の例では，空白行が索引項目"Leaping"の後にあります．
@section The Dog and the Fox @cindex Jumping, in general @cindex Leaping @cindex Dog, lazy, jumped over @cindex Lazy dog jumped over @cindex Fox, jumps over dog @cindex Quick fox jumps over dog The quick brown fox jumps over the lazy dog. |
(例で，同じ概念に対する項目を異なる方法で書いていることに注意してくださ い -- `Lazy dog'と`Dog, lazy' -- それで読者は，異なる方法で 概念を見つけることが可能になります．)
@tableコマンドの前と@end tableコマンドの後に，空白行を常
に挿入してください．しかし，@tableコマンドの後と@end
tableコマンドの前には，空白行を決して挿入しないでください．
例えば，以下のようにします．
Types of fox: @table @samp @item Quick Jump over lazy dogs. @item Brown Also jump over lazy dogs. @end table @noindent On the other hand, ... |
同じ方法で，@itemize ... @end itemizeの前後と，
@enumerate ... @end enumerateの前後に空白行を挿入し
てください．
完全なフレーズは何よりも読み易く....
全てのマニュアルの三箇所に，エディションナンバー，バージョンナンバー，そ
して日付を，@copyingのテキストに含めてください(Texinfoファイルを
読む人のためと，出力ファイルの法的な著作権のためです)．そして，
@insertcopyingを@titlepageセクション(印刷されたマニュア
ルを読む人のため)とTopノード(オンラインの出力を読む人のため)で使用してく
ださい．
こうするためには，@setと@valueを使用するのが最も簡単です．
See section @value Example, and C.2 GNUの見本のテキスト.
定義コマンドは，@deffn，@defun，@defmacとその同
類で，単一の書式で記述を書くことを可能にします．
@table ... @end tableを関数の概要を含む付録に使用し，
@deffnや他の定義コマンドを使用しないでください．
@TeX{}コマンドを使用して書いてください．大文字の
`T'と`X'に注意してください．このコマンドは，TeXを書いた
Donald Knuthに希望に従ってフォーマッタに植字させます．
@example ... @end exampleと類似のコマンド内部以外で，
Texinfoファイルの書式化のためにスペースを使用しないでください．
例えば，TeXは以下を補充します．
@kbd{C-x v}
@kbd{M-x vc-next-action}
現在のバッファに対応する，
バージョンで制御されたファイルで，
次の論理オペレーションを実行する．
|
そのため以下のように見えます．
`C-x v' `M-x vc-next-action' 現在のバッファに対応する，バージョンで制御 されたファイルで，次の論理オペレーションを実行する．
この場合，テキストは，表を作成する@table，@item，そして
@itemxで書式化するべきです．
@codeを使用してください．
例えば，以下のようにします．
主な関数は@code{vc-next-action}で，...
|
@varを使用してください．それらの周りに，山カッコ
を書かないでください．
句読点が引用の部分でない場合は，ピリオドとその他の句読点を引用の外 側に置いてください．この実行は，合州国の出版の慣習に反しますが，読者は 引用の内容と文節全体との区別が可能となります．
例えば，終りの引用符の外側にピリオドを文に続けて書くべきです．
Evidently, `au' is an abbreviation for ``author''. |
`au'は，`author.'(単語に続くピリオドと一緒)の省略として提供さ れていません．
例えば，以下で用語"check in"，"register"，そして"delta"はすべて， 初めて現われます．例文を理解できるように書き換えるべきです．
The major function assists you in checking in a file to your version control system and registering successive sets of changes to it as deltas.
@dfnコマンドを紹介している単
語の周りに使用してください．
設計された特別な文脈(つまりカッコの中)以外で，@pxrefを絶対に使用
しないでください．カッコの内部で，閉じ弓カッコの直後に閉じカッコを使用し
ます．一つのフォーマッタは自動的に句読点を挿入し，もう一つはそうしません．
これは，印刷物とInfoファイルで出力は正しく見えますが，それはコマンドがカッ
コの中で使用されるときだけだということを意味します．
Emacs，GCC，そしてgawkのようなプログラムをシェルから呼び出すこと
が可能です．それぞれのプログラムのドキュメントには，このことを述べている
セクションを含むべきです．残念ながら，これらのセクションのノード名とタイ
トルが全く異なっている場合，ユーザがセクションを見つけるのは困難です．
そのため，そのようなセクションは，`Invoking Emacs'のように，単語 `Invoking'で始まる文節で命名するという慣習があります．この方法で，ユーザ はセクションを簡単に見つけることが可能になります．(18)
C関数の呼び出しの慣習を記述するため@exampleを使用するとき，以下
のようにANSI C構文を使用してください．
void dld_init (char *@var{path});
|
そしてそれに続く引数では，再び@varで強調されている同じ引数名で引
数の値を参照してください．
以下のような，古いスタイルを避けてください．
#include <dld.h> dld_init (path) char *path; |
また，関数がヘッダファイルで宣言されていることを示すだけのため，宣言の上
に#includeを書くことを避けるのが最善です．その方法では，関数宣言
の近くに#includeがあるという間違った印象を与えるかもしれません．
ヘッダファイルに宣言があることを明示的に宣言する，またはより良いものとし
て，関数を記述しているセクションの始めで，関数グループのために使用されて
いるヘッダファイルに名前をつけるかのどちらかにしてください．
避けるべき悪い書き方の例のいくつかは以下のようになります．
この例で，" ... you must @dfn{check in} the new
version."と言っています．それで，より良くことが運びます．
When you are done editing the file, you must perform a
@dfn{check in}.
以下の例では，"... makes a unified interface such as VC mode possible."と言っています．
SCCS, RCS and other version-control systems all perform similar functions in broadly similar ways (it is this resemblance which makes a unified control mode like this possible).
そして，この例では，`it'が何を参照しているのか指定すべきです．
If you are working with other people, it assists in coordinating everyone's changes so they do not step on each other.
@byeの後のTexinfoファイルの終りに，独自の注釈を書いてください．
フォーマッタは@byeの後のテキストを処理しません．それは，テキスト
が@ignore ... @end ignoreの内側にあるのと同じです．
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |