feat: exampleタグの使う場面をドキュメントに追記

[yumetodo]

#487 より。exampleタグの使う場面をドキュメントに追記

ref:

• サンプルコードの拡張記法を使うべき場面について再考 #487
• 編集者向けの細かい慣例を明文化する #481

[saki7]

✨

[k-satoda]

「概要」にサンプルコードを書くことは無いと思うので、記載の位置が変な気が
しました。で、ここじゃなくて「例」のところに書けばいいのでは？と思って
見に行くと、すでに example タグは付いてますしコメントで言及もありました。
そっちに "(ref: cppref特有の拡張構文)" を追加するだけでよかったりしませんか？
（いっしょに編集されてるほかのページもまとめての話です。）

[saki7]

@k-satoda 本提案の主旨として、

#487 (comment)

以上の @yumetodo さんのコメントにあるように、以下のような点が背景にあります。

1. サンプルコードは「例」の中に書かれているとは限らない（その例外がたくさんあることが判明した）
2. どのコードをサンプルコードとして扱った方が良いのか明文化されていない
3. サンプルコードには基本的に example タグを付けることが望ましい（という風に僕が方針を示した）

このため、説明文に関してはご指摘のように「例」だけに書かれているのでは分かりづらいので、「どこでもサンプルコードを書いてよい」という風に奨励する意図を書く必要があります。

[k-satoda]

@saki7 「例」以外のコードブロックにも example をつけるおねがいは
いっしょに追加されてる example タグの説明に書かれているので、
新しく編集する人も「cpprefjpを編集するには」→「cpprefjp特有の拡張構文」
と読み進めれば拾えるようにはなっていそうです。

「新規ページ作成者さんが必ず読むところに重ねての注意が欲しい」という
ことなら文書構造とは関係ない話なので「概要」の一部として書くのではなく
テンプレ先頭に上記文書への参照を置いたほうがいいんじゃないかと思いました。

「どこでも～」という意図を考えてもやっぱり「概要」の中で言及することは
合わないように思います。現状の「例」でのみ言及されている状態を問題とする
なら「概要」と「例」でのみ言及されている状態にしても解決とはいえなさそうで。

[yumetodo]

「概要」にサンプルコードを書くことは無いと思うので

あります。
ex.)

• https://cpprefjp.github.io/reference/algorithm.html
• https://cpprefjp.github.io/lang/cpp17/inline_variables.html

「新規ページ作成者さんが必ず読むところに重ねての注意が欲しい」という
ことなら文書構造とは関係ない話なので「概要」の一部として書くのではなく
テンプレ先頭に上記文書への参照を置いたほうがいいんじゃないかと思いました。

「概要」と「例」でのみ言及されている状態にしても解決とはいえなさそうで。

# page_title (ページのタイトルです)

これの直下に、ということですか？

[saki7]

僕は現状の書き方でもOKですが、 @k-satoda さんの指摘のように記載場所に違和感があるということも少し分かります。

[k-satoda]

@yumetodo なるほど、概要を示すにあたって多少長くなってでも
コードを示したほうが手っ取り早いことはありますね。気づいてませんでした。

「テンプレ先頭に」はタイトルよりも上のつもりでした。タイトルの書き方に
関する情報が参照先の文書に載っててもおかしくはないと思いますし。
ただし、機械処理とか、なんか支障が出るようなら下でもいいと思います。

[saki7]

@yumetodo コミットコメントなどは好きに書いて良いと思うのですが、プルリクエストが英語だと少し分かりづらいので、日本語に改題していただけると助かります。

[yumetodo]

@k-satoda これでどうでしょうか？

[saki7]

ここに移動するのであれば、意図を明確にするために、補足を入れた方が良いと思います。

• 「サンプルコードは文章中のどの部分で書いても大丈夫です。閲覧者の理解を助けるために必要だと感じたところで入れてください。」

[k-satoda]

元コメントの「テンプレ先頭に上記文書への参照を～」で指していた文書は
「cpprefjpを編集するには」「cpprefjp特有の拡張構文」のことでした。
後者は前者からリンクされているので後者は無くてもいいかもしれないとも
思います。

「スタイル」など他にもいろいろある全体的な編集のしかたのうち
example タグについてだけが各テンプレ先頭に置いてあるというのはちょっと
変な気がします。

[yumetodo]

元コメントの「テンプレ先頭に上記文書への参照を～」で指していた文書は
「cpprefjpを編集するには」「cpprefjp特有の拡張構文」のことでした。
後者は前者からリンクされているので後者は無くてもいいかもしれないとも
思います。

おっと、読み間違えていました。

@saki7 さんの指摘も踏まえ反映します。

「スタイル」など他にもいろいろある全体的な編集のしかたのうち
example タグについてだけが各テンプレ先頭に置いてあるというのはちょっと
変な気がします。

やっぱりそうですよね・・・
revertします。

[yumetodo]

根本的に書き直しました。

[saki7]

大筋ではこれでも良いと思います。

が、途中をrevertしたことで繋がりがなくなってしまっているので直す必要があると思います（ということに今気づきました）。

以下の文章は、自己言及している気がするので、少し削っても良いんじゃないかなと思います。

その際拡張構文であるexampleタグをルールに従って付け、コンパイル・実行可能にすることを検討してください。

↓

その際は拡張構文のexampleタグを付け、コンパイル・実行可能にすることを検討してください。

exampleタグについての説明をrevertしてセクションが丸ごと消えたので、このprの現状ではexampleタグについて説明している箇所はここしかないです。

そうなると、この文章自体がルールになると思います。そこで、「ルールに従って……」と書いてしまうと「ルールってこれじゃないの？」と自己言及している風に感じると思います。

なので、exampleタグについてのrevertはrevertしない方が良いと思います。

雛形で端的に書くのは重要ですが、少し詳しく解説しているページがあっても良いと思います。ここは、僕は初稿の書き方が好きでした （Approveしてます）

[yumetodo]

exampleタグについての説明をrevertしてセクションが丸ごと消えたので、このprの現状ではexampleタグについて説明している箇所はここしかないです。

あべし、それが消えたのは意図するところではなかったです・・・戻します(commit log ごちゃごちゃ)

以下の文章は、自己言及している気がするので、少し削っても良いんじゃないかなと思います。

削ると拡張構文の説明ページ(現在lost中)を見てもらえない気がします。

[saki7]

削ると拡張構文の説明ページ(現在lost中)を見てもらえない気がします。

真上にリンクがあるのでそこを見てもらえるのではないですか。ここは任せます。

[yumetodo]

戻しました。

個人的には「ルールに従って」の部分は削るつもりはないですが他のレビューを待ちます。

[saki7]

お疲れ様です、このprに関しては細かい合意形成は #487 で終わってるので、あとの流れはお任せします。文面については僕の意図は伝わったと思います。

@yumetodo これをマージしたら #487 も close して良いと思います。似たIssueに #481 というのがありますが、これはタイトルが適切でないので変更しておきます。

[yumetodo]

@k-satoda さんないし @faithandbrave さんにmergeは委ねたいです。12/16 0:00 JST時点でmergeされていない場合は私がmergeします。