GitHub上でのプレビューのために、CommonMarkに対応する

[faithandbrave]

• A formal spec for GitHub Flavored Markdown - The GitHub Blog

GitHub Flavored MarkdownがCommonMarkベースの仕様になったことで、GitHub上での.mdファイルのプレビューが壊れています。

まず、見出し記法として##helloの代わりに## helloのようにスペースを空ける必要があります。
それと、インデントしたコードブロックのプレビューが壊れているので、調査して直す必要があります。( https://github.com/cpprefjp/site/blob/master/reference/cmath.md )

[faithandbrave]

見出しは対応完了。

インデントしたコードブロックは、いままでコードブロックの開始だけ4スペースを入れていましたが、どうやら全体的に4スペースを入れないといけないようです。 http://spec.commonmark.org/0.27/#example-102

例：

• hello

  #include <iostream>
  
  int main() {
      std::cout << "hello world" << std::endl;
  }

• world

[faithandbrave]

コードブロックのインデントをCommonMarkに合わせたら、サイト側の描画が崩れたのであとでsite_generatorを調査する。コードブロック内で4スペースのインデントが付いてしまう。

例として、C++11 エイリアステンプレートの仕様のところがそうなっている。

[faithandbrave]

site_generatorで使用しているMarkdownからHTMLへの変換ライブラリであるMarkdownは、方言の切り替えはとくにサポートしていないようです。ですので、現状の仕組みではGitHubプレビューのCommonMarkと両立させるのは難しそうです。

@melpon と相談したいところです。

[melpon]

CommonMark の仕様に対応すればGitHubとのプレビューの違いで心配が無くなるっていうのは嬉しいので、対応したいですね。
ただ、現状のシンタックスハイライトとか数式とかの拡張を維持しつつ対応するのは、そこそこコストが掛かりな予感がしています。
うまいことタスクを分散できるといいのですが、それも難しそうな気がしてます。

とりあえず site_generator で CommonMark 対応用のブランチを切って、そこで誰か（多分自分が）作業して、うまく行けばそっちに切り替える感じですかね

[faithandbrave]

暫定対処でやるとしたら、site_generator側でインデントコードブロックを検出して、開始以外のインデントを削除してから変換する、とかですかね。それくらいであれば、boostjpでのリリースノート翻訳が一段落したらぼくの方でもできそうです。
それで済まないことを想定してライブラリの選定からやり直すなら、ライブラリ選定とベース作りは @melpon にお願いして、手伝えるところはぼくもやる、くらいでしょうか。

[k-satoda]

問題になっているのは "インデントしたコードブロック" というより
"リストアイテム中のコードブロック" かなー、と思いました。
http://spec.commonmark.org/0.27/#example-215

The most important thing to notice is that the position of the text
after the list marker determines how much indentation is needed in
subsequent blocks in the list item. ...

挙げられた例だと "- hello" の "hello" の開始が "- " につづく2桁目なので、
リストアイテム全体に2桁のインデントが必要、ということになるようです。

@faithandbrave リストアイテム以外にも問題になってるところが見つかってたりしますか？

[faithandbrave]

リストアイテムだけですね。対応が必要なファイルの一覧は以下のようになっています：

cpprefjp

site/lang/cpp11/alias_templates.md
site/lang/cpp11/char16_32.md
site/lang/cpp11/defaulted_and_deleted_functions.md
site/lang/cpp11/initializer_lists.md
site/lang/cpp11/inline_namespaces.md
site/lang/cpp11/non_static_data_member_initializers.md
site/lang/cpp11/ref_qualifier_for_this.md
site/lang/cpp11/scoped_enum.md
site/lang/cpp11/uniform_initialization.md
site/lang/cpp11/user_defined_literals.md
site/lang/cpp11/utf8_string_literals.md
site/lang/cpp11/variadic_templates.md
site/lang/cpp14/generic_lambdas.md
site/lang/cpp14/initialize_capture.md
site/reference/cmath/fmod.md
site/reference/cmath/round.md
site/reference/cmath.md
site/reference/deque/op_constructor.md
site/reference/deque/op_equal.md
site/reference/deque/resize.md
site/reference/forward_list/op_constructor.md
site/reference/ios/basic_ios/op_bool.md
site/reference/ios/basic_ios/op_voidptr.md
site/reference/iterator/distance.md
site/reference/list/op_constructor.md
site/reference/map/map/op_constructor.md
site/reference/map/multimap/op_constructor.md
site/reference/numeric/partial_sum.md
site/reference/queue/priority_queue/push.md
site/reference/random/seed_seq/op_constructor.md
site/reference/regex/regex_iterator/op_constructor.md
site/reference/regex/regex_iterator/op_increment.md
site/reference/regex/regex_replace.md
site/reference/regex/regex_token_iterator/op_constructor.md
site/reference/regex/regex_token_iterator/op_increment.md
site/reference/set/set/op_constructor.md
site/reference/stack/push.md
site/reference/string/basic_string/op_constructor.md
site/reference/system_error/op_equal.md
site/reference/unordered_map/unordered_map/op_constructor.md
site/reference/unordered_map/unordered_multimap/emplace_hint.md
site/reference/unordered_map/unordered_multimap/op_constructor.md
site/reference/unordered_set/unordered_multiset/emplace_hint.md
site/reference/unordered_set/unordered_multiset/op_constructor.md
site/reference/unordered_set/unordered_set/op_constructor.md
site/reference/vector/op_constructor.md
site/reference/vector/resize.md

boostjp

site/document/version/1_55_0.md
site/document/version/1_58_0.md
site/document/version/1_59_0.md
site/document/version/1_60_0.md

[kariya-mitsuru]

markdown_to_html の方にインデントした fenced code block のインデントを削除する処理をプルリクしておきました。

[faithandbrave]

@kariya-mitsuru さんのプルリクをどうするか、site_generatorの方針をどうするかは @melpon にお任せします。

[melpon]

マージしておきました。
方針としては、短期的にはこうやってちょこちょこ気になる部分を直して、長期的にはがっつりCommonMarkに対応って感じですかね

[faithandbrave]

@kariya-mitsuru さん、 @melpon ありがとうございます。
日時更新でサイト側の描画が正しくできてそうなら、本Issueを終了しようと思います。

[faithandbrave]

@kariya-mitsuru さんがコミットした、以下のようなコード修飾にインデント4スペースを付ける修正ですが、

bb59c68

サイト上では修飾されていないようです。たとえばC++14 初期化キャプチャでのstd::moveのところ：

https://cpprefjp.github.io/lang/cpp14/initialize_capture.html

std::dequeのoperator==とかもそうです。

https://cpprefjp.github.io/reference/deque/op_equal.html

[kariya-mitsuru]

すみません、現状の markdown_to_html ではコード修飾のインデントに対応できてませんでした。
動作確認ができたら markdown_to_html に再度プルリクします。

[kariya-mitsuru]

プルリクしました。

[faithandbrave]

マージしました。
cpprefjp/markdown_to_html#3
今夜の日時更新をお待ちください。

[faithandbrave]

すいません、ページ側の対応がまだ全部おわってなかったですね。cpprefjpの方はおそらく全て修正されていると思います。
boostjpの方は手を付けていないので、私の方でやっておきます。

[kariya-mitsuru]

コードブロックがタブでインデントされていると、GitHub 上ではコードの行頭に不要なスペースが入った状態で表示されてしまっていたようなので、コードブロックのインデントを全てスペースに統一しました。

[faithandbrave]

日時更新は動作していたようですが、ページの変更がとくになさそうでした。
cpprefjp/cpprefjp.github.io@84104bb

[faithandbrave]

boostjp側の対応が完了しました。そちらはコード修飾していないので問題ありません。

[faithandbrave]

すいません、 @kariya-mitsuru さんのPull Requestを取り込んでから、site_generatorのサブモジュールを更新していませんでした。今夜の日時更新で反映されると思います。

[faithandbrave]

正しく反映されていることが確認できました。これでCommonMark対応は完了とします。
このほかに、GitHub上のプレビューが壊れているようなところがあれば、報告お願いします。