MarkdownをLintする必要性についての検討

[yumetodo]

背景

注釈を貼る記法をどうするかについて議論の結果、 #509 でルールが明文化されました。

しかし、例えば #542 (comment) のように連番の維持が難しい例がある。

人間が連番の維持なんて作業をできるとは思えない

提案

MarkdownをLintして適当なCIに掛ける。

MarkdownのLinterといえばRubyで書かれた
https://github.com/markdownlint/markdownlint
があるのでこれをforkしていじるという選択肢が考えられる(どうもこいつにはPluginシステムはないようです)

デメリット

site_generatorが利用しているPythonのMarkdownライブラリとMarkdownのパースが一致しないことに起因する問題が生じる可能性がある。

考えられる他の解決策

• HTML変換後に対してLintする: 手間ばかりかかる
• 注釈を貼れる記法の追加 site_generator#52 をReopen、独自記法を追加する: 導入コストが高くて一度見送られている
• HTML変換後に対してid重複のみ探索: site_generatorで対応しやすそうだけど効果は極めて限定的

[faithandbrave]

んー。まず、cpprefjpサイトのメインコンテンツは、ライブラリのリファレンスと、言語の新機能の解説なのですよね。そこで積極的に利用していない機能の利便性を向上させるのは、優先度が非常に低いと思います。
少なくとも私は興味がないのでやりません。

[faithandbrave]

もう少しちゃんと書きます。
まず、現在、私も @melpon もツール開発のための作業リソースがそれほどありません。そのような状況でも我々が作業すべきことは、本サイトのメインコンテンツのうち、広範な作業がやりにくいことに対する改善、もしくはサイトの利便性が悪いことの改善です。そのようなものは、作業リソースが乏しい状況でも取り組む必要があります。
そうでない場合、貢献の意思とセットでなければ提案を受け入れるのは難しいです。問題提起され、それが実際に問題になっているからといって、作業できる状況でなければ取り掛かれないというのはご理解していただきたいです。
そして、「いつか時間がとれたら検討する」くらいのものをIssueとして長く残しておくのは、いつまでも閉じられないIssueがどんどん増えることになってよくありません。ですので、当面だれも取り組めない問題は、その場では対処しないものとしてクローズさせてください。

また、この提案についてですが、Lintツールによってtypoの検出や、日本語の言い回しが悪いところ、さらにがんばればサイト内で統一されていない言い回しの検出などもできるでしょう。しかし、そのような軽微な問題はサイトの価値を低下させるものではなく、その軽微な問題を修正をしてもサイトの価値が向上するわけではありません。
「typoがあることでサイトの価値が落ちているから、自動検出して直ちに修正すべきである」とは考えられない、ということで、Lintツールを作業リソースを割いて導入するほどではない、というのがいまの私の考えとなります。

今回の提案については、作業担当者がついたら議論の余地がありますが、貢献の意思とセットで提案されたものでもないため、数日中に作業担当者が立候補しない場合は、この提案をクローズさせていただきます。

[yumetodo]

了解しました。私自身も今は作業時間が取れないので、時間が取れたら作業してPull Requestでの提案はするかもしれません。いつのことやらですが。

数日中に作業担当者が立候補しない場合は、この提案をクローズさせていただきます。

お願いします