グローバル修飾リストのルール整備

[faithandbrave]

• インラインコードの自動リンクツールを開発したい #1452

こちらからの派生。インラインコードへの修飾とは別に、グローバル修飾リストに関してはこちらで議論を進めましょう。

グローバル修飾リスト (GLOBAL_QUALIFY_LIST.txt) の概要

このファイルにコードブロックへの修飾を列挙することで、すべてのページのコードブロックにそれらの修飾が適用される。

導入意図

• 編集者の負担を減らす
  • 何度も同じ修飾を書かないといけない記述量の問題を解消
• 管理する文書を最小限にする
• 人的ミスを減らす

現状の問題

• グローバル修飾リストになにを登録すべきかがあいまい
• オーバーロードされているページを登録できない
  • std::moveのようなalgorithm / utilityに登録されているもの
  • 引数の数だけならstd::move/1のような形式で区別できそうだが、型はむずかしい
• グローバル修飾リストにどれくらい登録できるのかがあいまい (解決済み)
  • Pythonのreライブラリの制限に引っかからない限り登録できる、という状況
  • コードブロック内で使われている要素だけ使用するようツール改善が必要
• グローバル修飾リストのルールがとくに書かれていないために登録しにくい
  • コメント構文を追加するPull Requestを提出中
    • GLOBAL_QUALIFY_LISTにコメントを書けるようにした site_generator#91
• 名前空間の省略、略称をどうすべきかが決まっていない
  • 名前空間の省略は、宣言や効果・戻り値の記述で必要になる
  • サンプルコードはなるべく名前空間つきで書きたい
    • どうしても長くなってしまう場合にサンプルコードで名前空間の略称をルール決めしたい

[faithandbrave]

懸念されることとしては、無制限に登録できるようになったときに、無秩序になってしまうことですね。
いままでは頻出するものを登録してきましたが、これまで通りに頻出で絞るのか、あいまいにならないもの (オーバーロード・特殊化されていないもの) は制限なく登録OKにするのか、判断がむずかしいところです

[Raclamusi]

• コードブロック内で使われている要素だけ使用するようツール改善が必要

これは、以下のコードでやっていることではありませんか？

https://github.com/cpprefjp/markdown_to_html/blob/e2af656da07c963510edcd1971460c283d3a3575/qualified_fenced_code.py#L187

pre_target_re_text_list = [q.get_target_re_text() for q in self._qs if q.find_match(code)]

[faithandbrave]

あ、すでに解決してましたか。ではこれは解決済みですね。

[faithandbrave]

変数名ルールもこの機会にある程度決めておきたいです。

forward_listの変数名がlsになっていたりするので、ls.begin()とかをグローバル修飾リストに登録しにくい、というのがあります。

• forward_list -> fls
• unordered_map -> um
• unordered_set -> us
• unordered_multimap -> umm
• unordered_multiset -> ums
• map -> m
• set -> s
• multimap -> mm
• multiset -> ms (millisecondsに対するメンバ関数呼び出しと衝突しそうだけどdurationとメンバ関数はあまりかぶってなさそう)

コンテナはalgorithmやranges、iterator関係でよくでてきます。

valarrayはvectorと衝突しないようにvaにしてあります。

[faithandbrave]

いまは単純な置換をしているグローバル修飾リストですが、たとえば変数定義や名前空間定義なども考えられそうな気はします。変数名を決め打ちすることに危険を感じられる場合には有効な手段になりそうな気はします。

# 指定された定義がコードブロック内に見つかったら、インデントされたコード修飾を適用する
* std::vector<T> v[define]
    * v.begin()[link /reference/vector/vector/begin.md]

* namespace fs = std::filesystem;[define]
    * fs::path[link /reference/filesystem/path.md]

vectorのテンプレート引数をどうするとかの問題はありますが、正規表現でテンプレート引数部分を単に無視したりはできそうな気はします。

[faithandbrave]

なんでもかんでも無制限に登録したくなったら、そのときそれはグローバル修飾リストの役割ではなく、コード解析 + 検索エンジン用の辞書データを使ったツールで自動リンクすべき問題になる気がします。
なので現状のツールの範囲では頻出を登録という方針のままにして、無制限に登録したくなったらツール開発しましょう、というルールでよい気がします。

[akinomyoga]

"see below[italic]" はたくさんのページで定義されているみたいなので GLOBAL_QUALIFTY_LIST.txt に登録しても良いのではと思いました。

$ git grep 'see[ -]below\[italic]' | wc -l
133

[faithandbrave]

それは頻出なので登録してよいかと思います