関連項目のリストに長いマニュアルページ名が多く含まれる場合には、出力を見やすくするために \fI.ad l\fP (右揃えをしない) や \fI.nh\fP
(ハイフンによる折り返しをしない) を活用するとよい。個々のページ名のハイフンによる折り返しは、単語の前に "\e%" を付けることで防ぐことができる。
.SH スタイルガイド
-The following subsections describe the preferred style for the \fIman\-pages\fP
-project. For details not covered below, the Chicago Manual of Style is
-usually a good source; try also grepping for preexisting usage in the
-project source tree.
-.SS "Use of gender\-neutral language"
-As far as possible, use gender\-neutral language in the text of man pages.
-Use of "they" ("them", "themself", "their") as a gender\-neutral singular
-pronoun is acceptable.
+以下の節では\fIman\-pages\fPプロジェクトで推奨のスタイルについて説明している。 ここで触れられていない点については、"the Chicago
+Manual of Style" がたいていはよい情報源になるだろう。
+また、すでに使用されているスタイルについてはプロジェクトのソースツリーを検索してみてほしい。
+(訳注：この章では英語の原文でのスタイルについて説明しており、日本語マニュアルにはあわない点もあるため、具体例などは英語のままとしている箇所もあります。)
+.SS 性別の区別のない表現の使用
+可能な限り、マニュアルページの文章では性別の区別のない表現を使用すること。 性別に区別のない単数形の代名詞として "they" ("them",
+"themself", "their") を使用してもよい。
.SS フォントの慣習
.PP
関数に対しては、引き数には常にイタリック体を用いる。 「たとえ書式 (SYNOPSIS) セクションであっても、このルールに従う」
.fi
(相互参照にセクション番号を含めておくと、 \fBman2html\fP といったツールがページ間のハイパーリンクを適切に生成できる。)
-Control characters should be written in bold face, with no quotes; for
-example, \fB^X\fP.
+制御文字は太字で引用符なしで表記すること。 例えば \fB^X\fP。
.SS "綴り (spelling)"
リリース 2.59 からだが、 \fIman\-pages\fP はアメリカ英語の綴りの慣習に従っている
(以前はイギリス英語とアメリカ英語が基準もなく混在して使われていた)。 新しいページやパッチは全てこの慣習に従って下さい。
-Aside from the well\-known spelling differences, there are a few other
-subtleties to watch for:
+よく知られた綴りの違い以外に、微妙な違いもいくつか見られる。
.IP * 3
-American English tends to use the forms "backward", "upward", "toward", and
-so on rather than the British forms "backwards", "upwards", "towards", and
-so on.
-.SS "BSD version numbers"
-The classical scheme for writing BSD version numbers is \fIx.yBSD\fP, where
-\fIx.y\fP is the version number (e.g., 4.2BSD). Avoid forms such as \fIBSD
-4.3\fP.
+アメリカ英語では "backward", "upward", "toward" を使う傾向にあるが、イギリス英語では "backwards",
+"upwards", "towards" などを使う方が多い。
+.SS "BSD バージョン番号"
+BSD バージョン番号の伝統的な表記方法は \fIx.yBSD\fP である (\fIx.y\fP はバージョン番号; 例: 4.2BSD)。 \fIBSD 4.3\fP
+といった表記は避けること。
.SS 大文字表記
サブセクション ("SS") 見出しでは、最初の単語だけ先頭文字を大文字にし、残りの単語は小文字にすること。但し、英語の用法 (例えば、固有名詞)
やプログラミング言語の要件 (例えば、識別子の名前) などで別の表記をする場合はこの限りではない。
.SS 構造体の定義、シェルのセッションログなどの字下げ、など
構造体の定義やシェルのセッションログなどを本文中に記載する際は、 スペース 4個分の字下げを行う (つまり、ブロックを \fI.in\ +4n\fP と
\&\fI.in\fP で囲む)。
-.SS "Preferred terms"
-The following table lists some preferred terms to use in man pages, mainly
-to ensure consistency across pages.
+.SS 推奨用語
+以下の表にマニュアルページでの使用が推奨される用語を示す。これらは主にマニュアルページ間での一貫性を保つためである。
.TS
l l l
---
zeros zeroes
.TE
.PP
-See also the discussion \fIHyphenation of attributive compounds\fP below.
-.SS "Terms to avoid"
-The following table lists some terms to avoid using in man pages, along with
-some suggested alternatives, mainly to ensure consistency across pages.
+以下の\fI修飾子としての複合語におけるハイフン\fPの議論も参照。
+.SS 使用を避ける用語
+以下の表にマニュアルページでの使用を避けるべき用語を示す。 推奨される表現も合わせて記載している。
+これらは主にマニュアルページ間での一貫性を保つためである。
.TS
l l l
---
l l l.
-Avoid Use instead Notes
+使用を避ける 使用を推奨 備考
32bit 32\-bit T{
-same for 8\-bit, 16\-bit, etc.
+8\-bit, 16\-bit なども同様
T}
current process calling process T{
-A common mistake made by kernel programmers when writing man pages
+カーネルプログラマーがマニュアルページを書く際によくする間違い
T}
manpage T{
man page, manual page
Unixes UNIX systems
.TE
.SS 商標
-Use the correct spelling and case for trademarks. The following is a list
-of the correct spellings of various relevant trademarks that are sometimes
-misspelled:
+商標については正しい綴りと大文字小文字を使うこと。以下は時々綴りの間違いがある商標の正しい綴りのリストである。
DG/UX
HP\-UX
UNIX
UnixWare
-.SS "NULL, NUL, null pointer, and null character"
-A \fInull pointer\fP is a pointer that points to nothing, and is normally
-indicated by the constant \fINULL\fP. On the other hand, \fINUL\fP is the \fInull
-byte\fP, a byte with the value 0, represented in C via the character constant
-\fI\(aq\e0\(aq\fP.
-
-The preferred term for the pointer is "null pointer" or simply "NULL"; avoid
-writing "NULL pointer".
-
-The preferred term for the byte is "null byte". Avoid writing "NUL", since
-it is too easily confused with "NULL". Avoid also the terms "zero byte" and
-"null character". The byte that terminates a C string should be described
-as "the terminating null byte"; strings may be described as
-"null\-terminated", but avoid the use of "NUL\-terminated".
+.SS "NULL, NUL, ヌルポインター、ヌル文字"
+\fInull pointer\fP (\fIヌルポインター\fP) は何もないものを指すポインターで、通常は定数 \fINULL\fP で示される。 一方、
+\fINUL\fP は \fInull byte\fP (\fIヌルバイト\fP、値 0 のバイト) で、 C では文字定数 \fI\(aq\e0\(aq\fP と表現される。
+
+ポインターとして推奨される用語は "null pointer" (ヌルポインター) もしくは単に "NULL" である。 "NULL pointer"
+と記載するのは避けること。
+
+バイトとして推奨される用語は "null byte" (ヌルバイト) である。 "NUL" と記載するのは避けること。 "NUL" は "NULL"
+と間違われることが非常に多いからである。 また、 "zero byte" (ゼロバイト) と "null character" (ヌル文字)
+も避けること。 C の文字列を終端するバイトは "the terminating null byte" (終端ヌルバイト)、
+文字列の説明として使う場合には "null\-terminated" (ヌル終端された) と記載すべきである。 "NUL\-terminated"
+の使用は避けること。
.SS ハイパーリンク
-For hyperlinks, use the \fI.UR\fP/\fI.UE\fP macro pair (see \fBgroff_man\fP(7)).
-This produces proper hyperlinks that can be used in a web browser, when
-rendering a page with, say:
+ハイパーリンクについては、 \fI.UR\fP/\fI.UE\fP マクロの組を使うこと (\fBgroff_man\fP(7)
+参照)。ページを以下のようにレンダリングする場合に、このマクロはウェブブラウザーで使用できる正しいハイパーリンクを生成してくれる。
BROWSER=firefox man \-H pagename
-.SS "Use of e.g., i.e., etc., a.k.a., and similar"
-In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
-"a.k.a." should be avoided, in favor of suitable full wordings ("for
-example", "that is", "and so on", "also known as").
-
-The only place where such abbreviations may be acceptable is in \fIshort\fP
-parenthetical asides (e.g., like this one).
-
-Always include periods in such abbreviations, as shown here. In addition,
-"e.g." and "i.e." should always be followed by a comma.
-.SS Em\-dashes
-The way to write an em\-dash\(emthe glyph that appears at either end of this
-subphrase\(emin *roff is with the macro "\e(em". (On an ASCII terminal, an
-em\-dash typically renders as two hyphens, but in other typographical
-contexts it renders as a long dash.) Em\-dashes should be written \fIwithout\fP
-surrounding spaces.
-.SS "Hyphenation of attributive compounds"
-Compound terms should be hyphenated when used attributively (i.e., to
-qualify a following noun). Some examples:
-
- 32\-bit value
- command\-line argument
- floating\-point number
- run\-time check
- user\-space function
- wide\-character string
-.SS "Hyphenation with multi, non, pre, re, sub, and so on"
-The general tendency in modern English is not to hyphenate after prefixes
-such as "multi", "non", "pre", "re", "sub", and so on. Manual pages should
-generally follow this rule when these prefixes are used in natural English
-constructions with simple suffixes. The following list gives some examples
-of the preferred forms:
+.SS "e.g., i.e., etc., a.k.a. などの使用"
+一般的には、 "e.g.", "i.e.", "etc.", "a.k.a." などの省略形の使用は避けるべきである。 代わりに完全な形の単語を使うこと
+("for example" (例えば), "that is" (つまり), "and so on" (〜など), "also known as"
+(別名))。
+
+これらの省略形の使用が認められる唯一の場所は、 \fI短い\fP括弧で囲まれた余談 ("(e.g., like this one)") の場合である。
+
+ここで記載しているように、これらの省略形では必ずピリオドを入れること。 また、"e.g." と "i.e." では常に後にカンマも付けること。
+.SS "em によるダッシュ"
+*roff で em によるダッシュ\(emこの部分の両端にある記号\(emを書くには "\e(em" を使う。 (ASCII 端末では em
+によるダッシュは通常ハイフン 2 つとして表示されるが、別の活版印刷の場合などでは長いダッシュとして表示されることもある。) em
+によるダッシュの両側にはスペースを\fI置かないこと\fP。
+.SS 修飾子としての複合語におけるハイフン
+何かを修飾する際 (すなわち後続の名詞を限定する場合) 複合語にはハイフンを入れること。いくつか例を挙げる。
+
+ 32\-bit value (32 ビット値)
+ command\-line argument (コマンドライン引き数)
+ floating\-point number (浮動小数点数)
+ run\-time check (実行時チェック)
+ user\-space function (ユーザー空間関数)
+ wide\-character string (ワイド文字の文字列)
+.SS "multi, non, pre, re, sub などとの組み合わせでのハイフン"
+一般的に最近の英語の傾向では、"multi", "non", "pre", "re", "sub" などの接尾辞の後ろにはハイフンを付けない。
+これらの接尾辞が単純な接尾語との普通の英語の組み合わせの場合には、 マニュアルページでは基本的にこのルールに従う。
+以下のリストに推奨される形式での例をいくつか挙げる。
interprocess
multithreaded
subdirectory
subsystem
-Hyphens should be retained when the prefixes are used in nonstandard English
-words, with trademarks, proper nouns, acronyms, or compound terms. Some
-examples:
+接尾語が通常の英単語以外 (商標、固有名詞、頭字語、複合語) と組み合わされる場合は、ハイフンを使うこと。以下に例を挙げる。
non\-ASCII
non\-English
non\-NULL
non\-real\-time
-Finally, note that "re\-create" and "recreate" are two different verbs, and
-the former is probably what you want.
-.SS "Real minus character"
-Where a real minus character is required (e.g., for numbers such as \-1, or
-when writing options that have a leading dash, such as in \fIls\ \-l\fP), use
-the following form in the man page source:
+最後に、"re\-create" と "recreate" は異なる別の動詞である点に注意すること。たいていの場合、使おうと思っているのは前者であろう。
+.SS 本当のマイナス文字
+本当の意味でのマイナス文字が必要な場合は (\-1 といった数字や \fIls\ \-l\fP
+といった先頭にダッシュのオプションを記載する場合など)、マニュアルページの原文では以下の表記を使うこと。
\e\-
-This guideline applies also to code examples.
-.SS "Character constants"
-To produce single quotes that render well in both ASCII and UTF\-8, use the
-following form for character constants in the man page source:
+このガイドラインはサンプルコードの場合にも適用される。
+.SS 文字定数
+ASCII と UTF\-8 の両方で正しくレンダリングされるシングルクォート (一重引用符)
+を生成するには、マニュアルページの原文では以下の表記を使うこと。
\e(aqC\e(aq
-where \fIC\fP is the quoted character. This guideline applies also to
-character constants used in code examples.
+ここで \fIC\fP が括弧で囲まれる文字である。このガイドラインはサンプルコードの場合にも適用される。
.SS サンプルプログラムとシェルのセッション
マニュアルページには、システムコールやライブラリ関数の使い方を示す サンプルプログラムを含めることができる。 その際には、以下の点に留意すべきである。
.IP * 3
サンプルプログラムは、K&R (Kernighan and Ritchie) スタイルで書き、 字下げはスペース 4文字で行う。 (ソースコードで
TAB 文字を使うのは避けること。)
.IP *
-For consistency, all example programs should terminate using either of:
+一貫性を保つため、すべてのサンプルプログラムは以下のいずれかで終了すること。
exit(EXIT_SUCCESS);
exit(EXIT_FAILURE);
-Avoid using the following forms to terminate a program:
+プログラムを終了するのに以下を使うのは避けること。
exit(0);
exit(1);
return n;
.IP *
-If there is extensive explanatory text before the program source code, mark
-off the source code with a susbsection heading \fIProgram source\fP, as in:
+プログラムソースの前に説明文がある場合は、\fIプログラムソース\fPの見出しをソースコードの前に付けること。
\&.SS プログラムのソース
-Always do this if the explanatory text includes a shell session log.
+説明文がシェルセッションのログを含む場合は必ずこのようにすること。
.PP
プログラムの使い方や他のシステムの特徴を示すためにシェルのセッションログを含める場合、
.IP * 3
OSDN Git Service
