Re: [Groff] Re: Bug#552201: groff-base: Japanese manpages are shown with too wide spaces

[Werner LEMBERG]

>> The only thing which I consider bad is that there is `(' at the
>> line end.  Can this be improved by adjusting the calls to .cflags?
>
> Hmm, I tried to add `(' to CJKpostpunct class, but it did not help.
>
>>        リストでは合計実行時間、呼び出し回 数、そのルーチン自身で消費した時間 (
>
> Groff adds a space between (non-punct) Japanese characters instead
> of breaking the line.  The expected result would be something like:
>
>>        リストでは合計実行時間、呼び出し回数、そのルーチン自身で消費した時間
>>        (...
>
> or:
>
>>        リストでは合計実行時間、呼び出し回数、そのルーチン自身で消費した時
>>        間 (...
>
> Perhaps assigning IGNORE_HCODE to whole CJK range is not perfectly
> enough to control the line breaking rule.

I should have activated my brain before asking such questions :-)

Here are my observations.

  . Attached you can find an improved version of the Japanese
    `gprof.1' man page (I'm calling it `gprofx.1' for convenience).
    Note the many backslashes at the end of lines to suppress unwanted
    spaces caused by newline characters.  Alternatively, it might be
    useful to have long lines to avoid linebreaks at all.  Most
    editors provide automatic line breaking anyways.

    In groff, there is nothing similar to a `CJK*' environment (as
    provided by my CJK package for LaTeX) to handle suppression of
    unwanted spaces automatically.  It would need more cflags trickery
    (with new values) to emulate this behaviour since groff doesn't
    know the concept of active characters.

  . Formatting the improved man page, you get a lot of warning
    messages like

      gprofx.1:45: warning [p 1, 2.2i]: cannot adjust line

    This gets much better if you ensure that the indented part of the
    main page (which is the majority of text) has an even number of
    characters so that the double-width CJK characters fit exactly.
    Try, for example, this:

      groff -Keuc-japan -Tutf8 -rIN=8n \
            -ww -man -mja gprofx.1 > gprofx.txt

    and the number of warnings decreases from 15 to only 4 (output
    attached).  I strongly suggest to add something like this to the
    Japanese locale configuration for man.

  . To get really rid of the warnings, and to improve formatting CJK
    stuff in general, we need inter-character glue between CJK
    characters.  Without that, groff produces too short lines (it then
    emits the `cannot adjust line' warning).  This is a TODO.

    An alternative is to add `.ad l' for Japanese manpages.

  . To come back to the abovementioned problem of `(' in the original
    output of `gprof.1', this isn't solvable at all with the current
    set of cflags: The problem is conflicting cflags values: The
    character right after the open parenthesis, `ミ', has value 66,
    which means

      lines can be broken before the character (regardless of the
      hcode values of the surrounding characters)

    What ever cflags value I set for `(', the value `66' of `ミ'
    inserts a breakpoint, causing a line break right before the
    character.

    I've now implemented three new cflags values, completely
    independent of hcode values:

      don't break before character but allow break after: 128
      don't break after character but allow break before: 256
      allow break before and after character:             512

    which are handled internally similar to kern pairs so that the new
    `inter_char_space_node'[1] sees the cflags values of both the left
    and right character to decide whether there should be a zero-width
    break inbetween.  I've also updated ja.tmac accordingly.

    Please test.


        Werner


[1] Contrary to its name, inter-character spacing isn't yet
    implemented.  As soon as it is, value 512 becomes `allow
    inter-character breaks and insert stretchable space'; this should
    eventually fix all line adjust warnings.

.\" Copyright (c) 1983, 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms are permitted provided
.\" that: (1) source distributions retain this entire copyright notice and
.\" comment, and (2) distributions including binaries display the following
.\" acknowledgement:  ``This product includes software developed by the
.\" University of California, Berkeley and its contributors'' in the
.\" documentation or other materials provided with the distribution and in
.\" all advertising materials mentioning features or use of this software.
.\" Neither the name of the University nor the names of its contributors may
.\" be used to endorse or promote products derived from this software without
.\" specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\"     @(#)gprof.1     6.6 (Berkeley) 7/24/90
.\"
.\" Japanese Version Copyright (c) 1997-2000 NAKANO Takeo all rights reserved.
.\" Translated Fri Jan 9 1998 by NAKANO Takeo <nakano@@apm.seikei.ac.jp>
.\" Updated Fri 27 Oct 2000 by NAKANO Takeo
.\"
.TH GPROF 1 "January 29, 1993"
.SH 名前
gprof \- コール・グラフ (call graph) のプロファイルを表示する
.SH 書式
.B gprof [ \-abcsz ] [ \-e|\-E
.I name
.B ] [ \-f|\-F
.I name
.B ]
.B [ \-k
.I fromname toname
.B ] [
.I objfile
.B [
.I gmon.out
.B ]
.B ]
.SH 説明
.B gprof
は C, Pascal, Fortran77 プログラムの実行プロファイルを生成する。呼び出\
されたルーチンの値は呼び出し元に取り込まれる。プロファイルのためのデー\
タはコール・グラフ (call graph: 関数コールの親子関係のグラフ) のプロファ\
イルデータファイル (デフォルトでは `gmon.out') から取り\
込まれる。このファイルは
.BR cc ( 1 ) 、
.BR pc ( 1 ) 、
.BR f77 ( 1 )
で
.B \-pg
オプションを指定してコンパイルされたプログラムによって作成される。
.B \-pg
オプションでは、リンクされるライブラリもプロファイル用にコンパイルされ\
たものになる。
.B gprof
は指定されたオブジェクトファイル (デフォルトは `a.out') からシンボ\
ルテーブルを読み、これと `gmon.out' のコール・グラフ・プロファイルとを\
関連付ける。\
複数のプロファイルデータファイルが指定された場合には、
.B gprof
はそれらのプロファイル情報をすべて合計して表示する。
.PP
.B gprof
はそれぞれのルーチンによって消費された時間を計算する。次にこれらの時間\
をコール・グラフの枝に沿って親ルーチンへと伝播させる。プログラムの\
サイクル (cycle: 再帰呼び出しの循環) をまとめ、サイクルへのコールを行っ\
たルーチンは、サイクルで消費した時間を共有するとみなす。最初のリストは\
関数で、消費時間の順にソートされている。\
消費時間にはコール・グラフでの子孫の分も含まれる。それぞれの関数エントリ\
の下には、その関数のコール・グラフでの (直接の) 子と、そこで消費された\
時間がどのように関数に伝播したかが表示される。同様の表示は関数の上にも\
表示されており、その関数とそれらの子孫で消費された時間がどのようにコー\
ル・グラフの (直接の) 親へ伝播するかが示される。
.PP
サイクルも表示される。サイクル全体としてのエントリ、そのサイクルに属す\
るメンバーのリストとそれぞれのメンバーによって消費された時間、その\
サイクルの呼び出し回数などが表示される。
.PP
次にフラットプロファイル
.RB ( prof (1)
の結果と似たもの) が与えられる。このリストでは合計実行時間、呼び出し回\
数、そのルーチン自身で消費した時間 (ミリ秒単位)、子孫の分も含めて消費\
した時間 (ミリ秒単位) が表示される。
.PP
最後に関数名の索引が与えられる。
.SH オプション
以下のオプションが指定できる:
.TP
.B \-a
スタティックに宣言された関数を表示しない。このオプションが指定され\
ると、スタティックな関数に関する全ての情報 (実行時間、他の関数の呼び出\
し、他の関数から呼び出される関係など) は、ファイル `objfile' 中でこの\
スタティックな関数の直前にロードされた関数に属することになる。
.TP
.B \-b
プロファイルのそれぞれのフィールドに関する説明を表示しない。
.TP
.B \-c
プログラムのスタティックなコール・グラフを、オブジェクトファイルのテキ\
ストセグメントを調べるという発見的 (heuristic) な手法で作成する。ス\
タティック・コールだけの親や子の呼び出し回数は 0 として表示する。
.TP
.BI "\-e " name
ルーチン
.I name
と、その子孫すべてに関するグラフプロファイルのエントリを表示しない
(子孫に関しては、別の祖先がいれば表示される)。
.B \-e
オプションは複数回指定できる。一つの
.B \-e
オプションについて指定できる
.I name
は一つだけである。
.TP
.BI "\-E " name
.B \-e
と同様にルーチン
.I name
とその子孫に関するグラフプロファイルのエントリを表示しない。また
.I name
(とその子孫) によって消費された時間も、プログラム実行の総時間 (および\
パーセンテージの計算) から除かれる。例えば
.BI "\-E " mcount
.BI "\-E " mcleanup
はデフォルトになっている。
.TP
.BI "\-f " name
ルーチン
.I name
とその子孫に関してのみ、グラフプロファイルのエントリを表示する。
.B \-f
オプションは複数回指定できる。一つの
.B \-f
オプションについて指定できる
.I name
は一つだけである。
.TP
.BI "\-F " name
.B \-f
と同様に、ルーチン
.I name
とその子孫に関してのみ、グラフプロファイルのエントリを表示する。またこ\
れらによって用いられた時間だけを合計の実行時間とパーセンテージの計算に\
用いる。
.B \-F
オプションは複数指定できる。一つの
.B \-F
オプションについて指定できる
.I name
は一つだけである。
.B \-F
オプションは
.B \-E
オプションによる設定を上書きする。
.TP
.BI "\-k " "fromname toname"
ルーチン
.I fromname
からルーチン
.I toname
までの枝を削除する。これは不要なサイクルの循環を破壊するのに便利である。
.B \-k
は複数指定できる。一つの
.B \-k
オプションに対して指定できるのは一組のルーチン名だけである。
.TP
.B \-s
プロファイルファイル `gmon.sum' を作成し、指定したプロファイルファイル\
の情報すべてからのプロファイル情報を総計したものを書き込む。この合計プ\
ロファイルファイルは後に gprof を (おそらくは
.B \-s
と共に) 実行する際に与えて、 `objfile' ファイルを複数回実行して得られ\
たプロファイルデータを累積するために用いることもできる。
.TP
.B \-v
gprof のバージョン番号を表示して終了する。
.TP
.B \-z
用いられなかった関数 (呼び出し回数と実行時間でわかる) も表示する。これ\
を
.B \-c
オプションと共に用いると、呼び出されなかったルーチンを見つけるのに役\
に立つ。
.PP
.SH ファイル
a.out       名前のリストとテキスト空間
.br
gmon.out    ダイナミックなコール・グラフとプロファイル
.br
gmon.sum    ダイナミックなコール・グラフとプロファイルのまとめ

.SH 関連項目
.BR monitor ( 3 ) ,
.BR profil ( 2 ) ,
.BR cc ( 1 ) ,
.BR prof ( 1 )
.sp
``An Execution Profiler for Modular Programs'',
by S. Graham, P. Kessler, M. McKusick;
.I
Software \- Practice and Experience,
Vol. 13, pp. 671-685, 1983.
.sp
``gprof: A Call Graph Execution Profiler'',
by S. Graham, P. Kessler, M. McKusick;
.I
Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
SIGPLAN Notices, Vol. 17, No  6, pp. 120-126, June 1982.

.SH 履歴
.B gprof
は 4.2 BSD から登場した。
.SH バグ
サンプリングの粒度 (granularity) も表示されるが、せいぜい統計的なもの\
でしかない。ここでは関数の一回あたりの実行時間は、関数の消費した合計時\
間を呼び出し回数で割ったものと仮定している。したがって、呼び出しグラフの\
枝を伝播して関数の親に伝わる時間は、枝を通過した回数に直に比例すること\
になる。
.PP
自分自身がプロファイルされていない親でも、子から伝播してくる時間を保有\
することになる。しかしこれらのルーチンは、呼び出しグラフの中で (どこか\
ら呼び出されたのでもなく) 勝手に起動するように見えるので、その時間はそ\
れ以上どこへも伝播しない。同様に、シグナルをキャッチしたルーチンは、プ\
ロファイルされていても勝手に起動するように見えてしまう (理由はもう少し\
複雑だが)。シグナルをキャッチしたルーチンの子がプロファイルされてい\
ればその時間を正しく伝播させることができるが、親ルーチンがプロファ\
イルルーチンの途中でシグナルがキャッチされた場合には全ての情報は失われる。
.PP
プロファイルされるプログラムは
.BR exit ( 2 )
をコールして終了するか、 main ルーチンからの return で終了しなければな\
らない。さもないと終了時にプロファイル情報が `gmon.out' ファイルにセー\
ブされない。

GPROF(1)                                                              GPROF(1)



名前
        gprof - コール・グラフ (call graph) のプロファイルを表示する

書式
        gprof  [ -abcsz ] [ -e|-E name ] [ -f|-F 
name ] [ -k fromname toname ]
        [ objfile [ gmon.out ] ]

説明
        gprof は  C,  Pascal,  Fortran77  プログラムの実行プロファイルを生成す
        る。呼び出されたルーチンの値は呼び出し元に取り込まれる。プロファイルの
        ためのデータはコール・グラフ (call  graph:  関数コールの親子関係のグラ
        フ)  のプロファイルデータファイル (デフォルトでは `gmon.out') から取り
        込まれる。このファイルは cc(1)、 pc(1)、 
f77(1) で -pg  オプションを指
        定してコンパイルされたプログラムによって作成される。  -pg オプションで
        は、リンクされるライブラリもプロファイル用にコンパイルされたものにな
        る。  gprof は指定されたオブジェクトファイル (デフォルトは `a.out') か
        らシンボルテーブルを読み、これと `gmon.out' のコール・グラフ・プロファ
        イルとを関連付ける。複数のプロファイルデータファイルが指定された場合に
        は、 gprof はそれらのプロファイル情報をすべて合計して表示する。

        gprof はそれぞれのルーチンによって消費された時間を計算する。次にこれら
        の時間をコール・グラフの枝に沿って親ルーチンへと伝播させる。プログラム
        のサイクル (cycle: 再帰呼び出しの循環)  をまとめ、サイクルへのコールを
        行ったルーチンは、サイクルで消費した時間を共有するとみなす。最初のリス
        トは関数で、消費時間の順にソートされている。消費時間にはコール・グラフ
        での子孫の分も含まれる。それぞれの関数エントリの下には、その関数のコー
        ル・グラフでの (直接の) 子と、そこで消費された時間がどのように関数に伝
        播したかが表示される。同様の表示は関数の上にも表示されており、その関数
        とそれらの子孫で消費された時間がどのようにコール・グラフの (直接の) 親
        へ伝播するかが示される。

        サイクルも表示される。サイクル全体としてのエントリ、そのサイクルに属す
        るメンバーのリストとそれぞれのメンバーによって消費された時間、そのサイ
        クルの呼び出し回数などが表示される。

        次にフラットプロファイル (prof(1) の結果と似たもの) が与えられる。この
        リストでは合計実行時間、呼び出し回数、そのルーチン自身で消費した時間
        (ミリ秒単位)、子孫の分も含めて消費した時間 (ミリ秒単位) が表示される。

        最後に関数名の索引が与えられる。

オプション
        以下のオプションが指定できる:

        -a      スタティックに宣言された関数を表示しない。このオプションが指定
                されると、スタティックな関数に関する全ての情報 (実行時間、他の
                関数の呼び出し、他の関数から呼び出される関係など) は、ファイル
                `objfile' 中でこのスタティックな関数の直前にロードされた関数に
                属することになる。

        -b      プロファイルのそれぞれのフィールドに関する説明を表示しない。

        -c      プログラムのスタティックなコール・グラフを、オブジェクトファイ
                ルのテキストセグメントを調べるという発見的 (heuristic)  な手法
                で作成する。スタティック・コールだけの親や子の呼び出し回数は 0
                として表示する。

        -e name ルーチン name と、その子孫すべてに関するグラフプロファイルのエ
                ントリを表示しない   (子孫に関しては、別の祖先がいれば表示され
                る)。 -e オプションは複数回指定できる。一つの -e  オプションに
                ついて指定できる name は一つだけである。

        -E name -e  と同様にルーチン name 
とその子孫に関するグラフプロファイル
                のエントリを表示しない。また name (とその子孫)  によって消費さ
                れた時間も、プログラム実行の総時間   (およびパーセンテージの計
                算) から除かれる。例えば -E mcount -E 
mcleanup  はデフォルトに
                なっている。

        -f name ルーチン name とその子孫に関してのみ、グラフプロファイルのエン
                トリを表示する。 -f オプションは複数回指定できる。一つの -f オ
                プションについて指定できる name は一つだけである。

        -F name -f  と同様に、ルーチン name 
とその子孫に関してのみ、グラフプロ
                ファイルのエントリを表示する。またこれらによって用いられた時間
                だけを合計の実行時間とパーセンテージの計算に用いる。  -F  オプ
                ションは複数指定できる。一つの -F オプションについて指定できる
                name  は一つだけである。 -F オプションは -E 
オプションによる設
                定を上書きする。

        -k fromname toname
                ルーチン fromname からルーチン toname までの枝を削除する。これ
                は不要なサイクルの循環を破壊するのに便利である。 -k は複数指定
                できる。一つの -k オプションに対して指定できるのは一組のルーチ
                ン名だけである。

        -s      プロファイルファイル `gmon.sum' を作成し、指定したプロファイル
                ファイルの情報すべてからのプロファイル情報を総計したものを書き
                込む。この合計プロファイルファイルは後に  gprof を (おそらくは
                -s と共に) 実行する際に与えて、 `objfile' ファイルを複数回実行
                して得られたプロファイルデータを累積するために用いることもでき
                る。

        -v      gprof のバージョン番号を表示して終了する。

        -z      用いられなかった関数 (呼び出し回数と実行時間でわかる) も表示す
                る。これを -c オプションと共に用いると、呼び出されなかったルー
                チンを見つけるのに役に立つ。

ファイル
        a.out       名前のリストとテキスト空間
        gmon.out    ダイナミックなコール・グラフとプロファイル
        gmon.sum    ダイナミックなコール・グラフとプロファイルのまとめ


関連項目
        monitor(3), profil(2), 
cc(1), prof(1)

        ``An Execution Profiler for  Modular  Programs'',  by  S.  Graham,  P.
        Kessler, M. McKusick; Software - Practice 
and Experience, Vol. 13, pp.
        671-685, 1983.

        ``gprof: A Call Graph Execution Profiler'', by S. Graham, P.  Kessler,
        M. McKusick; Proceedings of the 
SIGPLAN '82 Symposium on Compiler 
Con‐
        struction, SIGPLAN Notices, Vol. 17, No  6, pp. 120-126, June 
1982.


履歴
        gprof は 4.2 BSD から登場した。

バグ
        サンプリングの粒度 (granularity)  も表示されるが、せいぜい統計的なもの
        でしかない。ここでは関数の一回あたりの実行時間は、関数の消費した合計時
        間を呼び出し回数で割ったものと仮定している。したがって、呼び出しグラフ
        の枝を伝播して関数の親に伝わる時間は、枝を通過した回数に直に比例するこ
        とになる。

        自分自身がプロファイルされていない親でも、子から伝播してくる時間を保有
        することになる。しかしこれらのルーチンは、呼び出しグラフの中で (どこか
        ら呼び出されたのでもなく) 勝手に起動するように見えるので、その時間はそ
        れ以上どこへも伝播しない。同様に、シグナルをキャッチしたルーチンは、プ
        ロファイルされていても勝手に起動するように見えてしまう (理由はもう少し
        複雑だが)。シグナルをキャッチしたルーチンの子がプロファイルされていれ
        ばその時間を正しく伝播させることができるが、親ルーチンがプロファイル
        ルーチンの途中でシグナルがキャッチされた場合には全ての情報は失われる。

        プロファイルされるプログラムは  exit(2)  をコールして終了するか、 main
        ルーチンからの return で終了しなければならない。さもないと終了時にプロ
        ファイル情報が `gmon.out' ファイルにセーブされない。



                               January 29, 1993                       GPROF(1)