7. JPMANマニュアル校正ガイドライン

このページは、jpman ML に流れた以下の記事 [jpman,00904] とそれに関する ML 内での議論を元にしています。
Message-Id: < 199701231040.TAA26026@isrdgw.isrd.hitachi.co.jp>


  1. 原文中に発見した誤りへの対処
  2. 訳者注を加えるべきか否か
  3. 原文に無い記述追加(訳注も含む)の扱い
  4. 章のタイトル
  5. 書式
  6. 術語の統一
  7. roff マクロのチェック [必須]
  8. 日本語 roff を通して確認[望ましい]
  9. いわゆる全角文字と半角文字の間に半角スペースを入れるかどうか?
  10. 訳語の統一[望ましい]

  1. 原文中に発見した誤りへの対処

    jpman ML 内で誤りであることを確認して send-pr する(カテゴリdocs)。

  2. 訳者注を加えるべきか否か

    原文中に発見した誤りが誤りであると 確認された場合のみ注を加えても良い。

    注を加える場合、日本語マニュアル本文に現れる(=jman 実行時に画面表示 される)部分には

        (訳注).....
    
    という形式で書く。コメントに訳注を加えた人のメールアドレス、対象OS バージョンを必ず記述する。また、必要に応じて訳注を加えた事情などにつ いて記述する。コメントは例えば以下の形式で記述する。
          .\" 上記(訳注)は....の理由により追加しました
          .\" 2.2-RELEASE 対象
          .\" By who@anywhere.or.jp (Jan 1 1997)
    
    これは後にマニュアルをチェックする人が訳注を加えた人に問い合わせを行 う時の便宜をはかるためである。

  3. 原文に無い記述追加(訳注も含む)の扱い

    以下の要件を満たす場合、残す。

    1. 訳注の場合、マニュアルに記述されている OS バージョンと、現在対象 としている OS バージョンが一致し、 訳注を載せることに意義が有る場合。
    2. 訳注でない場合、 以下の要件を共に満たした場合、残す。
      1. 正しいことを確認できている ことが必要。
        担当者が確認を行うか、マニュアルに連絡先が記載されている場合に はその人に連絡し再確認してもらう。
        (後に日本語マニュアルの対象リリースバージョンが上がった場合に再 確認を要請される場合が有ります。例えば後のリリースバージョンで 記述が追加されることが分かっている場合には、追加記述を残すのは 良い考えかも知れません。マニュアルに記載された連絡先に連絡でき ない場合には、動作確認出来ないときおよび後々まで動作確認をする つもりが無いときには記述を削除して下さい。)
      2. 載せることに意義がある。
        マニュアルの分量が増えるデメリットに対して、 メリットの方が大きい。デメリットとは、チェックの手間のこと だけではなく、マニュアルを手にするエンドユーザが読まなければな らないマニュアルの分量が増えることを意味する。
    追加されていた記述を残す場合、前記訳注の記述方法に従うようにすること。

  4. 章のタイトル

    複数の日本語が記述してあるものは、一番最初に書いてあるものを使用する。

    英語			日本語
    ACKNOWLEDGEMENTS	謝辞
    AUTHOR(S)		作者
    AVAILABILITY		入手性
    BUGS			バグ
    CAVEATS			警告
    COMMANDS		コマンド
    COMPATIBILITY		互換性
    COPYING			COPYING
    COPYRIGHT		COPYRIGHT
    COPYING PERMISSIONS	COPYING PERMISSIONS
    DESCRIPTION		解説
    DIAGNOSTICS		診断
    ENVIRONMENT		環境変数
    ERRORS			エラー
    EXAMPLE(S)		使用例、実行例
    FEATURES		特徴
    FILES			関連ファイル
    HISTORY			歴史
    IDENTIFICATION		作者
    NAME			名称
    NOTES			注釈
    OPTIONS			オプション
    SEE ALSO		関連項目
    STANDARDS		規格
    SYNOPSIS		書式
    USAGE			使用法
    WARNING			警告
    
    [section 4 用]
    英語			日本語
    BLOCKING MODES		ブロッキングモード
    CONFIGURATION		設定
    DRIVER CONFIGURATION	ドライバの設定
    KERNEL CONFIGURATION	カーネルの設定
    FILE MARK HANDLING	ファイルマークの扱い
    FreeBSD SYNOPSIS	FreeBSD での書式
    NetBSD SYNOPSIS		NetBSD での書式
    INTERFACES		インタフェース
    IOCTLS			IOCTL
    KERNEL OPTIONS		カーネルのオプション
    MIB VARIABLES		MIB の変数
    MOUNT SESSIONS		マウントセッション
    NUMBERING		番号
    PARTITIONING		パーティション
    SUPPORTED CARDS		サポートされているカード
    

  5. 書式

  6. 術語の統一

    迷った場合には多い方の用例にあわせる[望ましい]

  7. roff マクロのチェック [必須]

    1. grep '^.Nm [A-Z]' によるチェック
      .Nm などによるコマンド名が文頭に来る場合、英語ならば最初の 1 文字を 大文字にしますが、日本語は普通そうはしません。で、この小文字にし忘 れをチェックするには
            grep '^.Nm [A-Z]'
      が有効です。
    2. grep '^ ' によるチェック
      roff は、行頭に空白があると、そこでまず改行してしまいます。これを 知らずにゴミとして行頭に空白を残してしまうと、そこで不要な改行が出 てしまいます。
    3. grep '^The' および '^If' によるチェック
      英語版をまず最初にコピーし、それを直接書きかえて 日本語版を作成しているような場合、文頭の The や If を 残してしまうことが多々あります。
    4. 間違ったコマンドによる欠落
      例えば、stty.1 の
            .DV CR-NL
            .Dv CR-NL
      です。このような間違いの場合、その部分がまるまる欠落してしまいます。
      特に、mdoc 系のコマンドを使っているのに古い man 系のコマンドを利用 してしまっているというオリジナルバグを発見するためには
            grep '^\.[A-Z][A-Z]'
      を行い、少ししかマッチしないファイルは、mdoc を利用しているにも関 わらず旧 man マクロを指定してしまっている可能性が大です。
    5. 文末の .
      英語の文末には "." がつきますが、文末が roff コマンドの場合にはそ のコマンドで一緒に "." を書きます。ここでそれを日本語にした時に、 そのコマンドが文末から文中に移動になったためにその "." は削除しな ければなりません。これを調べるためには:
            grep '^\.[A-Z].*\.$'
      を行って、ひとつひとつ調べるのがよいでしょう。
    6. 行頭の '
      行頭の ' は roff ではマクロとして扱われてしまいますので、不用意に行頭に ' を書くとその行全体が不正なマクロとして扱われ、表示されなくなります。 これを調べるためには:
            grep ^\'
      または
            grep ^\'\[^\'\]
      をおこなうとよいでしょう。

  8. 日本語 roff を通して確認[望ましい]

    jman や jgroff で cat 形式ファイルを作成し、全体を一覧して意図通りで あることを確認する。

  9. いわゆる全角文字と半角文字の間に半角スペースを入れるかどうか?

    半角スペースを入れる [望ましい]
    とするべき。
    ただし、句読点の直後が半角文字の場合、その直前には空白は不要。

  10. 訳語の統一[望ましい]

    対訳表に照らし合わせて、共通な訳語を用いる ことが望ましいが、状況に応じて適宜異なる訳語を使わなくてはならない場合 もあり得る。


← 6. 成果物の提供  ↑トップページ  対訳表 →
最終更新日 $Date: 1999/03/27 16:19:15 $
Copyright (C) 1997 Jpman Project. All Rights Reserved.
連絡先: manjpadm@jp.freebsd.org