feat: 注釈・出典記法のルール化および適用 by yumetodo · Pull Request #509 · cpprefjp/site

yumetodo · 2017-12-27T15:25:46Z

#505 にて議論も収束したと判断したので、ルールの文案を作成した。

(インターネットという人権が乏しい世界に向かうため、2017/12/28午後から2018/1/3午前まで反応が鈍くなります、問題があれば、ここに書き込んだ上で、直接このbranchをいじって構いません)

ref:

Resolve #505

議論は #505 ref: - #485 - cpprefjp/site_generator#52 - #493 - #505

akinomyoga · 2017-12-27T15:31:04Z

+|------|----------------|----------------|--------------|------------|
+| 注釈 | `[注N]`        | `N. ^`         | `note_ref-${N}` | `note-${N}`   |
+| 出典 | `[N]`          | `N. ^`         | `cite_ref-${N}` | `cite-${N}`   |
+


以下に例を示す または ### 例 などの文言が欲しい。

akinomyoga · 2017-12-27T15:33:49Z

+|      | 参照元の見た目 | 参照先の見た目 | 参照元のid   | 参照先のid |
+|------|----------------|----------------|--------------|------------|
+| 注釈 | `[注N]`        | `N. ^`         | `note_ref-${N}` | `note-${N}`   |
+| 出典 | `[N]`          | `N. ^`         | `cite_ref-${N}` | `cite-${N}`   |


[注N] や [N] ではなくて、実際の上付きも反映して ^[注N] や ^[N] となっていた方が分かりやすい。

akinomyoga · 2017-12-27T15:34:52Z

+
+本文中に参照を貼り、ページ最下部に「注釈」「出典」の項を作ってそこに注釈・出典を書く。
+
+- `N`: 1から始まる連番


以降で使われている ${N} という表記は通じない可能性があるので、ここで「N または ${N}」とするか、以降で使われている ${N} は単に N に置き換える

akinomyoga · 2017-12-27T15:41:02Z

+
+表の中のみの事柄について注釈をつけるときに検討するべき注釈記法がこれだ。
+
+表中に参照を貼り、表の直後に注釈・出典を書く。


議論を掘り返すようで済まないのですがもしかすると行き違いがあるかもしれないので。

表の直後に注釈・出典

私が「表の注」で意図したのは「表の読み方」についての注釈でした。この種類の注釈 (^†N) と通常の注釈 (^[注N])・出典 (^[N]) は混在して表の中に現れることを許し、通常の注釈・出典はページ全体の ## 注釈/出典 または節の ### 注釈/出典 に記述することを想定していました。

cpprefjp では通常の注釈・出典に関しても、それが表の中だけの事柄であれば表の下部に混ぜて注釈・出典を記述するということにしますか。

あ、それは読み違えていました。

「表の読み方」についての注釈で

それに書き換えます。

akinomyoga · 2017-12-27T15:41:40Z

+>| std::list | (O(n)<sup><a id="note_ref-t1-1" href="#note-t1-1">†1</a></sup>) | O(1) |
+>| bar | O(1) | O(1) |
+>| baz | O(1) | O(1) |
+>| hoge | (O(n)†) | (O(n)†) |


ここの † も同じ意味なので ^†1 (リンクは貼らなくても良い)

面倒だし説明上なくても支障ないので123行目削ります。

akinomyoga · 2017-12-27T15:43:49Z

+
+* [cpprefjpにおける注釈・出典の貼り方](./cite_note_ref.md)
+
+それ以外に本サイト内で使用しているhtmlタグは以下です：


どうも start_editing.md の既存の問題のようですが、html / HTML が混在しているので HTML に統一?

HTMLのほうが良さそうですね、ついでに直します

akinomyoga · 2017-12-27T15:51:29Z

+
+のようにする。
+
+出典の本文は`cite`タグで囲う。


出典の本文はciteタグ

出典の本文にページタイトル・書籍タイトルなど以外の情報 (著者名や、ページ番号、章・節番号など) もつける場合はどうでしょうか。例えば、

^{^} 【Minecraft】ありきたりな工業と魔術S2 Part01【ゆっくり実況】 - ニコニコ動画、再生位置 20:17 (2017-12-28 0:46 JST 閲覧)

的な形にしたいとしたら (いい加減な例ですみません)、<cite>～</cite> で囲むべきなのは作品名 (ページタイトル) たる 【Minecraft】ありきたりな工業と魔術S2 Part01【ゆっくり実況】 - ニコニコ動画 の部分だけなのではという気がします。

日本語の斜体は可読性を書くので使いたくないです。それはそうとたしかに出典の一般的な要求を満たしていない例でしたね、直します。

斜体はただの例として出したものなので何でもよいです。

しかし <cite>～</cite> の既定の CSS は Chrome も Firefox も font-style: italic; で cpprefjp の CSS でも上書きされていないようです。なので、斜体を使わないようにするとしたら、cpprefjp の CSS も同時に弄る必要がありますね…。

追記 font-style: italic; で日本語が斜体になるかならないかはフォントに依存します (斜体になるフォントもあればならないフォントもあります)。

yumetodo · 2017-12-27T17:38:55Z

@akinomyoga 修正しました

akinomyoga · 2017-12-27T17:41:22Z

ありがとうです

faithandbrave · 2017-12-28T02:19:53Z

+### 例
+
+```md
+| コンテナ | ○○操作の計算量 | ××操作の計算量


ヘッダの閉じが抜けてるみたいです。ひとつ下の表も同様です。

faithandbrave · 2017-12-28T02:23:28Z

一件だけ小さな指摘をしましたが、そこだけ修正したらマージしてもらって大丈夫です。

yumetodo · 2017-12-28T02:59:26Z

修正したのでMergeします。

akinomyoga · 2017-12-28T04:54:40Z

@yumetodo 今標準規格と処理系 - cpprefjp C++日本語リファレンスを確認した所 <cite>～</cite> で囲まれたところが、(手許の環境では少なくとも) 日本語の斜体で表示されているのですが、

一方で、日本語の斜体は可読性を書くので使いたくないです。 by @yumetodo

という意見もあります (私自身は斜体が良いのか悪いのかについては今のところ中立)。cpprefjp で <cite> の CSS を上書きするなどの対策の議論があれば Issue/PR を投げると良いかもしれません。

yumetodo · 2017-12-28T05:41:46Z

まあ、私以外の人からそういう話が聞こえたらにしていいかなと思ってます。

faithandbrave · 2017-12-28T06:10:05Z

斜体は、英語文章内では主に強調のバリエーションとして使われますが、日本語文章内で強調を目的に斜体を使用すると目立ちません。そのため、太字以外の強調のためには、カギカッコが採用されることが多いです。
<cite>タグは引用を意味するタグですが、GitHubのコメントでもQiitaでも、引用文章は斜体になっていないようです。

ちなみに、cpprefjpのサンプルコードは、CSSのデフォルトでコメントコードが斜体になっていましたが、斜体をやめています。(読みにくいという理由で)

faithandbrave · 2017-12-28T06:12:34Z

ちなみに、cpprefjpのサンプルコードは、CSSのデフォルトでコメントコードが斜体になっていましたが、斜体をやめています。(読みにくいという理由で)

これはGoogle SitesからGitHub Pagesへ移行する際の初期実装の段階で、私と @melpon の間で議論して決めたことなので、議論ログは残っていません。

akinomyoga · 2017-12-28T06:14:57Z

鉤括弧で囲むというのは良さそうですね。現在の斜体よりはそちらの方が良さそうに思われます。

yumetodo added 2 commits December 28, 2017 00:16

feat(cite_note_ref): 注釈・出典記法についてルール化

4bcf218

議論は #505 ref: - #485 - cpprefjp/site_generator#52 - #493 - #505

fix(implementation): aplly new cite_note_ref rule

8efb091

yumetodo requested a review from faithandbrave December 27, 2017 15:25

yumetodo self-assigned this Dec 27, 2017

yumetodo added the feedback-needed label Dec 27, 2017

yumetodo changed the title ~~feat: 注釈・出典記法のルール化および適応~~ feat: 注釈・出典記法のルール化および適用 Dec 27, 2017

akinomyoga requested changes Dec 27, 2017

View reviewed changes

yumetodo added 5 commits December 28, 2017 02:02

chore: s/html/HTML/

51c0e84

fix(cite_note_ref): satisfy cite requirement

0adbf0f

fix(cite_note_ref): remove dest text

45a6204

fix(cite_note_ref): fix description about table-note-syntax

69e7ebc

refactor(cite_note_ref): booooot readability

b78a4bc

akinomyoga approved these changes Dec 27, 2017

View reviewed changes

fix(implementation): re-apply rule

ce379ad

faithandbrave reviewed Dec 28, 2017

View reviewed changes

fix(implementation): fix markdown table syntax

23eb4b1

yumetodo merged commit ba18216 into master Dec 28, 2017

melpon deleted the feat/rule/cite_note_ref branch January 17, 2018 09:26

yumetodo mentioned this pull request Mar 7, 2018

Visual C++ 製品名を修正、及びRC除去 #525

Merged

yumetodo mentioned this pull request May 13, 2018

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

Closed


		本文中に参照を貼り、ページ最下部に「注釈」「出典」の項を作ってそこに注釈・出典を書く。

		- `N`: 1から始まる連番


		表の中のみの事柄について注釈をつけるときに検討するべき注釈記法がこれだ。

		表中に参照を貼り、表の直後に注釈・出典を書く。


		* [cpprefjpにおける注釈・出典の貼り方](./cite_note_ref.md)

		それ以外に本サイト内で使用しているhtmlタグは以下です：


		のようにする。

		出典の本文は`cite`タグで囲う。 No newline at end of file

Conversation

yumetodo commented Dec 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

akinomyoga Dec 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yumetodo commented Dec 27, 2017

Uh oh!

akinomyoga commented Dec 27, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

faithandbrave commented Dec 28, 2017

Uh oh!

yumetodo commented Dec 28, 2017

Uh oh!

akinomyoga commented Dec 28, 2017

Uh oh!

yumetodo commented Dec 28, 2017

Uh oh!

faithandbrave commented Dec 28, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

faithandbrave commented Dec 28, 2017

Uh oh!

akinomyoga commented Dec 28, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yumetodo commented Dec 27, 2017 •

edited

Loading

akinomyoga Dec 27, 2017 •

edited

Loading

faithandbrave commented Dec 28, 2017 •

edited

Loading