Skip to content

Add VS Code TextMate grammar for #@ directives in manual/*.md#3047

Merged
znz merged 2 commits into
rurema:masterfrom
znz:tools/vscode-rurema-grammar
Jul 10, 2026
Merged

Add VS Code TextMate grammar for #@ directives in manual/*.md#3047
znz merged 2 commits into
rurema:masterfrom
znz:tools/vscode-rurema-grammar

Conversation

@znz

@znz znz commented Jul 10, 2026

Copy link
Copy Markdown
Member

概要

manual/**/*.md を VS Code で編集するときに #@ プリプロセッサ指令を
ハイライトする TextMate grammar を追加します(MARKUP_SPEC §15 の
「エディタ支援: #@ 指令用の VS Code TextMate grammar 作成」の実装)。

tools/vscode/rurema-markdown/ に文法のみの最小構成の拡張として配置:

  • package.json — Markdown への injection grammar として contribute
    (既存の Markdown ハイライトはそのまま、#@ 行にだけ色を足す)
  • syntaxes/rurema-directives.tmLanguage.json — 文法本体
  • README.md — インストール手順(~/.vscode/extensions/ へ symlink)と対応範囲

設計のポイント(bitclust Preprocessor と同じ解釈)

  • 行頭(カラム0)の #@ 行だけを指令として扱う(インデントされた #@ は本文。
    Preprocessor の \A アンカーと同じ)
  • 対応指令: #@since/#@until(バージョン値を強調)・#@ifversion
    比較/論理演算子・文字列を強調)・#@else/#@end(後続テキスト不可)・
    #@include(path)#@samplecode [ラベル]#@todo(大文字小文字不問)・
    #@# コメント
  • 既知の指令以外の行頭 #@ は invalid(エラー色)表示 — ビルドでも
    parse error になる行なので、編集中のタイポ検出を兼ねる
  • プリプロセッサはコードブロック内・YAML front matter 内(§1.6 のゲート付き
    リスト)の #@ も処理するため、injection はそれらの領域にも適用される

検証

  • 文法中の全 regex が Onigmo(TextMate の Oniguruma 互換エンジン)でコンパイル可
  • manual/ 全ツリーの行頭 #@ 全 10,062 行をパターン順で分類:
    #@# 4,028 / #@else#@end 2,970 / #@since#@until 2,099 /
    #@todo 737 / #@include 124 / #@if 103 / #@samplecode 1、
    invalid・未分類は 0 行(= 実在する正しい指令を誤ってエラー表示しない)
  • 不正形 7 種(#@sinse・バージョン欠落・#@else foo 等)が invalid に落ち、
    非対象 4 種(インデント付き・\#@ エスケープ・行中の #@)はマッチしないことを確認
  • VS Code 上での見た目の最終確認のみ手元でお願いします
    (symlink → ウィンドウ再読み込み → manual/ の適当な .md を開く)

CI

tools/** はマニュアルのビルドに影響しないため、docs/**refm/** と同様に
CI の paths-ignore と misspell の対象から除外しました(2コミット目)。
除外後も misspell の対象が正しく残ることをローカルで確認済み
git ls-files 1,270 ファイル、tools/docs/refm は 0)。

なお本 PR 自体は .github/workflows/ci.yml を変更しているため CI が一度走ります
paths-ignore は変更ファイル全部が ignore に一致した場合のみスキップ)。
workflow 変更の検証を兼ねるのでそのままにしています。
除外が効くのは今後の tools/ のみの変更からです。

🤖 Generated with Claude Code

A minimal grammar-only VS Code extension that injects highlighting for
the #@ preprocessor directives into the built-in Markdown highlighting
(tools/vscode/rurema-markdown, install by symlinking into
~/.vscode/extensions).

Covers the same directive set as bitclust's Preprocessor: #@SInCE,
#@until, #@if, #@else, #@EnD, #@include, #@SampleCode, #@todo and #@#
comments, at column 0 only, matching the preprocessor's behavior. Any
other column-0 #@ line is shown as invalid, because it would be a
parse error at build time — this doubles as typo detection while
editing.

Validated against the whole manual/ tree: all 10,062 column-0 #@
lines classify into the intended patterns (0 fall out as invalid or
unmatched), and synthetic typos/malformed directives are flagged
invalid. Every regex compiles under Onigmo, which approximates the
Oniguruma engine TextMate uses.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
tools/ holds editor tooling (the VS Code grammar), which does not
affect the manual build, in the same way docs/ and the frozen refm/
do not.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz znz merged commit e2ce733 into rurema:master Jul 10, 2026
9 checks passed
@znz znz deleted the tools/vscode-rurema-grammar branch July 10, 2026 05:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant