編集者向けの細かい慣例を明文化する

[saki7]

from #473

[yumetodo]

@faithandbrave 0258311 の内容だと、「例」の項の中のみにこのsynatxが適応されるように読めるのですが・・・

[faithandbrave]

雛形に全てのルールを記載するわけではないです。Issueの議論を遡ること、ほかのページとスタイルを合わせることが編集者に求められます。
3,000ページ超の情報を提供している本サイトにおいて、類似ケースを探し出せない状況は数少ないです。

分厚い辞書のようなルールを渡されて、それら全てを満たす記事を書くことは参入障壁にもなるため、明記してあるルールは最小にし、Pull Requestを受け入れる基準も甘めにし、細かいスタイルの違いはスタイルを知っている人が周りに合わせるよう修正します。
なので、歴史と周りを知ってください。

[e-kwsm]

雛形に全てのルールを記載するわけではないです。

「例」以外で cpp example をつけるのは多分まれなのでこのままでいいと思います．

Pull Requestを受け入れる基準も甘めにし、細かいスタイルの違いはスタイルを知っている人が周りに合わせるよう修正します。

には同意ですが，ルールは明文化した方がいいと思います．

[faithandbrave]

ルールとしてどのようなものを想像されているかわからないですが、たとえば以下のようなものは前例をルールと見なしています：

• 機能の非推奨・削除の書き方
  • https://cpprefjp.github.io/reference/algorithm/random_shuffle.html
• 特定領域のみ出てくる項目
  • スレッド関係の「同期」とか https://cpprefjp.github.io/reference/thread/this_thread/sleep_for.html
  • 乱数関係なら「周期」「サイズ」「パフォーマンス」とか
• 図を書いて載せる場合はcpprefjp/imageリポジトリに図のファイルを置く
• 演算子のファイル名
  • リテラル演算子も含め、ほぼ全ての演算子の前例がすでにある
• 非メンバ関数のファイルをどの階層に配置するか

雛形は基本ルールですが、基本ルールだけで全てのケースに対応できるわけではありません。類似ケースの問題解決を事例として残し、それを見つけて同様の対応をするのは、どうしても必要となります。

[e-kwsm]

たとえば以下のようなものは前例をルールと見なしています：(略)

これらを参照するよう wiki か working_style.md に書いておいた方がいいと思います．

それと， cpprefjp/site_generator#10 の

@melpon に以前確認したところ、タイトル(見出し1)はなにも修飾しないで記述するのが方針だそうなので

はあまり認識されていないと思うのでこれもどこかに書いた方がいいと思います．

[faithandbrave]

クローズされたIssueで議論を続けるのはよくないので、再オープンします。
詳細ルールを明記することを止めはしませんが、メンテナンスまでお願いします。

[saki7]

@e-kwsm

サンプルコードの拡張記法の明文化について、 #487 で @yumetodo さんにお願いしているので、その他の明文化の作業をするのであれば、連携をお願いします。コンフリクトを避けるため、作業内容は事前に分担をお願いします。

[faithandbrave]

諸々の経緯は、以下を参照していただければと思います。不明点があったら聞いてください。

• 非推奨の書き方
  • 非推奨の書き方 #149
• 演算子ページの命名
  • https://github.com/cpprefjp/site_generator/blob/411bb3990113e5f88e3ba9b2ddeef6288ad0740f/settings/cpprefjp.py#L79
  • https://cpprefjp.github.io/reference/complex/op_il.html
• 非メンバ関数のファイル配置
  • 非メンバ関数mdファイルの適切な配置位置 #245

[e-kwsm]

@melpon HTML のコメントなどが無効化されていたと思いますが，どこを見ればいいですか？

[e-kwsm]

wiki に書き始めました

[saki7]

@e-kwsm 一部の設定情報は cpprefjp/kunai_config#1 によって分離されることが決まっているので、ここに含まれるデータはこれを参照するようにお願いします。今は、バックエンドの実装に着手していないので一時的に古いデータが分散している状況です。

[saki7]

@e-kwsm:

@melpon HTML のコメントなどが無効化されていたと思いますが，どこを見ればいいですか？

おそらく、通知が流れてしまっていると思うので、僕が代わりに答えます。

調べたところ、

https://github.com/cpprefjp/markdown_to_html/blob/a567e5b66ba5523724f671a87d1ffcad550dd44d/html_attribute.py#L131

https://github.com/cpprefjp/markdown_to_html/blob/a567e5b66ba5523724f671a87d1ffcad550dd44d/html_attribute.py#L17

バックエンドではここの部分でHTMLタグを正規表現でホワイトリストしているので、ここに含まれていない要素（コメント要素など）は変換されないという挙動らしいです。

[saki7]

今は @e-kwsm さんが作業しているので ( #481 (comment) )、assigneeに反映しておきます

[faithandbrave]

こちら、 @e-kwsm さんが随時Wikiにまとめてくださっているので、ここで議論するべきことは終わったと判断し、クローズします。