PIC(1)

名称
pic - troff と TeX で用いるピクチャコンパイラ

書式
pic [ -nvCSU ] [ filename ... ]
pic -t [ -cvzCSU ] [ filename ... ]

解説

本マニュアルでは、groff ドキュメントフォーマットシステムの一部である GNU バージョンの pic について記述します。 pic は、 troff か TeX の入力ファイルに埋め込まれたピクチャの記述を troff か TeX が解釈できるコマンドに変換します。 ピクチャは .PS で始まる行から開始され、 .PE で始まる行で終了します。 .PS と .PE に狭まれた領域以外は、変更せずに素通しします。

.PS と .PE マクロの適切な定義はユーザに任されています。使用している マクロパッケージが適当な定義を提供しない場合 (たとえば、古いバージョンの -ms マクロの場合)、 -mpic マクロから取り出すことができます。 -mpic マクロではピクチャ は中央寄せになります。

オプション
引数を伴わないオプションは - のあとにまとめて続けることができます。 特別なオプション -- は、オプションの最後を意味します。ファイル名のかわ りに用いられる - は、標準入力を意味します。

-C  .PS や .PE のあとに空白や改行以外の文字がきても、それを .PS や .PE であると解釈します。

-S  より安全なモード; sh コマンドを実行しません。 信用できない入力を処理する場合に便利です。 (デフォルトで有効です)

-U  安全でないモード; デフォルトオプション -S を打ち消します。

-n  groff の troff に対する独自拡張を用いません。後処理に独自拡張を解釈 できないものを用いるときに、このオプションを指定します。拡張については、 groff_out(5) に記述されています。 -n オプションはまた、troff モードにおいて、点を打つために pic が長さ 0 の直線を使わないようにします。

-t  TeX モードです。

-c  より tpic との互換性が高い処理を行います。本オプションは自動的に -t オプションも設定します。 \ で始まる行が透過的に出力されることがなくなり ます。 . で始まる行は先頭の . を \ に置き換えます。 .ps で始まる行は、特 別な扱いを受けます。すなわち、整数のオプションを続けることができ、それ は直線の太さ (ペンのサイズ) を 1000 分の 1 インチで示します。オプションが 省略された場合は、直 前の直線の太さに戻します。直線の太さの初期値は 1000 分の 8 インチです。 このように指定された直線の太さは、 thickness 属性、または、 linethick 変数によって負でない値が設定されていない場合にのみ有効です。

-v  バージョン番号を表示します。

-z  TeX モードにおいて、長さ 0 の直線を用いて点を描画します。

他のバージョンの pic でサポートされている以下のオプションは無視されます。

-D  すべての直線を \D エスケープシーケンスにより描画します。 pic は、つねに この動作を行います。

-T dev
    troff のデバイス dev のための出力を行います。 pic が troff に出 力する内容はデバイス非依存なので、本オプションは不要です。

使用法
本節では GNU pic とオリジナルバージョンの pic との違いのみを説明します。 これらの違いの多くは新しいバージョンの Unix pic にもあてはまります。 完全な文書は次のファイルにあります

    /usr/src/contrib/groff/doc/pic.ms

  TeX モード
TeX モードは -t オプションにて有効になります。 TeX モードでは、各ピクチャのために \graph から呼び出される vbox を、 pic は定義します。 vbox の名前を変えるには figname コマンドを使用してください。 例えば以下のようにして、自分自身で vbox を表示する必要が有ります。

    \centerline{\box\graph}

実際、vbox は高さが 0 ですから (これは \vtop で定義されています)、この表現ではピクチャの上の空間が ピクチャの下の空間よりも若干大きくなります。

    \centerline{\raise 1em\box\graph}

はこの問題を避けます。

vbox が正の高さおよび 0 の深さを持つようにするには (例えば LaTeX の graphics.sty が使うように)、次のマクロを文書中に定義します:

    \def\gpicbox#1{%
    \vbox{\unvbox\csname #1\endcsname\kern 0pt}}

そうすれば、\box\graph の代りに単に \gpicbox{graph} と書けます。

TeX ドライバで tpic スペシャルバージョン 2 をサポートするものを使用する必要が有ります。

\ で始まる行は透過的に通されます; 単一の % が行末に追加され、望まれない空白が出るのを防ぎます。 この機能を使用して、安全にフォントを変更したり \baselineskip の値を変更できます。 この方法以外で実行すると、望ましくない結果となるでしょう; 各自のリスクで実行して下さい。 ピリオドで始まる行は特別には扱われません。

  コマンド

for variable = expr1 to expr2 [by [*]expr3] do X body X
    variable を expr1 に設定します。 variable の値が expr2 以下の間、 body を実行して variable を expr3 だけ増加させます; もし by が指定されない場合、 variable の増分は 1 です。 もし expr3 の前に * が指定された場合、 variable には expr3 が掛けられます。 X は body に存在しない任意の文字を使用して構いません。

if expr then X if-true X [else Y if-false Y]
    expr を評価します; もし非 0 ならば、 if-true を実行します、 そうでないなら if-false を実行します。 X は if-true に存在しない任意の文字であり、 Y は if-false に存在しない任意の文字です。

print arg...
    引数を結合し、標準エラー出力に 1 行で出力します。 各 arg は式、位置、テキストのいずれかである必要が有ります。 デバッグに有効です。

command arg...
    引数を結合し、troff または TeX に 1 行として渡します。 各 arg は式、位置、テキストのいずれかである必要が有ります。 これは . や \ で始まる行と同様の効果が有りますが、 値や変数をそのまま通します。

sh X command X
    command をシェルに渡します。 X は command 中に存在しない任意の文字です。

copy "filename"
    filename をファイルのこの位置に埋め込みます。

copy ["filename"] thru X body X [until "word"]

copy ["filename"] thru macro [until "word"]
    この構造は body を filename の各行に対して 1 度づつ実行します。 行は空白で区切られた語に分割され、 body 中の $i ただし i は 1 から 9 までは、 行の i 番目の語に置換されます。 filename が指定されない場合、行は現在の行から .PE の行までが使用されます。 until 節が指定されると、 行の最初の語が word の行までが読み込まれます; その行は捨てられます。 X は body に含まれない任意の文字です。 例えば

        .PS
        copy thru % circle at ($1,$2) % until "END"
        1 2
        3 4
        5 6
        END
        box
        .PE

    は以下等価です。

        .PS
        circle at (1,2)
        circle at (3,4)
        circle at (5,6)
        box
        .PE

    各行に対して実行されるコマンドは、 thru の引数としてマクロ名を与えることで、 すでに定義されているマクロをとりえます。

reset

reset variable1[,] variable2 ...
    既定義の変数 variable1, variable2 ... をデフォルト値にリセットします。 引数が指定されない場合、すべての既定義の変数はデフォルト値にリセットされます。 また scale に値を定義すると、寸法を管理する全ての既定義の変数は、 それらのデフォルト値に新しい scale を掛けたものになります。

plot expr ["text"]
    これはテキストオブジェクトであり、 text をフォーマットとして expr を引数として sprintf を用いて構成します。 text が省略された場合にはフォーマット文字列 "%g" が使用されます。 通常のテキストオブジェクトと同様属性を指定できます。 適切なフォーマット文字列を指定するように非常に気を付ける必要が有ります; pic は文字列に関して非常に限られたチェックしか行いません。 この仕様は、 sprintf のことを考慮して批判されています。

variable := expr
    これは = と同じですが、 variable が既に定義されていなければならず、 現在のブロックに対してローカルな変数を作成せずに expr を variable へ代入します (これに対して = は、variable がまだ定義されていない場合には現在のブロックにおいて定義し、 現在のブロックに置いてのみ値を変更します。) 例えば

        .PS
        x = 3
        y = 3
        [
          x := 5
          y = 5
        ]
        print x " " y
        .PE

    は 5 3 を表示します。

    X anything X

という形式に対しては

    { anything }

も許されます。 この場合、 anything には { と } がバランスして登場する必要が有ります。 文字列に X が含まれる場合、 { と } のバランスが悪い場合に対応します。

  式
式の文法が少し拡張されました:

x ^ y (指数)
sin(x)
cos(x)
atan2(y, x)
log(x) (base 10)
exp(x) (base 10, ie 10^x)
sqrt(x)
int(x)
rand() (0 から 1 までの乱数を返す)
rand(x) (1 から x までの乱数を返す; 勧められません)
srand(x) (乱数の種を設定する)
max(e1, e2)
min(e1, e2)
!e
e1 && e2
e1 || e2
e1 == e2
e1 != e2
e1 >= e2
e1 > e2
e1 <= e2
e1 < e2
"str1" == "str2"
"str1" != "str2"

曖昧さを避けるために、 文字列の比較式はあるコンテキストにおいては括弧で括られる必要が有ります

  その他の変更
単なる式 expr は属性として受理可能です; これは dir expr と同じであり、 dir は現在の方向です。 例えば

    line 2i

は 2 インチの長さの線を現在の方向へ描きます。 文字 `i' (または `I') は無視されます。 他の計量単位を使用したい場合は、 scale 変数を適切な値に設定してください。

ピクチャの最大の幅と高さは変数 maxpswid, maxpsht により指定されます。 初期値は 8.5 および 11 です。

数を表すのに科学技術的表記が可能です。 例えば
    x = 5e-2

テキストの属性は組み合わせることが可能です。 例えば
    "foo" above ljust
は正しいです。

ブロックが検査される深さには制限は有りません。 例えば
    [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
    circle at last [].A.B.C
は受理可能です。

円弧はコンパスポイントを持ち、円弧が部分となるような円から決定されます。

円と円弧は点線や破線で書くことが出来ます。 TeX モードではスプラインを点線や破線で書くことが出来ます。

ボックスの角を丸くできます。 rad 属性は、角を構成する 1/4 円の半径を指定します。 rad, diam 属性が与えられない場合、 boxrad が半径として使用されます。 初期値では boxrad は値 0 です。 角の丸いボックスは点線や破線で書くことが出来ます。

.PS 行は 2 番目の引数としてピクチャの最大の高さを指定できます。 幅として 0 が指定された場合には、 ピクチャのスケーリングファクタの計算においては幅は無視されます。 GNU pic は常に水平方向と垂直方向ともに同じ縮尺で スケーリングしていることに注意して下さい。 これは 高さが指定された場合に水平方向と垂直方向を同じ縮尺でスケーリングしない DWB 2.0 pic と異なります。

テキストオブジェクトはそれぞれに関連づけられた見えないボックスを持っています。 テキストオブジェクトのコンパスポイントはこのボックスによって決定されます。 オブジェクトに関連づけられた暗示的な動きもこのボックスによって決定されます。 このボックスの寸法は width, height 属性から定まります; もし width 属性が与えられていない場合は幅は textwid となります; もし height 属性が与えられていない場合は高さは textht となります。 初期値では textwid, textht は値 0 です。

クォートされたテキストが使用される場合、

    sprintf("format", arg,...)

という形式の式を (ほとんどの場所で) 使用可能です; これは引数を format に従い整形したものを出力します。 format は printf(3) に記述されている文字列であり、 与えられる数及び引数に適切なものである必要が有ります。

オブジェクトを描画する時に使用する線の太さは linethick 変数で制御可能です。 これは線の太さをポイントで指定します。 負の値はデフォルトの太さを使用することを意味します: TeX 出力モードでは、8 ミリインチを使用することを意味します; TeX 出力モードで -c オプション使用時には、線の太さには .ps 行で指定されるものを使用することを意味します; troff 出力モードでは、ポイントサイズに比例する太さを使用することを意味します。 値 0 ではデバイスがサポートするもっとも細い線で描画します。 初期値は -1 です。 また、 thick[ness] 属性が有ります。 例えば

    circle thickness 1.5

は 1.5 ポイントの太さの円を描画します。 線の太さは scale 変数の値の影響も .PS 行における高さの影響も受けません。

ボックス (角の丸いボックスを含みます)、 円、楕円は塗りつぶすことが可能であり、 属性 fill[ed] で指定します。 これは値が 0 から 1 の式をオプションで引数として取ります; 0 は白で塗りつぶし、1 は黒で塗りつぶし、その間の値では 適切な灰色で塗りつぶします。 1 より大きい値も使用可能です: この場合、現在のテキスト及び線に使用している灰色で塗りつぶします。 通常これは黒ですが、出力デバイスが変更する機構を持っているかも知れません。 引数を取らない場合、 fillval 変数の値が使用されます。 初期値では 0.5 です。 invisible 属性はオブジェクトの塗りつぶしには影響しません。 塗りつぶされたオブジェクトに関連づけられたテキストは、 塗りつぶし後に追加されます。 このため、塗りつぶしによってテキストが隠されることは有りません。

3 個の追加修正子を使用して、色付きオブジェクトを指定可能です: outline[d] は外周の色を設定し、 shaded は色で塗りつぶし、 colo[u]r[ed] は両方を設定します。 これら 3 種のキーワードは、色を指定するサフィックスを期待します。 例えば次のようになります。

    circle shaded "green" outline "black"

現在のところ、TeX モードでは色サポートは使用できません。 groff で既定義の色の名前はデバイスマクロファイルにあり、例えば ps.tmac にあります。 追加の色は、 .defcolor リクエストで定義可能です (詳細は troff(1) マニュアルページを参照してください)。

TeX モードで vbox 名を変えるには、擬似変数 figname (これは実際には特別に構文解析されるコマンドです) をピクチャ中で設定します。 例:

    .PS
    figname = foobar;
    ...
    .PE

このピクチャは、ボックス \foobar 中で使用可能となります。

pic は、ピクチャの開始時に、 グリフと塗りつぶしの色がデフォルト値に設定されていることを仮定しています。

変数 arrowhead が非 0 でありかつ TeX モードが有効もしくは -x オプションが与えられている場合には、 矢印の頭を実線の三角形で描画します。 初期値では arrowhead は 1 です。

pic の troff 出力はデバイス独立です。 それゆえ -T オプションは冗長です。 全ての数値はインチとして扱われます; 数値は troff マシン単位としては解釈されません。

オブジェクトは aligned 属性を取りえます。 これは後処理が grops で実行される場合のみ機能します。 オブジェクトに関連づけられたテキストで aligned 属性を持つものは全て オブジェクトの中央において回転されます。 それゆえ、オブジェクトの始点から終点への方向にあわせられます。 この属性は始点と終点が同じオブジェクトに関しては効果が有りません。

nth と言う表現が許されている場所では `expr'th という表現も許されます。 'th は単一のトークンであることに注意して下さい: ' と th の間には空白を入れてはなりません。 使用例は以下です。

    for i = 1 to 4 do {
       line from `i'th box.nw to `i+1'th box.se
    }

変換
スタンドアロンのピクチャを pic ファイルから得るには、 pic コードを .PS と .PE のリクエストで囲みます。 roff 設定コマンドをファイルの先頭に追加しても良いですが、 roff テキストは追加しません。

ページ情報をなにも加えずに、このファイルを groff に喰わせることが必要です。 どの .PS と .PE のリクエストが実際に呼ばれたのかを確認してください。 例えば、mm マクロパッケージはページ番号を追加しますが、 これは非常に迷惑です。 当面、標準の groff を、どのマクロパッケージも働かないようにして呼び出します。 または、独自のリクエストを定義します。 例えば、なにもしないようにするには次のようにします:

    .de PS
    ..
    .de PE
    ..

groff 自身は、他のグラフィックスファイル書式への直接変換はできません。 しかし、 groff オプション -Tps の使用により、ピクチャを最初に PostScript® 書式へ変換すれば、 多くの可能性があります。 この ps ファイルは、BoundingBox 情報が無いので、 それ自身は非常に使用し易いというものではないので、 他の変換プログラム、通常は ps2other や pstoother といった名前のものに喰わせます。 さらに、PostScript インタプリタ ghostscript (gs) は、 次のオプションで呼び出し可能な組み込みのグラフィックス変換デバイスを持ちます:

    gs -sDEVICE=<devname>

使用可能なデバイス一覧を得るには、次のように呼び出します:
    gs --help

Encapsulated PostScript ファイル書式 EPS がより重要になっており、 また変換が過去のようには簡単ではないので、正しい仕事を行う ps2eps という名前の変換ツールの存在を知っていると良いでしょう。 これは、 gs にパッケージされているツール ps2epsi よりも良いものです。

ビットマップグラフィックス書式用には、 pstopnm を使用します。結果の (中間出力の) PNM ファイルは、 netpbm パッケージを使用することにより、 実質的に任意のグラフィックス書式に変換可能です。

関連ファイル
/usr/share/tmac/pic.tmac PS と PE マクロの定義の例です。

関連項目
troff(1), groff_out(5), tex(1), gs(1), ps2eps(1), pstopnm(1), ps2epsi(1), pnm(5)

Tpic: Pic for TeX
Brian W. Kernighan, PIC — A Graphics Language for Typesetting (User Manual). AT&T Bell Laboratories, Computing Science Technical Report No. 116 <http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz> (revised May, 1991).

ps2eps は CTAN ミラーで入手可能であり、例えば次のところから入手可能です:
<ftp://ftp.dante.de/tex-archive/support/ps2eps/>

W. Richard Stevens - Turning PIC Into HTML
<http://www.kohala.com/start/troff/pic2html.html>

W. Richard Stevens - Examples of picMacros
<http://www.kohala.com/start/troff/pic.examples.ps>

バグ
groff にとって不正な文字 (例えば ASCII code 0 や 8 進数で 013、015〜037、 0200〜0237) は TeX モードであっても拒否されます。

fillval の解釈は 10th edition Unix と互換性がありません。 10th edition Unix は 0 を黒、1 を白と解釈します。

PostScript® は、Adobe Systems Incorporation の登録商標です。