2
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 1 year has passed since last update.

無料のVisual Studio CodeとXML拡張機能でJATS XMLを編集する

2
Last updated at Posted at 2025-06-10

JATS (Journal Article Tag Suite)のXML文書(学術情報XML1)を、無料のVisual Studio Code (VSCode)と無料の拡張機能XML2 (以下、vscode-xml)を使って編集するときに、気になる次の3 4つについて:

  • バリデーション(validate、妥当性検証)
  • コード補完(code completion)
  • 外部実体(external entity)の解決
  • ワークフロー

まず大事な外部実体の解決から。

外部実体の解決

J-STAGE3では、DOCTYPE宣言を次の固定値としていて、つまりDTDがJ-STAGEドメインのリモートにあるという前提です:

<!DOCTYPE article PUBLIC " -//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.1 20151215//EN " " https://www.jstage.jst.go.jp/dtds/1.1/JATS-journalpublishing1.dtd ">

J-STAGEのDTDや、DTDの内部で展開されるパラメーター実体(parameter entity、パラメーター・エンティティ)はリモートにあります。そこで、

  • vscode-xmlのxml.validation.resolveExternalEntitiesをtrueに設定します4 (図参照)
  • 信頼できるワークスペースで作業します。「このフォルダー内のファイルの作成者を信頼しますか?」に「はい、作成者を信頼します」と答えます
  • J-STAGEがメンテナンス中だとDTDを取得できません(^_^;) (図参照)

図 xml.validation.resolveExternalEntitiesをtrueに設定

xml-setting.png

resolve-external-entities.png

図 DTDを読み込めない例
jstage-maintenance.jpg

xml.validation.resolveExternalEntitiesの初期値はfalseになっていて、そのままだと、DTDは読み込むのですが、DTDが参照してる別ファイル内のパラメーター実体の宣言などが読み込まれません。JATSでは、こういった芋づる式に読み込まれるファイルが59個あるようです。

DTDなどを読み込めないと次の不都合が起きます:

  • JATS XML文書がバリデーションでエラーになります
  • DTDに基づいたコード補完5が効きません。コード補完は便利です、挿入可能なタグや属性名の候補を出してくれますから(後述)

初期値で外部実体を解決しないという設定は、vscode-xmlに限らずXMLを扱うツール全般に言えることです。XML外部実体攻撃6を警戒してるのだと思います。

XML Catalogを使う

(コメントいただいたように)XML Catalogを使うとDTDなどをローカルに置いて作業できます。JATS XML文書はそのままで、変えなくてよいです。

オフラインでも作業できるように、DTDなどをダウンロードして、vscode-xmlがダウンロードしたDTDなどを見に行くようXML Catalogを使う方法を、別の記事に書きました。こちらを参照してください。

ダウンロードしたDTDを直接指すように書き換える

別記事のようにDTDなどをダウンロードできたら、JATS XML文書のDOCTYPE宣言を書き換えて、ダウンロードしたDTDを直接参照する方が分かりやすいかもしれませんね。難しいことはスキップして、最短距離で編集にたどり着く……たどり着けるかもしれない方法です。

<!DOCTYPE article
  PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.1 20151215//EN"
  "https://www.jstage.jst.go.jp/dtds/1.1/JATS-journalpublishing1.dtd"
>

entityフォルダ配下にDTDなどを置いたとすると、次のように書き換えます:

<!DOCTYPE article
  PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.1 20151215//EN"
  "entity/JATS-journalpublishing1.dtd"
>

バリデーション

設定したDTDに対して妥当性を検証して、問題のあるところには赤い波線が表示されて、その波線にカーソルを置くと、問題の内容や参考ページへのリンクが表示されます。図ではjournal-meta要素の中が空っぽなので怒られてます。

図 問題のあるところに赤い波線
validation1.png

バリデーションを手動でトリガーできます。Visual Studio Codeのコマンド パレット7を開いて、xml: reとタイプしてXML: Revalidate current XML fileを選ぶと、今開いてるXML文書をバリデートできます。

図 開いてるXML文書を手動でバリデート
revalidate.png

コード補完

DTDがあると、カーソル位置に挿入できる要素や属性を補完してくれます。

要素のコード補完

次の図は、article要素の配下で<と打ち込んだところで、そこに挿入できる要素の候補が表示されてます。

図 DTDに基づいて入力できる要素を表示
code-completion-1.png

属性のコード補完

属性もコード補完されます。図は、contrib要素のタグの中でcとタイプしたところで、設定できる属性の候補が表示されます。cとタイプしたからといって、cで始まる属性名だけ表示されるわけではありません。

code-completion-attribute.png

Copilotのコード提案

生成AIのCopilotの機能だと思うのですが、要素の配下やタグの中にカーソルを置いて時間が経つと、そこから続くコードが提案されます8。図はfront要素の配下にカーソルを置いて少し経ったところで、front配下の構造の提案されてます。ここでTABキーを押すと、これらが確定します。これがDTDに基づいて妥当なのか…は、ちょっと分からないですが、確定したらバリデートされるので、問題あれば分かりますね。

copilot.png

ワークフロー

JATS XML文書をゼロから作成・編集することは、あまりないでしょう。たいていは、著者あるいは学会から入稿されたWord形式、LaTeX形式、あるいはHTML形式(後述)の査読・掲載決定済み原稿をツールでJATS XMLに変換するでしょう。そのJATS XMLを出発点として、DOIを追加したり、著者・所属をJATSの構造に構造化したり、参考文献を構造化したりするのではないでしょうか。特に、著者・所属や参考文献は細かくタグ付けされます。例えば、著者が山田太郎、Jane Smithなら、こんなふうに分解したりします:

<contrib-group>
  <contrib contrib-type="author">
    <name xml:lang="ja" name-style="eastern">
      <surname>山田</surname>
      <given-names>太郎</given-names>
    </name>
  </contrib>
  <contrib contrib-type="author">
    <name xml:lang="en" name-style="western">
      <surname>Smith</surname>
      <given-names>Jane</given-names>
    </name>
  </contrib>
</contrib-group>

この作業でCopilotのコード提案を利用すると、提案される範囲は限定的で、そんなに外れてないかも…やってみないと分かりませんが (^_^;)

VivliostyleではMarkdownで論文を書いて、所定の書式をCSSで指定して組版できます9。組版の途中で生成されるHTML、あるいはWebPub10のHTML、あるいは元々のMarkdown形式で論文データを入稿するのもありかなと思うところです。gihyo.jpの記事のサンプルのHTMLを、JATS XML変換するサンプル・プログラムを作ってみました11。この出力をVisual Studio Code + vscode-xmlで触ってみてください。

サンプル

実際のJATS XML文書を触ってみたいところです。「JATSがわかる 学術情報XML作成の実際」という本の出版記念ページからたどって、本のJATS XML文書をダウンロードできます。

ダウンロードしてみると、XML文書がいくつかのフォルダー/ファイルに分かれています。前述のXML Catalogファイルの置き場所などを考える事例にもなりそうです。

やってみましょう。

ファイルの準備

JATS XML文書のサンプルのZIPファイルを展開すると、JATSBOOK_XMLというディレクトリ/フォルダーができて次のような構造になると思います:

JATSBOOK_XML
├── 2025_112
│   ├── 2025_112.txt
│   ├── 2025_112.xml
│   └── Graphics
│       ├── 2025_112_f1.jpg
│       ├── …
├── 2025_122 # 以降、配下の構造を省略
├── 2025_14
├── 2025_2
│── 2025_38
├── 2025_52
├── 2025_65
├── 2025_78
├── 2025_98
└── 2025_i

前記の別記事のようにJATSのDTDをダウンロードして展開すると、(JATS-Publishing-1-1-MathML2-DTDができて、その下にさらに)JATS-Publishing-1-1-MathML2-DTDというフォルダーができて次のような構造になってるでしょう:

JATS-Publishing-1-1-MathML2-DTD
├── catalog-jats-v1-1-no-base.xml
├── catalog-jats-v1-1-with-base.xml
├── iso8879
│   ├── isobox.ent
│   ├── isocyr1.ent
│   ├── … # 以降、省略
├── iso9573-13
│   ├── isoamsa.ent
│   └── … # 以降、省略
├── JATS-journalpublishing1.dtd
├── … # 他、省略
├── mathml
│   ├── mmlalias.ent
│   ├── … # 以降、省略
└── xmlchars
    ├── isogrk1.ent
    ├── … # 以降、省略

ここで

  • このJATS-Publishing-1-1-MathML2-DTDフォルダーをJATSBOOK_XMLフォルダーの下に移動して
  • XML Catalogファイルcatalog-jats-v1-1-with-base.xmlをJATSBOOK_XMLフォルダーの直下に移動します

するとこんな構造になってるかと:

JATSBOOK_XML
├── 2025_112
├── 2025_122
├── 2025_14
├── 2025_2
├── 2025_38
├── 2025_52
├── 2025_65
├── 2025_78
├── 2025_98
├── 2025_i
├── catalog-jats-v1-1-with-base.xml
└── JATS-Publishing-1-1-MathML2-DTD
    ├── catalog-jats-v1-1-no-base.xml
    ├── iso8879
    ├── iso9573-13
    ├── JATS-journalpublishing1.dtd
    ├── … # 以降、省略

XML Catalogの準備

ここでcatalog-jats-v1-1-with-base.xmlファイルをテキストエディターなどで開いて、xml:baseでファイル内を検索すると、次のような記述が複数見つかるでしょう:

xml:base="put a real base here, such as 'file:///C:/MyWork/OurTasks/DTDs-for-JATS/'"

XMLもHTML同様に<!--から-->まではコメントです。コメント外のxml:baseを次のように書き換えます(置換します):

xml:base="./JATS-Publishing-1-1-MathML2-DTD/"

カレント・ディレクトリの下のJATS-Publishing-1-1-MathML2-DTDフォルダが基準ですよ、ということです。

Visual Studio Codeを起動

Visual Studio Codeを起動してJATSBOOK_XMLフォルダーを開きます。このフォルダーがワークスペースです。すると「このフォルダー内のファイルの作成者を信頼しますか?」と聞いてきます。NIH(National Institutes of Health、アメリカ国立衛生研究所12)などを信頼できるなら「はい、作成者を信頼します」を選択します。ここで信頼しないとvscode-xmlはDTDなどを読み込みません。

01-trust-2.png

XML Catalogを読み込む設定

vscode-xmlがXML Catalogファイルcatalog-jats-v1-1-with-base.xmlを読み込むように設定します。Visual Studio Codeのコマンド パレットを開いてsettings (JSON)などと打ち込むと「基本設定: ワークスペース設定を開く (JSON)」というコマンドが現れるので選択します。

02-workspace-settings.png

settings.jsonとファイルが開くので、次の項目を追加します:

"xml.catalogs": [
    "catalog-jats-v1-1-with-base.xml"
]

項目はコンマ,で区切るので、この項目の前にも項目があったら、その後ろに,があることを確認してください。
settings.jsonファイル全体としては、こんな感じになってるでしょう

{
    // …他の項目
    "xml.catalogs": [
        "catalog-jats-v1-1-with-base.xml"
    ]
}

ここまでで、次のような構造になってるでしょう:

JATSBOOK_XML
├── .vscode
│   └── settings.json
├── 2025_112
├── 2025_122
├── 2025_14
├── 2025_2
├── 2025_38
├── 2025_52
├── 2025_65
├── 2025_78
├── 2025_98
├── 2025_i
├── catalog-jats-v1-1-with-base.xml
└── JATS-Publishing-1-1-MathML2-DTD

.vscodeフォルダは隠しファイルになっていて「隠しファイルを表示する」設定にしないと表示されないかも。.vscodeフォルダの下のsettings.jsonが、今編集したワークスペース設定のファイルです。

外部実体読み込む設定

前記「外部実体の解決」の通り、vscode-xmlがDTDなどを読み込むように設定します。

準備ができました。

JATS XML文書を開く

2025_2フォルダの下の2025_2.xmlファイルをクリックして開いてみます。前記「バリデーション」のような赤い波線が表示されないことを確認してください。

03-jats-xml-2.png

前記「バリデーションの方法で手動バリデートしてみると、ウィンドウ右下に「The current XML file was successfully validated.」と表示されて、妥当性を確かめられました。

04-validated.png

ようこそ!JATS XMLの世界へ

  1. JATS XMLとは - 学術情報XMLとは - 学術情報XML推進協議会 https://xspa.jp/what/jats/ ↩

  2. XML Language Support by Red Hat https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml ↩

  3. J-STAGE全文 XML利用者向けマニュアルhttps://www.jstage.jst.go.jp/static/pages/GuidelineAndManuals/zenbun-xml-jats1_1-manual/-char/ja ↩

  4. Resolve External Entities https://github.com/redhat-developer/vscode-xml/blob/main/docs/Validation.md#resolve-external-entities ↩

  5. Completion based on DTD https://github.com/redhat-developer/vscode-xml/blob/f6aaeba81da7f74292e72341a09c4fe7bbc0df20/docs/Features/XMLFeatures.md#completion-based-on-dtd ↩

  6. XML外部実体攻撃 https://ja.wikipedia.org/wiki/XML%E5%A4%96%E9%83%A8%E5%AE%9F%E4%BD%93%E6%94%BB%E6%92%83 ↩

  7. GitHub Codespaces で Visual Studio Code のコマンド パレットを使う https://docs.github.com/ja/codespaces/reference/using-the-vs-code-command-palette-in-codespaces ↩

  8. GitHub Copilotを使用してIDEでコードの提案を取得する https://docs.github.com/ja/copilot/using-github-copilot/getting-code-suggestions-in-your-ide-with-github-copilot ↩

  9. VFMで学会論文を書いてVivliostyleで組んで投稿する https://gihyo.jp/article/2025/02/vivliostyle-05 ↩

  10. Web 出版物(WebPub)の出力 https://github.com/vivliostyle/vivliostyle-cli/blob/main/docs/ja/special-output-settings.md#web-%E5%87%BA%E7%89%88%E7%89%A9webpub%E3%81%AE%E5%87%BA%E5%8A%9B ↩

  11. 論文ThemeのHTMLファイルをJATSに変換 https://yamahige.github.io/study/vivliostyle-theme-ipsj-tech-2-jats/index-google-xml-formatter.html ↩

  12. https://ja.wikipedia.org/wiki/%E3%82%A2%E3%83%A1%E3%83%AA%E3%82%AB%E5%9B%BD%E7%AB%8B%E8%A1%9B%E7%94%9F%E7%A0%94%E7%A9%B6%E6%89%80 ↩

2
4
2

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
2
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?