Go to the first, previous, next, last section, table of contents.


助言とヒント

Texinfoドキュメントを書くための助言として以下をあげます.

索引,索引,索引!

異なる方法で多くの索引項目を書いてください.読者は索引が好きです.それら は役に立ち便利です.

テキストの本体に書くように索引項目を書くのが最も簡単ですが,項目を後で書 くのを好む人もいます.どちらの場合でも,現れる段落の前に項目を書いてくだ さい.この方法では,索引項目はページを跨ぐ段落の最初のページを示します.

我々が貴重だと分かったより多くのヒントには以下のものがあります.

空白行

完全なフレーズ

完全なフレーズは何よりも読み易く@enddots{}

エディション,日付と,バージョン

全てのマニュアルの三箇所に,エディションナンバー,バージョンナンバー,そ して日付を,@copyingのテキストに含めてください(Texinfoファイルを 読む人のためと,出力ファイルの法的な著作権のためです).そして, @insertcopying@titlepageセクション(印刷されたマニュア ルを読む人のため)とTopノード(オンラインの出力を読む人のため)で使用してく ださい.

こうするためには,@set@valueを使用するのが最も簡単です. See section @valueの例, and section GNUの見本のテキスト.

定義コマンド

定義コマンドは,@deffn@defun@defmacとその同 類で,単一の書式で記述を書くことを可能にします.

大文字化

スペース

@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,@samp,@var,そして`---'

引用外部のピリオド

句読点が引用の部分でない場合は,ピリオドとその他の句読点を引用の外 側に置いてください.この実行は,合州国の出版の慣習に反しますが,読者は 引用の内容と文節全体との区別が可能となります.

例えば,終りの引用符の外側にピリオドを文に続けて書くべきです.

Evidently, `au' is an abbreviation for ``author''.

`au'は,`author.'(単語に続くピリオドと一緒)の省略として提供さ れていません

新しい用語の紹介

設計された特別な文脈(つまりカッコの中)以外で,@pxrefを絶対に使用 しないでください.カッコの内部で,閉じ弓カッコの直後に閉じカッコを使用し ます.一つのフォーマッタは自動的に句読点を挿入し,もう一つはそうしません. これは,印刷物とInfoファイルで出力は正しく見えますが,それはコマンドがカッ コの中で使用されるときだけだということを意味します.

シェルからの呼び出し

Emacs,GCC,そしてgawkのようなプログラムをシェルから呼び出すこと が可能です.それぞれのプログラムのドキュメントには,このことを述べている セクションを含むべきです.残念ながら,これらのセクションのノード名とタイ トルが全く異なっている場合,ユーザがセクションを見つけるのは困難です.

そのため,そのようなセクションは,`Invoking Emacs'のように,単語 `Invoking'で始まる文節で命名するという慣習があります.この方法で,ユーザ はセクションを簡単に見つけることが可能になります.(18)

ANSI Cの構文

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.

終りに...


Go to the first, previous, next, last section, table of contents.