mdnconv specification

# mdnconv

## 概要

## Overview

mdnconv はネームサーバの設定ファイル `named.conf` や ゾーンマスタファイルのためのコードセット (エンコーディング) 変換ツールです。

mdnconv is a code set (encoding) conversion tool for the `named.conf` configuration or zone master files used with name servers.

mdnconv は引数で指定されたファイル、あるいは標準入力から テキストを入力し、オプションで指定されたコードセット変換および正規化を 実行し、結果を標準出力に書き出します。

mdnconv receives the file specified by an argument or text entered using the keyboard, executes the code set conversion and normalization specified by the option, and writes the result in standard output.

具体的な使い方に関しては利用者ガイドの `named.conf`、 ゾーンマスタファイルの作成の項をご覧ください。

For detailed information about usage, refer to `named.conf`, Creating a Zone Master File in the User's Guide.

## 起動

## Startup

>     % mdnconv [オプション...]  [ファイル...]

>     % mdnconv [Option...]  [File...]

## オプション

## Option

-in in-code
  入力テキストのコードセット名 in-code を指定します。 in-code に指定できるコードセット名は、次のいずれかです。
  Specifies the code set name in-code of input text. The following code set names can be specified in in-code.
  - iconv_open() が受け付けるコードセット名
  - Code set name accepted by iconv_open()
  - `UTF-5`
  - `RACE`
  - `BRACE`
  - `LACE`
  - 上記のコードセット名の別名 (-alias オプション参照)
  - Alias of above code set names (refer to the -alias option)

  指定しなかった場合には現在のロケールからデフォルトのコードセットを 求めます。

  When not specified, the default code set is obtained from the current locale.

-out out-code
  出力テキストのコードセット名 out-code を指定します。 out-code に指定できるコードセット名は -in オプションの in-code と同じです。
  Specifies the code set name out-code of output text. Code set names that can be specified for out-code are the same as for in-code of the -in option.

  指定しなかった場合には クライアント設定ファイルの サーバエンコーディングエントリ に設定されているコードセットが使用されます。
  When not specified, the code set specified in server encoding entry of the client configuration file is used.

-normalize scheme
  正規化の方式を指定します。schemeに指定できる方式は 次のいずれかです。
  Specifies the normalization method. The following methods can be specified for scheme.
  - ascii-uppercase
  - ascii-lowercase
  - unicode-uppercase
  - unicode-lowercase
  - unicode-form-c
  - unicode-form-kc
  - ja-kana-fullwidth
  - ja-alnum-halfwidth
  - ja-compose-voiced-sound
  - ja-minus-hack
  - ja-delimiter-hack
  個々の正規化方式については MDN ライブラリの normalizer モジュールをご覧ください。

  For individual normalization methods, refer to the normalizer module of the MDN library.

  このオプションは複数指定することが可能です。複数指定した場合には、 指定した順に正規化が行われます。

  With this option, more than one method can be specified. When multiple methods are specified, normalization takes place in the order of the specification.

  このオプションを指定しなかった場合には クライアント設定ファイルの 正規化エントリに 指定されている正規化方式が使用されます。

  When this option is not specifed, the normalization method specified in normalization entry of the client configuration file is used.

-zld ZLD
  使用する ZLD を指定します。変換されるドメイン名が ピリオドで終わる FQDN で、かつ最後が ZLD と 一致した場合には、一致した部分は変換対象から外されます。 これは UTF-5 など一部の ASCII互換エンコーディングにおいて、ZLD 部分が 変換されないようにするためにするために必要な処理です。
  Specifies ZLD. When the domain name to be converted is FQDN that ends with a period and also the last character matches with ZLD, the matched part will not be converted. This processing is necessary so that the ZLD part is not converted in some ASCII-compatible encoding schemes such as UTF-5.

  このオプションを指定しなかった場合には クライアント設定ファイルの サーバ ZLD エントリに 指定されている値が使用されます。

  When this option is not specified, the value specified in the server ZLD entry of the client configuration file is used.

-auto
  -zld オプションと組み合わせて使用します。 もし変換対象である、非ASCII文字を含むドメイン名の最後が ピリオドで終わっていた場合に、-zld オプションで指定した ZLD がそのあとに自動的に付加されます。 これによってゾーンマスタファイル等に ZLD を明示的に書く必要が 少なくなりますが、この補完機能は完全ではないので、明示的に ZLD を 書かなければならない場合もあります。一般的にはこの機能に 頼らない方がよいでしょう。
  Used in combination with the -zld option. When a domain name is converted that includes non-ASCII characters and ends with a period, ZLD specified by -zld option is automatically added after the period. This reduces the need to explicitly write ZLD for zone master files, etc. However, because this is not a perfect complementary function, ZLD sometimes need to be explicitly written. In general, it is recommended that you do not rely on this function.

-whole
  正規化とターゲットコードセットへの変換を 入力されたテキスト全体に対して行います。このオプションを指定しなければ 非ASCII文字を含むドメイン名だと判断された部分のみが変換対象と なります。詳細は変換処理の詳細をご覧ください。
  Normalization and conversion to the target code set are applied to the entire entered text. When this option is not specified, only the part where it is determined that the domain name includes non-ASCII characters is the subject of conversion. For details, see Details of Conversion Processing.

-alias path
  コードセット名の別名を定義したファイル path を指定します。 このファイルはテキストファイル形式で、1行に一組ずつ コードセット名の別名と正式名とを一つ以上のスペースで区切って書いた ものです。例えば次の例は `Shift_JIS` と `EUC-JP` の 別名としてそれぞれ `sjis`、`euc-jp` を定義するものです。
  Specifies the file path that defines the alias name of the code set name. This file is a text file and in each line, one set of the alias name and formal name of the code set is written with one or more spaces as a delimiter. For example, the following examples `Shift_JIS` and `EUC-JP` define `sjis` and `euc-jp` as the alias.

  >     # "#" で始まる行はコメント
  >     sjis		Shift_JIS
  >     euc-jp		EUC-JP

  >     # Lines that begin with a "#" are comments
  >     sjis		Shift_JIS
  >     euc-jp		EUC-JP

-noconf
  クライアント設定ファイルを 読み込まないようにします。
  The client configuration file is not loaded.

-flush
  行ごとに出力をフラッシュします。mdnconv はファイルやパイプへの 出力の場合、通常は複数行のデータをまとめて書き出しますが、この オプションを指定すると1行ごとに変換結果を書き出します。 通常はこのオプションを指定する必要はありませんが、 mdnconv をフィルタプログラムとして他のプログラムから利用する場合などに 便利なことがあります。
  Flushes output for each line. When outputting to a pipe file, omdnconv usually writes data from a multiple number of lines in a single operation. By specifying this option, conversion result is written line by line. Usually, this option does not need to be specified but it may be useful when using mdnconv as a program to filter output from another program.

## 変換処理の詳細

## Details of Conversion Processing

mdnconv が行う変換処理をステップごとに記述します。

The steps performed during conversion processing by mdnconv are described below.

1. ファイルあるいは標準入力からテキストを1行読み込みます。
   Loads a file or one line of text entered with a keyboard.

2. 行末の改行コードを取り除きます。 これは -whole オプションをつけて mdnconv を実行し、かつ 出力エンコーディングが UTF-5 や RACE など ASCII 互換 エンコーディングの場合に、改行コードも UTF-5 や RACE で エンコードされてしまい、改行がなくなってしまうのを避けるためです。
   Removes the carriage return at the end of the line. This prevents the carriage return from dissapearing; this is needed because when mdnconv is executed with the -whole option set, and also when the output encoding is ASCII-compatible encoding such as UTF-5 or RACE, the carriage code will also be encoded using UTF-5 or RACEencoding.

3. 行を UTF-8 エンコーディングに変換します。変換には MDN ライブラリの converter モジュール を使用します。
   Converts the line to UTF-8 encoding. The converter module of the MDN library is used for conversion.

   通常は行全体を UTF-8 に変換しますが、入力コードセットが "RACE" の場合には、RACE エンコーディングを識別するプリフィックスを用いて RACE エンコードされた部分のみを取り出して UTF-8 に変換します。

   Usually, the entire line is converted to UTF-8. However, when the input code set is "RACE", a prefix that identifies RACE encoding is used to extract the RACE encoded part for conversion to UTF-8.

4. 変換結果が UTF-8 として正しいエンコーディングであるかをチェックします。 これには MDN ライブラリの utf8 モジュール を使用します。本来この処理は不要なはずですが、コード変換の実装に バグがあった場合に早い段階で検出できるよう、ここでチェックをするように してあります。
   Checks whether or not the conversion result is correctly encoded as UTF-8. The utf8 module of the MDN library is used for this operation. Basically, this processing is not necessary but checking is performed at this point so that if there is a bug in code conversion implementation, it can be detected at an early stage.

5. -whole オプションが指定されていれば次の処理対象の取り出しを飛ばし、 行全体を処理対象として 7. に飛びます。
   When the -whole option is specified, extraction of the processing target explained below is skipped and processing jumps to Step 7 because the entire line is the processing target.

6. UTF-8に変換された行の中から多言語ドメイン名の部分を取り出します。 これには MDN ライブラリの selectiveencode モジュール を使用します。取り出されるのは次のような部分文字列です。
   In a line that was converted to UTF-8, the multilingual domain name part is extracted. The MDN selectiveencode module of the MDN library is used for this step. The following partial text strings are extracted.
   - 1文字以上の非ASCII文字を含むこと。
     Text that includes one or more non-ASCII characters
   - 従来のドメイン名に許される文字 (アルファベット、数字、ハイフン)、 非ASCII文字、ピリオドだけから構成されていること
     Text that consists of only characters permitted for conventional domain names (alphabet, numbers, hyphens), non-ASCII characters, and periods.

   取り出された部分のみを以降の正規化等の処理対象とします。

   Only the extracted part is the processing target for the subsequent normalization and other processing.

7. 正規化を行います。 これには MDN ライブラリの normalizer モジュール を使用します。
   Normalization is performed. The normalizer module of the MDN library is used for this operation.

8. 再度変換結果が UTF-8 として正しいエンコーディングであるかをチェックします。 本来この処理は不要なはずですが、正規化の実装に バグがあった場合を考えてチェックを入れてあります。
   In this operation, a check is performed as to whether or not the conversion result is correctly encoded as UTF-8. In essence, this processing is not necessary but checking is performed here in consideration of the possibility of bugs in normalization.

9. 正規化された文字列の最後がピリオドで終わっており、かつ -zld オプションで指定された ZLD と文字列がマッチすれば、ZLD の部分を 次のコードセット変換の対象から外します。これは ZLD の部分まで (UTF-5 などに) 変換されてしまうのを防ぐためです。
   When the normalized text string ends with a period and also matches the ZLD specified using -zld option, the ZLD part will not be included in the next code set conversion target. This method is used to prevent conversion of the ZLD part (to UTF-5, etc).

10. UTF-8 エンコーディングから -out で指定された出力エンコーディングに 変換します。変換には MDN ライブラリの converter モジュール を使用します。
    Converts from UTF-8 encoding to the output encoding specified by -out. The converter module of the MDN library is used for this operation.

11. 出力エンコーディングに変換する前の文字列がピリオドで終わっており、 かつ -auto オプションが指定されていれば、文字列の後に ZLD を付加します。
    When a text ends with a period prior to converting to the output encoding, and also the -auto option is specified, ZLD will be added after the text string.

12. -whole オプションが指定されていた場合には変換された文字列をそのまま 標準出力に出力します。 指定されていなかった場合には、変換された文字列と 6. で処理対象と ならなかった部分とをマージしてからやはり標準出力に出力します。 どちらの場合も最後に改行コードを出力します。
    When the -whole option is specified, the converted text string is output in standard output. When the -whole option is not specified, the converted text string and the part that was excluded from conversion in Step 6 above are merged and then output in standard output. In both cases, the carriage return code is added at the end.

13. すべての入力行を処理し終われば終了します。そうでなければ 1. に 戻ります。
    The procedure ends when all input lines are processed. If not, the process returns to Step 1.