Provided by: manpages-ja_0.5.0.0.20221215+dfsg-1_all bug

名前

       man - man ページを整形するマクロ

書式

       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title

説明

       このマニュアルページでは、  groff an.tmac のマクロパッケージ (man マクロパッケージとも呼ば
       れることも多い) について説明する。 このマクロパッケージは、 Linux の man  ページを書いたり
       移植したりするときに、 開発者が用いるものである。 このマクロパッケージはバージョン間での互
       換性が高く、 man page の移植にあたっては大きな問題はないだろう (但し、NET-2 BSD release は
       例外である。    こちらでは   mdoc   と呼ばれる全く異なるマクロパッケージが使用されている。
       mdoc(7)  を参照)。

       NET-2 BSD の man ページも、 groff のオプションとして -man の代わりに -mdoc  を指定するだけ
       で、利用することができる。  -mandoc オプションを使えばどのマクロパッケージが用いられている
       か 自動的に検出できるので、このオプションを使うのがお薦めである。

       Linux   man-pages   プロジェクトのマニュアルページを書く際に    従うべき決まり事については
       man-pages(7)  を参照。

   タイトル行
       man ページの (コメント行を除く) 最初のコマンドは、 以下のようにする必要がある。 コメント行
       とは .\" で始まる行のことである。

              .TH title section date source manual

       TH に渡す引数の詳細については man-pages(7)  を参照。

       なお BSD の mdoc フォーマットのページは TH コマンドではなく Dd コマンドから始まる。

   セクション
       セクションは .SH で始まり、見出し名がそれに続く。

       NAME (名前) という見出しだけは必ず置かないといけない。  この見出しは一番最初のセクションに
       すべきで、見出しの 次の行にはプログラムの説明を一行で書く。

              .SH NAME
              item \- description

       このフォーマットに従い、コマンド名に続くシングルダッシュ (-) の前には必ず バックスラッシュ
       を置くこと。 この文法は、 mabdb(8) プログラムが whatis(1) や apropos(1) コマンド用の短い説
       明のデータベースを 生成する際に利用される。

       マニュアルページに登場する可能性のあるこれ以外のセクションのリストに ついては man-pages(7)
       を参照。

   フォント
       タイプフェイスを選択するコマンドは以下のように指定する:

       .B  ボールド。

       .BI ボールドとイタリックとを交互に (特に関数指定に便利)。

       .BR ボールドとローマンとを交互に (特に他のマニュアルページを参照するときに便利)。

       .I  イタリック。

       .IB イタリックとボールドとを交互に。

       .IR イタリックとローマンとを交互に。

       .RB ローマンとボールドとを交互に。

       .RI ローマンとイタリックとを交互に。

       .SB スモールとボールドを交互に。

       .SM スモール (頭字語などに用いる)

       Traditionally, each command can have up to  six  arguments,  but  the  GNU  implementation
       removes  this  limitation  (you  might  still  want  to  limit yourself to 6 arguments for
       portability's sake).  Arguments are delimited by spaces.  Double quotes  can  be  used  to
       specify  an  argument which contains spaces.  For the macros that produce alternating type
       faces, the arguments will be printed next to each other  without  intervening  spaces,  so
       that  the  .BR  command  can  be  used  to  specify  a  word in bold followed by a mark of
       punctuation in Roman.  If no arguments are given, the command is applied to the  following
       line of text.

   その他のマクロや文字列
       Below  are  other  relevant  macros  and  predefined strings.  Unless noted otherwise, all
       macros cause a break (end the current line of text).  Many of these macros set or use  the
       "prevailing  indent." The "prevailing indent" value is set by any macro with the parameter
       i below; macros may omit i in which case the current prevailing indent will be used.  As a
       result,  successive  indented  paragraphs can use the same indent without respecifying the
       indent value.  A normal (nonindented) paragraph resets the prevailing indent value to  its
       default value (0.5 inches).  By default, a given indent is measured in ens; try to use ens
       or ems as units for indents, since these will automatically adjust to font  size  changes.
       The other key macro definitions are:

   通常の段落
       .LP      .PP と同じ (新たな段落の開始)。

       .P       .PP と同じ (新たな段落の開始)。

       .PP      新しい段落を開始し、インデントをリセットする。

   相対マージンインデント
       .RS i    相対マージンインデント  (relative margin indent) を開始する。 左マージンを i だけ
                右に移動する (i が省略されると優先インデントの値が用いられる)。  新たな優先インデ
                ントは 0.5 インチにセットされる。 結果として、以下の段落は対応する .RE が現れるま
                でインデントされる。

       .RE      相対マージンインデントを終了し、 優先インデントの値を元に戻す。

   段落をインデントするマクロ
       .HP i    ぶらさがりインデントの段落を開始する    (段落の先頭行は通常の段落の左マージンとな
                り、 段落の残りの行はインデントされる)。

       .IP x i  インデントされた段落。オプションとしてぶらさがりタグをとる。  タグ x が省略される
                と、以下の段落すべてが i でインデントされる。タグ x  が与えられると、タグはインデ
                ントされた段落の前にぶら下げられる  (.TP とちょうど同じ。ただしタグを次の行に書く
                代わりにコマンドに指定する)。  タグが長すぎる場合には、タグに続くテキストは次の行
                に移動する  (テキストが失われたり混ざったりすることはない)。 箇条書きをするには、
                \(bu (点) あるいは \(em (ダッシュ) をタグにしてこのマクロを用いるとよい。番号付き
                で箇条書きをする場合は、 数字または文字にピリオドを付けたものをタグにすればよい。
                こうすれば他のフォーマットへの変換が簡単になる。

       .TP i    ぶらさがりタグの段落を開始する。タグは次の行に指定する。 結果は .IP  コマンドと似
                たものになる。

   ハイパーテキストリンク用のマクロ
       .UR url
              Insert  a  hypertext  link to the URI (URL)  url, with all text up to the following
              .UE macro as the link text.

       .UE [ trailer ]
              Terminate the link text of the preceding .UR macro, with the optional  trailer  (if
              present,   usually   a  closing  parenthesis  and/or  end-of-sentence  punctuation)
              immediately following.  For non-HTML output devices (e.g., man  -Tutf8),  the  link
              text is followed by the URL in angle brackets; if there is no link text, the URL is
              printed as its own link text, surrounded by angle brackets.   (Angle  brackets  may
              not be available on all output devices.)  For the HTML output device, the link text
              is hyperlinked to the URL; if there is no link text, the URL is printed as its  own
              link text.

       These  macros  have been supported since GNU Troff 1.20 (2009-01-05) and Heirloom Doctools
       Troff since 160217 (2016-02-17).

   その他のマクロ
       .DT      タブをデフォルトのタブ値 (0.5 インチごと) にリセットする。 改行はしない。

       .PD d    パラグラフ間の間隔を引数にセットする (省略されると d=0.4v となる)。

       .SS t    サブヘッダー t (.SH のようなものだが、サブセクションのために用いる)。

   定義済みの文字列
       man パッケージには、以下のような定義済みの文字列がある:

       \*R    登録シンボル: ®

       \*S    デフォルトフォントサイズを変更する

       \*(Tm  商標シンボル: ™

       \*(lq  左に傾いたダブルクォート: “

       \*(rq  右に傾いたダブルクォート: ”

   安全なサブセット
       技術的には man は troff  のマクロパッケージだが、実際には多数の別のツールが  man  ページの
       ファイルを処理しており、それらは  troff  の全ての機能を 実装していないこともある。したがっ
       て、他のツールでも正しく処理できるように、 troff  のあまり一般的でない機能は、可能ならば用
       いないのが望ましい。  様々な troff プリプロセッサ も用いないほうが良いだろう (やむを得ない
       場合は tbl(1)  は用いても良い。しかし 2 列の表なら、代わりに IPTP コマンドを用いてみよ
       う)。  計算機能も用いない方が良いだろう。他のツールのほとんどはこれらを処理できない。 他の
       フォーマットに変換が容易な、単純なコマンドを使うようにしよう。   以下の   troff   コマンド
       は、使っても問題ないと考えてよいだろう (多くの場合、変換コマンドによって無視されるかもしれ
       ないが)。 \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne,  nf,  nh,
       ps, so, sp, ti, tr

       You may also use many troff escape sequences (those sequences beginning with \).  When you
       need to include the backslash character as normal text, use \e.  Other sequences  you  may
       use, where x or xx are any characters and N is any digit, include: \', \`, \-, \., \", \%,
       \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx.  Avoid using the escape  sequences  for
       drawing graphics.

       bp  (改頁) にはオプションパラメーターを用いないこと。 sp (垂直スペース) には正の値のみを用
       いること。 man や mdoc マクロパッケージにあるマクロと、 名前が同じで機能の異なるマクロを定
       義  (de)  しないこと。そのような再定義は無視される可能性が高い。 正方向へのインデント (in)
       には、負のインデントを対応させること (このマクロの代わりに RSRE マクロを使った方がよい
       のだが)。  条件テスト (if,ie)  は状態として 't' または 'n' だけを持つようにすること。 変換
       (tr)  には無視できるものだけを使うこと。 フォントの変更 (ft\f エスケープシーケンス) に
       は  1, 2, 3, 4, R, I, B, P, CW のみを用いること (ft コマンドの場合はパラメーターを指定しな
       くてもよい)。

       この制限を越えて機能を用いる場合は、いくつかのツールを使って、  その結果を注意してチェック
       すること。追加した機能が安全だと    確信したら、この文書の管理者にその安全なコマンドまたは
       シーケンスを 教えてほしい。リストに追加する。

ファイル

       /usr/share/groff/[*/]tmac/an.tmac
       /usr/man/whatis

注意

       By all means include full  URLs  (or  URIs)  in  the  text  itself;  some  tools  such  as
       man2html(1)   can  automatically  turn them into hypertext links.  You can also use the UR
       and UE macros to identify links to related information.  If you include URLs, use the full
       URL (e.g., ⟨http://www.kernel.org⟩) to ensure that tools can automatically find the URLs.

       Tools  processing  these  files  should  open the file and examine the first nonwhitespace
       character.  A period (.) or single quote (') at  the  beginning  of  a  line  indicates  a
       troff-based  file  (such  as  man  or  mdoc).   A  left  angle  bracket  (<)  indicates an
       SGML/XML-based file (such as HTML or Docbook).  Anything else suggests simple  ASCII  text
       (e.g., a "catman" result).

       Many man pages begin with '\" followed by a space and a list of characters, indicating how
       the page is to be preprocessed.   For  portability's  sake  to  non-troff  translators  we
       recommend  that  you  avoid  using  anything  other than tbl(1), and Linux can detect that
       automatically.  However, you might want to include this information so your man  page  can
       be handled by other (less capable) systems.  Here are the definitions of the preprocessors
       invoked by these characters:

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)

バグ

       mdoc や DocBook に比べると、 マクロの多くは書式 (フォントタイプやスペーシングなど)  に関す
       るものであり、  意味上のもの (このテキストは他のページへの参照である、など) ではない (HTML
       ですら意味的なマーキングに思える)。  このため、  man  フォーマットを他のメディアへ変換した
       り、 フォーマットを他のメディアで有効なものにしたり、 相互参照を自動的に挿入したりすること
       が困難になっている。 上に挙げたような安全なサブセットを守れば、 将来別のリファレンスページ
       フォーマットへ変換する作業が簡単になるだろう。

       Sun のマクロである TX は定義されていない。

関連項目

       apropos(1),   groff(1),   lexgrog(1),   man(1),   man2html(1),   whatis(1),  groff_man(7),
       groff_www(7), man-pages(7), mdoc(7)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
       説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。