MediaWiki

Parsoid/ja

This page is a translated version of the page Parsoid and the translation is 40% complete.
Outdated translations are marked like this.
Languages:

Parsoid はウィキテキストとHTMLを変換するライブラリです。 Eventually, the goal is to fully replace MediaWiki’s current native Parser. The legacy parser will still be supported in MediaWiki 1.43 (LTS).

Parsoid
双方向のランタイム ウィキテキスト パーサー。 RDFa を用いて、ウィキテキストと HTML/XML DOM を相互変換します。
グループ: Content Transform Team
開始: 2011-10
チームのメンバー: Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Yiannis Giannelos
バックログ: #parsoid
リーダー: Subramanya Sastry
管理者: Sérgio Lopes
Artist's impression of the Parsoid HTML5 + RDFa wiki runtime
For the older version of Parsoid written in JavaScript (Node.js), see Parsoid/JS.

技術的な詳細

Parsoid は、MediaWiki のウィキテキスト構文と同等の HTML/RDFa 文書モデルを相互に変換できるアプリケーションです。この変換には、自動処理や豊富な編集機能の向上をサポートする機能が含まれています。

これは2012年からウィキメディア財団のチームによって開発が続けられています。 現在、VisualEditor とStructured discussions 、コンテンツ翻訳 、他のアプリケーションで広く使われています。

Parsoidは完全な変換、つまり情報の損失を防ぎ、「汚い差分」を無くす事を目的としています。

ウィキメディアのウィキでは現在、いくつかのアプリケーションのためにRESTBase のHTML変換をバックエンドで行っています。 予想されるところでは、RESTBase はより緊密に MediaWiki に統合されたキャッシュに最終的に置き換えられるでしょう。

プロジェクト全体の詳細については、2013年3月のブログの投稿を参照してください。 使用されているHTMLモデルについては、 MediaWiki DOM specを参照してください。

Parsoidは元々JavaScriptで書かれ、Node.jsを使用するWebサービスとして作られました。 2019年2月のテクニカルトーク (スライド)とブログ投稿ではPHPへ移植する工程を説明しています。 Parsoid拡張APIは現在開発中で、2020年8月のテクニカルトークでこの活動について説明しています。

GitHub リポジトリ： https://github.com/wikimedia/parsoid

使用法

インストール

MediaWiki 1.35 では Parsoid/PHP は標準で同梱されており、ビジュアルエディターにより自動的に読み込まれます。 MediaWiki 1.35 以降では、設定は必要ありません。

Parsoid exports an internal REST API which was historically used by RESTBase and not accessible outside the WMF internal cluster. This is no longer required for Visual Editor or core read views, and the internal API is being deprecated and is planned for removal in MW 1.43.

Parsoid is nominally a composer library used by mediawiki core. If you still require the internal API for some reason, you can explicitly load Parsoid "as an extension" by adding the following to LocalSettings.php: 

wfLoadExtension( 'Parsoid', "$IP/vendor/wikimedia/parsoid/extension.json" );

Any remaining third-party users of the internal Parsoid API are strongly encouraged to migrate to the core REST HTML page endpoint which provides equivalent functionality.

開発

開発はParsoid Git repositoryで行われます。 コードレビューはGerritで行われます。 アカウントのセットアップはGerrit/はじめにを参照してください。

仮想マシンでMediaWiki-Vagrant 開発環境を使用する場合は、ロールvisualeditorをそれに追加するだけでExtension:VisualEditor と共に動作するParsoidがセットアップされます。 (これはParsoid/PHPへの切り替えにより機能しなくなった可能性があります：T258940)

最新のParsoidはPHPで記述されており、Parsoid/PHPのインストールについては以下で説明されているものであることに注意してください。 MediaWiki 1.35 以降を実行している場合は、これを使用すべきです。 1.34以前のJavaScriptで記述されているParsoidについては、Parsoid/JSを参照してください。

Linking a developer checkout of Parsoid

MediaWiki の標準的なインストレーションでは、Parsoid は 2 つの方法でバンドルされています。一つは、MediaWiki の composer ライブラリ、wikimedia/parsoid です。

開発目的では通常、MediaWikiコアにcomposerライブラリとしてバンドルされたバージョンではなく、gitからチェックアウトしたバージョンを使用します。 The following lines added to LocalSettings.php allow use of a git checkout of Parsoid (optionally), load the Parsoid REST API with wfLoadExtension (rather than using the version bundled in VisualEditor) and manually do the Parsoid configuration which is usually done by VisualEditor: 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # bundled copy
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// For developers: ensure Parsoid is executed from $parsoidInstallDir,
// (not the version included in mediawiki-core by default)
// Must occur *before* wfLoadExtension()
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // Only intercept Parsoid namespace classes
        if ( preg_match( '/(MW|Wikimedia\\\\)Parsoid\\\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // AutoLoader::registerNamespaces was added in MW 1.39
    AutoLoader::registerNamespaces( [
        // Keep this in sync with the "autoload" clause in
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src",
    ] );
}

wfLoadExtension( 'Parsoid', "$parsoidInstallDir/extension.json" );

# Manually configure Parsoid
$wgVisualEditorParsoidAutoConfig = false;
$wgParsoidSettings = [
    'useSelser' => true,
    'rtTestMode' => false,
    'linting' => false,
];
$wgVirtualRestConfig['modules']['parsoid'] = [
    // URL to the Parsoid instance.
    // If Parsoid is not running locally, you should change $wgServer to match the non-local host 
    // While using Docker in macOS, you may need to replace $wgServer with http://host.docker.internal:8080
    // While using Docker in linux, you may need to replace $wgServer with http://172.17.0.1:8080
    'url' => $wgServer . $wgScriptPath . '/rest.php',
    // Parsoid "domain", see below (optional, rarely needed)
    // 'domain' => 'localhost',
];
unset( $parsoidInstallDir );

These lines are not necessary for most users of VisualEditor, who can use auto-configuration and the bundled Parsoid code included in MediaWiki 1.35 and VisualEditor, but they will be required for most developers.

If you're serving MediaWiki with Nginx, you'll need to also add something like this in your server block (Assuming your MediaWiki setup has its files residing in /w/): 

location /w/rest.php/ {
    try_files $uri $uri/ /w/rest.php?$query_string;
}

To test proper configuration, visit {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page where $domain is the hostname in your $wgCanonicalServer. (Note that production WMF servers do not expose the Parsoid REST API to the external network.)

テストを実行するには

To run all parser tests and mocha tests: 

$ composer test

The parser tests have quite a few options now which can be listed using php bin/parserTests.php --help.

If you have the environment variable MW_INSTALL_DIR pointing to a configured MediaWiki installation, you can run some additional tests with: 

$ composer phan-integrated

簡単なwikitextへの変換

You can convert simple wikitext snippets from the command line using the parse.php script in the bin/ directory: 

echo 'Foo' | php bin/parse.php

The parse script has a lot of options. php bin/parse.php --help gives you information about this.

Parsoidのデバック (開発者向け)

See Parsoid/Debugging for debugging tips.

Continuous Integration

As of October 2021

Parsoid is always available as a library since it is a composer dependency of MediaWiki core. But two pieces are not enabled:

  • Parsoid ServiceWiring
  • Parsoid's external REST api

The test runner Quibble would enable it if it detects mediawiki/services/parsoid.git has been cloned as part of the build. In which case it:

  • points the autoloader for Wikimedia\Parsoid to the cloned code (effectively replacing the version installed by composer)
  • Load the extension wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

The ServiceWiring should be enabled in MediaWiki starting with 1.38.

The REST API would theorically never get merged in MediaWiki: a) it has never been exposed to the public in production, it is an internal API used by RESTBase which is going away; b) it never has been security audited and c) it is redundant with the enterprise MediaWiki API. The solution will be for VisualEditor to invoke Parsoid directly via the VisualEditor Action API which would save a round trip through the REST API.

Loading the extension is thus a hack which enables using interfaces subject to change and which we don't really want people to use yet.

For most purposes, parsoid should thus not be added as a CI dependency, the only exception as of October 2021 is the Disambiguator MediaWiki extension.

Loading parsoid as an extension let us run MediaWiki integration test jobs against mediawiki/services/parsoid.git (such as Quibble, apitesting) and ensure Parsoid and MediaWiki work together.

An extension may be able to write tests with Parsoid even when the repository has not been cloned. Since it is a composer dependency of MediaWiki core the MediaWiki\Parsoid namespace is available, but the service wiring part is not (it is extension/src in the Parsoid repository and exposed as the \MWParsoid namespace). The ParsoidTestFileSuite.php code would only run the parser tests if Parsoid has been loaded (which should be the default with MediaWiki 1.38).

For CI, Parsoid is tested against the tip of mediawiki, whereas mediawiki is tested with the composer dependency. In case of a breaking change, the Parsoid change get merged first (which breaks its CI but not MediaWiki one) and MediaWiki get adjusted when Parsoid is updated. It is thus a one way change.

Release build

For MediaWiki release builds, we have an integration of Parsoid ServiceWiring into VisualEditor in order to have VisualEditor work without further configuration (beside a wfLoadExtension( 'VisualEditor' )). The release build also enables the REST API and hook everything us so that parsoid works out of the box. This is done by copying a bit of parsoid code into VisualEditor which is not in the master branch of VisualEditor since that would be obsolete as soon as Parsoid is updated. Instead the code is maintained in two places.

技術的な説明文書

Proton 開発者向けリンク

History

元々はJavaScript (Node.jsを使用)で記述され、ウィキメディアクラスターで2012年12月に運用開始しました。 2019年、PHPに移植され、12月にウィキメディアクラスターのParsoidもPHPバージョンに置き換えられました。 Parsoid は、MediaWiki コアに統合されており、将来的には MediaWiki の現在のネイティブ パーサーを置き換えることを目指しています。 In early 2024, Parsoid began to be used on some production wikis of the Wikimedia Foundation as the default parser for read views.

Parsoid(PHP Ver.)は2020年9月のVer.1.35から標準で組み込まれています。 ウィキメディア以外でのParsoid/JSの利用は、2021年9月のMediaWiki 1.31 (LTS)のサポート終了までサポートされていました。

The legacy parser will still be supported in MediaWiki 1.43 (LTS).

関連項目

外部リンク

お問い合わせ

ヘルプが知りたい、質問／ご意見ご指摘については、担当に #mediawiki-parsoid 接続 または ウィキ文メーリングリスト wikitext-l mailing list に投稿してください。 どれもうまくいかなかった場合は、担当にメールにてwikimedia.org ドメインのcontent-transform-teamまでご連絡ください。

Retrieved from "https://www.mediawiki.org/w/index.php?title=Parsoid/ja&oldid=6935831"