README

noi/parsedown-rubytext是Parsedown的一个用于插入平假名旁注的扩展。

以下包含以下扩展语法

1. \Noi\Parsedown\RubyTextTrait -- 内联卢比指定
2. \Noi\Parsedown\RubyTextDefinitionTrait -- 卢比定义（引用样式）
3. \Noi\Parsedown\AozoraRubyTextTrait -- 青空文库卢比格式（内联）
4. \Noi\Parsedown\PixivRubyTextTrait -- Pixiv卢比格式（内联）

还包含将上述1和2的trait组合在一起的实现类

• \Noi\ParsedownRubyText -- 从Parsedown派生
• \Noi\ParsedownExtraRubyText -- 从ParsedownExtra派生

以下主要说明1和2的扩展语法的用法。3的说明请参考README-Aozora.md，4的说明请参考README-Pixiv.md。

Markdown

内联卢比指定

1. [父文本]^(卢比)
2. [父文本]^（卢比） （使用全角括号）
3. [父文本]（卢比） （使用全角括号）

这会生成以下<ruby>标签

<ruby>親文字<rp>（</rp><rt>ルビ</rt><rp>）</rp></ruby>

此包除了上述格式外，还包含卢比语法扩展。请参阅青空文库卢比格式(README-Aozora.md)和Pixiv卢比格式(README-Pixiv.md)。

引用样式卢比定义

• **[父文本]: 卢比

使用上述格式在文档的某行中定义卢比。卢比定义行本身不会包含在转换后的HTML中，类似于Markdown的链接定义或MarkdownExtra的“缩写”。

已定义卢比的单词在卢比指定不存在的地方也会自动添加卢比（除了内联代码或代码块内）。

默认情况下，已定义卢比的单词在文档的所有出现位置都会添加卢比。也可以更改此行为，使其仅限于每个单词的第一次出现。

要将自动卢比添加设置为仅限于第一次出现，请执行以下方法

• setRubyTextDefinitionMarkupAll(false)

无论自动卢比添加设置如何，使用内联卢比明确指定卢比的文本将始终添加指定的卢比。

单字卢比分配

卢比可以通过分词将卢比分配给每个卢比对象的每个字符

• [日本語]^(に ほん ご) -- 卢比指定
• **[日本語]: に ほん ご -- 卢比定义

上述示例会生成以下<ruby>标签

<ruby>
  日<rp>（</rp><rt>に<rt><rp>）</rp>
  本<rp>（</rp><rt>ほん<rt><rp>）</rp>
  語<rp>（</rp><rt>ご<rt><rp>）</rp>
</ruby>
(実際の出力は1行)

属性值指定

卢比还可以添加属性值。请使用与Markdown Extra "Special Attributes"相同的格式 {...} 进行指定

• [日本語]^(にほんご){#id .classA .classB lang=ja}

上述示例会生成以下<ruby>标签

<ruby id="id" class="classA classB" lang="ja">日本語<rp>（</rp><rt>にほんご</rt><rp>）</rp></ruby>

自动将小写假名转换为平假名

在HTML转换时，也可以将包含卢比的小写假名（如撇号“ぁ”、“っ”等）自动转换为平假名。

此模式下，小写假名将自动转换为平假名

• [東京都]^(とうきょうと) => <ruby>東京都<rp>（</rp><rt>とうきようと</rt><rp>）</rp></ruby>
• [百科事典]^(ひゃっかじてん) => <ruby>百科事典<rp>（</rp><rt>ひやつかじてん</rt><rp>）</rp></ruby>

要更改自动转换模式，请执行以下方法

• setRubyTextSuteganaAllowed(false)

由于平假名以较小的字体大小显示，因此从可读性的角度来看，通常倾向于使用平假名。如果需要在较小的字体大小下显示或用于印刷目的，则使用自动转换模式会很有用。

默认情况下不进行自动转换。即使有小写假名也保持原样。

安装 - 安装方法

使用 Composer 执行以下操作。

$ php /path/to/composer.phar require noi/parsedown-rubytext "*"
$ php /path/to/composer.phar require erusev/parsedown-extra "*"

或者，在 composer.json 中包含以下行。

{
    "require": {
        "noi/parsedown-rubytext": "*",
        "erusev/parsedown-extra": "*"
    }
}

如果不使用MarkdownExtra，则不需要包含erusev/parsedown-extra的行。

如果未使用Composer进行包管理，则请在任何include_path中创建Noi/目录，并将lib/以下的所有文件放入其中。

使用 - 使用方法

方法1: 使用Noi\ParsedownRubyText / Noi\ParsedownExtraRubyText

这些类是各自将卢比用扩展组合到Parsedown和ParsedownExtra中的实现类。

除了派生类功能外，还可以使用卢比指定和卢比定义扩展语法。方法与Parsedown类相同。

$pd = new \Noi\ParsedownRubyText(); // or new \Noi\ParsedownExtraRubyText();
echo $pd->text('[日本語]^(にほんご)');

// Output:
<p><ruby>日本語<rp>（</rp><rt>にほんご</rt><rp>）</rp></ruby></p>

两个类都没有包含“青空文库卢比格式”和“Pixiv卢比格式”的扩展。在需要使用这些扩展语法时，需要参考方法2创建自己的派生类。

方法2: 在自定义的Parsedown派生类中引入卢比语法

如果您想在自定义的Parsedown派生类中引入卢比扩展，请按以下方式添加所需的trait

class YourParsedown extends Parsedown /* or ParsedownExtra or etc. */ {
    // 1. ルビ用エクステンションのtraitをuse
    use \Noi\Parsedown\RubyTextTrait;
    use \Noi\Parsedown\RubyTextDefinitionTrait;

    // 2. registerメソッドをコンストラクタかどこかで実行
    public function __construct()
    {
        parent::__construct(); // 必要に応じて

        $this->registerRubyTextExtension();
        $this->registerRubyTextDefinitionExtension();
    }
}

$pd = new YourParsedown();
echo $pd->text('[日本語]^(にほんご)');

// Output:
<p><ruby>日本語<rp>（</rp><rt>にほんご</rt><rp>）</rp></ruby></p>

添加trait时，除了使用use外，还需要执行**register**方法。很容易忘记，所以请注意！

PHP5.3之前的情况

由于PHP5.3之前不支持trait，因此不能直接使用。

请打开要组合的trait文件，复制内容创建一个类，或者升级PHP版本。

详细说明

• Markdown和转换结果的示例请参阅 tests/data/ 以下。
• 请检查各个类或trait文件的DocComment。

许可证

MIT许可证。在许可证限制范围内，您可以在商业和非商业用途中自由使用。

在MIT许可证下发布的代码 - 有关详细信息，请参阅LICENSE文件。