[Merge可] 規格の基本用語、慣用語、略語#493
Conversation
|
長くなって申し訳ないですが現状の相談項目です 1. 体裁などに関する質問1.1 ファイル名・階層cpprefjp の構成がよく分からないのですが、何処におけばよいでしょうか。取り敢えず今はトップレベルに 1.2 英単語と日本語の間のスペース記事によって英単語と日本語の間にスペースを入れるか入れないかについては cpprefjp で規則は設けていますか。 個人的には空白を置く派なのですが、取り敢えず今回は空白は置かない方向で作成してみました。 1.3 術語書籍だと新しくその場所で導入する術語は、ゴシック・太字 (日本語) にしたり italic (英語) にしたりしますが、cpprefjp では一定の規則はありますか。少し見た範囲で以下のものが見つかりました。
今は鉤括弧にしています。個人的にはやはり太字にした方が見やすいかなと思っています。 1.4 その他その他気になる点などを教えて頂けると幸いです。 2. 他のページで説明した方が良さそうなもの2.1 value category"○○動作" の記述で参照したいのですが value category の解説ページはありますか。もしくは C++17 で入った P0135R0, P0135R1 の解説があればそれでも良いです。見たところ見つかりません。 2.2 単一定義規則(ODR)解説しだすと長くなるのでちゃんとした説明は他のページでした方が良さそうです。今は適当な一文説明しかありません。 2.3 安定 (stable)アルゴリズム関連の用語は今のところ一つしかなく、このページに入れても孤立してしまうので、もう少し解説するアルゴリズム用語の数を増やしてから、独立させるかどうか考えた方が良いかなと感じました。 3. 当初提案された幾つかの語についての相談当初 #489 で提案された単語について、相談・確認の必要なもの 3.1 処理系依存処理系依存に明確な定義はあるでしょうか。私の感覚ですと処理系定義・未規定・未定義の動作の全てを含みそうな気がするのですが、いかがですか。 3.2 不定不定 (indeterminate) は未規定 (unspecified) と使い分けがありますのでここでは扱いません。例えば未規定の値 (unspecified value)は不定値 (indeterminate value) に含まれますがその逆は成り立ちません。これについては不定値についての説明が他のページになければここで取り扱っても良いかもしれません。また、不定の評価順序 (indeterminately sequenced-before/after) は未規定の動作をもたらしますが、これについては評価順序のページを作ってそこで説明するべきことのように思います。 3.3 合法・違法結局、合法・違法の明確な定義ってありますか? 処理系が合法か違法かについては、規格が Implementation compliance と書いているように、適合するか適合しないかということと解釈するのが自然です。一方で、プログラムの正しさのレベルは複数あり、"プログラムが合法" とは以下の何れなのか、明確な共通認識があるのか不明です。
そもそも規格は法律ではないので、合法も違法もただの "比喩表現" に過ぎないように思うのですが実際に cpprefjp で幾らか使われています。 個人的には、明確な基準がない限りは、
のどちらかにすることになるのかなという気がします。 3.4 i.e., e.g., NBcpprefjp では使われていません。規格では使われていますが、もちろん一般的な英語の用法であり特別な使い方はされていません。このページを英語辞書にしても仕方がないので取り敢えず載せないことにしました。 また標準化委員会語の NB (national body) ではなく "注意" 的な意味での NB については、cpprefjp でも使われていませんし規格でも使われていません。これは載せません。 4. 他のページとの関係4.1 用語一覧表記を統一するためのページではありますが、以下に用語一覧がありました。こちらも参考にできるかもしれません。
4.2
|
usagi
left a comment
usagi
left a comment
There was a problem hiding this comment.
これまで cpprefjp 以外の日本語情報サイトを含めても整理された情報として見られなかった情報が綺麗によく整理され、初心者、中級者の善き助けとなると思います。
|
|
||
| ### 標準規格の文書 | ||
|
|
||
| - 「提案(proposal)」新しい機能の提案文書 |
There was a problem hiding this comment.
proposal は「新しい機能提案」も "含む" けれど、「排除または非推奨とする提案」、「既存の機能を変更する提案」も含まれるので、それらを統合した表現に変更するとよりよいと思います。
There was a problem hiding this comment.
ありがとうございます。確かにそうです。後で修正します
saki7
left a comment
saki7
left a comment
There was a problem hiding this comment.
本記事を書いていただきありがとうございます。
記事の文面については正確で簡潔なもので、良いと思います。細かい文面について指摘はありませんが、構成を変えると文面はこのままでも大幅に見やすくなると思います。
詳細についてはIssueのコメントで書きます。
|
まず記事全体の構成ですが、cpprefjpユーザの動線としては
という流れだと思います。このとき、ユーザが知りたいのは単語ごとの解説と同時に、その単語が規格の中でどの領域に含まれるかという俯瞰的なイメージだと思います。 なので、 #489 (comment) ←のような画像がまず記事の一番頭に置いてあると嬉しいです。ここでは便宜上 俯瞰図 と呼称することにします。 まず、 俯瞰図 のあるなしにかかわらず、本来なら1つの俯瞰図で示せるはずの全体像を全て1か所で文章で書き下そうとすると無理が出てきてしまいます。「AとはBに含まれる○○である。BのなかにはCとDがあり、……」という内容は、ABCD各項の頭で（文脈ごとに細分化して）書いた方が良いです。 書き方の例を以下に示します： ## プログラム
C++では、～～（プログラムが規則に従う必要性を解説する）～～。
- 「適格(well-formed)」とは～～～。
- 「不適格(ill-formed)」とは～～～。
## 規則
標準規格の定める要件は、～～～。C++の標準規格内では～～～～。（ここでは詳細を省く）
- 構文規則: ～～～（詳細はここに書く）
- 制約: ～～～（詳細はここに書く）
- 意味規則: ～～～（詳細はここに書く）
### 各規則の性質
各規則には「診断不要(no diagnostics required; 慣用名 NDR)」や～～～～。
### 規則に適合する処理系
規則に適合する処理系の条件は、
- ～～～。
- ～～～。ここの初稿・先頭部分には「 構成を変えることで蛇足になる文章を除いては、文面については初稿のままで良いと思います。 ところで、このような構成の変更を入れた場合、文章の構成としては階層構造が平たくなります。書籍の体裁としては微妙かもしれませんが、多少平たい文書構造の方が、cpprefjpのこのページとしては見やすいと思います。 文書階層が平たくなることで記事として散逸している印象になった場合は、上に挙げた 俯瞰図 のようなもの（画像や表、特殊な書き方の文章など）を必要に応じて挿入すると良いはずです。これは新たに作るのは大変だと思いますので、リンクの記事に既出のもので自作のものがあればそれで構いません。 画像を追加する場合は、本文中でプレースホルダにしたうえで元画像の公開URLをコメントして頂ければ僕がひとまず https://github.com/cpprefjp/image にpushします。 文字の装飾やスペースの入れ方などは特にこれといった決まりはないので、好きなもので構いません。斜体・太字・括弧・空白を適当に入れると見やすくなると思います。（句読点は「、。」で良いと思います） もし、太字や斜体を駆使した場合でも英単語の併記のために見づらさが解消できないと感じる場合は、文章を分離して複数単語の解説を1文に詰め込み過ぎないようにすると良いと思います。 ファイル名は もとは @akinomyoga さんのこの初稿のようなイメージで僕が立てたのが #489 だったので、用語集を合流するのは本意ではありませんでした（何故「用語集」を作るという話の流れになったのか実はよく分かってません）。なので、「スタイル」ページを巻き取ることは考えなくて良いです。 「2. 他のページで説明した方が良さそうなもの」は省略して構いません。 「3. 当初提案された幾つかの語についての相談」は感覚で書いていただいて構いません。明確な定義がないものはその旨を注記したうえで、好きな言葉で解説して良いと思います。慣用英単語は全て省略して構いません。 |
|
また、せっかく https://qiita.com/akinomyoga/items/592e5a3b8438a0c8556b という素晴らしい解説があるので、これを参考リンクに含めた方が良いと思います。 |
glvalueが説明無しで出てきて、これはまずいなと思います。 https://cpprefjp.github.io/lang/cpp11/rvalue_ref_and_move_semantics.html に一応説明があるんですが、別記事にしてもうすこし噛み砕いてあげたい思いです。どのくらい噛み砕くかというと
locale依存も含んだりする気がします
ないと思うので、既存の箇所を書き換えて使わない方向にしつつ、曖昧な語句であることを取り上げるに一票( |
|
@akinomyoga 僕のコメントのイメージとして、初稿ではこの上のような脳の使い方をする必要があるのですが、下のようなイメージです （追記）これは俯瞰図の例のイメージではなくて、本記事の文書構造の別案として僕が上のコメントで示したもののイメージです。
元はと言えば、C++規格自体の構成がひどいことに端を発しているので、結構つらい問題だと思います |
|
@yumetodo さんから指摘のあったvalue categoryは非常に根が深いものなので、このprには含めなくて良いでしょう。 補足：
「処理系の正式な定義があります」というのは多分あまり深い意味はなくて、コンパイラバージョンの対応表があるよというくらいの意味合いだと思うのであまり気にしなくて良いと思います |
|
私は初稿の方が読みやすくて良いと思います。関連して把握したい事項が別節、別項に見出しレベルで分離されると、かえって相関を把握しにくいし、そのために冒頭の俯瞰図と視線を行き来するコストがかかると読者の一連の用語への俯瞰的理解をかえって妨げてしまうような気がします。 |
|
僕が上に貼ったイメージ図は誇張して書いてあるので、全ての解説項目を見出しレベルで分離する必要はないです。それぞれの文章同士の包含関係や相関関係が明らかなものは、その関係性を文書構造に反映した方が良いと思います。 value categoryのような単語への対応としてはたぶん、大きく２つあると思います。開き直って「右辺値」のような名詞にしてしまって詳細を省くか、最初から概説を書いてページ内リンクするか。ここの裁量は執筆者に任せます。 |
|
江添さんのいいようではないけれど、
という思い。 |
|
（おもに） @akinomyoga さんへ Note: 原則的に執筆内容はわたしたち "編集者" が互いに意見を交換しあいながらよりよい集合知を築き上げようとするものです。 @saki7 さん（や私や |
|
皆さんお返事ありがとうございます! また後で一つ一つお答えしますので、それまでの間どんどん気になることを書いてくださって問題ありません。 |
俯瞰図@saki7 作りますね。元の図は conditionally-supported だとか、diagnostics required だとか、locale-specific behavior だとかもっとごちゃごちゃ書き込んでありますが、余り複雑になるのもよくないのでここで説明しているものに絞って簡単化したものを作ることにします。 しかし、俯瞰図にしてしまうと規格のよく分からないところ (元の図で ❌ で示した箇所) が浮き彫りなってしまうのですよね…どうしたものか。。取り敢えずは適当にやってみます と思ったのですけれど、これ後で説明項目が追加されたり削除されたりしたら再度作り直しになって嫌ですね…取り敢えず #489 で @yumetodo さんが貼った図を暫定的に埋め込むことにします (暫定なので cpprefjp/image には追加せずに外部リンクで)。 構成をフラットにすることについて@saki7 @usagi そうですよね…。実は初めはフラットにしようとして
のような形にしたのですが、それだけで閉じようとすると余りに適当な説明になる (例: 適格とはプログラムが規格で定められたある特定の種類の規則を満たすことである) ので自己完結するように背景説明を加えたことによって初稿の構造になりました。
これは結局読み手がどのレベルの理解を求めてこのページに来るのかという問題ですね。cpprefjp の他の記事で分からない単語があったときに、このページに来てその単語がどういうカテゴリの概念なのかがぼんやりと分かれば良くてちゃんと理解したいわけではないというのであれば、各単語ごとにそれっぽい説明があれば良さそうです。一方で、その単語を理解したいと考えるのであれば、初稿のような説明書きがないと背景も意義も掴めません。 前者の目的のために 構文規則・意味規則
@saki7 確かにそうです。そのようにします (実は規格は構文規則と意味規則を定義していないという意味不明なことになっているので、微妙なのですがごまかして書くことにします)。 Re: 1.2/1.3 空白・装飾
@saki7 ありがとうございます。取り敢えず好きなようにやってみることにします。 Re: 1.1 ファイル名
@saki7 そうですね。下手に省略するのも分かりにくいので Re: 4.1 用語一覧
@saki7 承知しました。
たぶん、
の流れでしょうかね…。 参照ページ
@saki7 @yumetodo @usagi ありがとうございます。そのようにさせていただきます。 Re: 2.1 value category@yumetodo @usagi @saki7
取り敢えず暫定的に /lang/cpp11/rvalue_ref_and_move_semantics.md を参照しておきます
実は参照しているのは glvalue なので、仮に右辺値・左辺値の系列の名前を使うとしても、定着した名前はないのですよね (一般化左辺値?)。 Re: 3.1 処理系依存
@yumetodo 確かに…。conditionally-supported もですね。 「文化圏固有(locale-specific)」と「条件付き対応構成(?)(conditionally-supported constructs)」も追加します。 Re: 3.3 合法・違法
@yumetodo 承知しました。他に異論がなければ取り敢えずそのように編集してみます 執筆内容と管理者
@usagi 方針についてご説明くださりありがとうございます。既に "時間計算量" の議論の方でそのような雰囲気を感じておりました。むしろ、"時間計算量" の方で色々と我儘なことを書いてしまって恐縮です。 |
Re: 1.2/1.3 空白・装飾
今気づいたのですが、cpprefjp には索引 (index) の仕組みはありますか? つまり、以下のような感じの仕組みです。
そのような仕組みがなければ、結局その「分からない単語」に解説が用意されているのかされていないのか分からないし、解説が用意されているとしても何処にあるのか見つけられないので、結局ググる方が便利ということになってしまいます。或いは、索引を手動で管理するとそれはそれで整合性を保つのが大変です。 |
|
更新しました。 「提案(proposal)」の説明Re: 俯瞰図暫定的な図を追加しました 71c1a4d Re: 構成をフラットにすることについて診断情報は独立させました 0db0150 @saki7 確かに改めて見ると仰るとおりですね…。絡まっています (これでも大分ほどいたつもりだったのですが)。改めて並び替えたりしようとしましたが難しそうなので、説明の順番は保持したまま、色々試してみることにしました。 各段落の前に見出しをつけるだけで大分フラットな感じになりました (以下)。多分、これ以上フラットにはなりません。自分の知りたいところだけ読めば良いという感じで印象は軽くなりましたが、一方で実際に読んだ感触はむしろ関係性(背景・流れ)は理解はしにくくなった感じですね。個人的には、結局説明文は同じなのだからわざわざ切る必要はないかなという感じです。
また、診断対象規則・単一定義規則・診断情報などもそのまま箇条書きにするのも試してみましたが (以下)、これはないなという感じです。他の概念と並列関係にあるわけではないものについて、敢えて箇条書きにする意味はないかなという印象です。
やはり、僕は箇条書き+文章の方が断然良いように感じます。各々それぞれの形式の感触をお聞かせ頂ければと思います。 Re: 構文規則・意味規則整理しました bc8d505 Re: 1.2/1.3 空白・装飾英単語の周りの空白 4187628 Re: 1.1 ファイル名
Re: 参照ページ追加しました 8709b9d Re: 2.1 value category取り敢えずリンク追加 d916e08 ToDo:
|
|
とりあえず今の cplusplus-program-conformance-jp-svg2.zip を Windows 10, Firefox 57.0.2 で見ると
右下が窮屈 |
|
同じ環境のはずなのにこれだけ差があるとは・・・(自分の環境は游ゴシック体にしていますが、MeyrioやＭＳ ＰゴシックやIPAゴシックでもそれは再現できませんでした) |
フォントの種類やサイズなどいろいろ設定しています． |
|
@e-kwsm それはそうと編集用のベクター情報ファイルをどこかに持っておきたいところですが、さてどこに置くべきなんでしょう？ |
|
cpprefjp/imageリポジトリに用語用のディレクトリを作って、ラスター画像と同じところにでも置いていただければ。 |
それについてなのですが cpprefjp/image の中を覗いてみた所、
から、直接 |
|
@faithandbrave |
|
@yumetodo 一応 |
|
オープンソースのツールしか使ってはいけない、という縛りはないので、Power Pointを持っている人が編集作業すればよいかと思います。 |
特に問題がなければ現時点で Merge して頂いて問題ありません |
議論は #505 ref: - #485 - cpprefjp/site_generator#52 - #493 - #505
|
rawファイルのURLが変わったようなので、順次githubusercontentに置き換えたほうがよさそうですね。 |
|
マージしました。執筆していただいた @akinomyoga さん、レビューに参加していただいた方々、ありがとうございます。 |
|
@usagi さん、@yumetodo さん、@faithandbrave さん、@e-kwsm さん、そして (今は去りし) @saki7 さん 、長々と議論につきあってくださりありがとうございました。 |
6 participants
Resolve #489
原稿のプレビュー (2017-12-26 10:37 更新):
取り敢えず可能な限り簡潔に書きました。先に構成などを確定させてから、その後で細かい説明 (鼻から悪魔の話題や、コード例などを含む) は追加する予定です。