make guideline

[vvakame]

サマリをここに随時更新していく
初期案はリポジトリに突っ込んでおきました(動かしてないのでコンパイルは通らないかも
https://github.com/prh/rules/blob/master/README.ja.md

[vvakame]

主に話題が刺さる人 @mhidaka @azu
ある程度方針が決まったら適当にコミット権渡して好き勝手やってくれーみたいな感じにしたい。

npmに出すとかprh側になんか仕組み作るとかやりたくなる可能性があるので主権は握っておきたいという気持ち。

[vvakame]

主にフォルダ構成とかファイル構成とかどうするの みたいな話をしたい。
話題も色々あるはず。

• 漢字の開きと閉じは組織毎に好みがだいぶ異なる気がするが統一的なファイルを作ってよいのか？
• 日本語のチェックでtypo辞書とそれ以外辞書に分ける必要があるのだろうか
• 商標系のルールは独立のフォルダを作る必要はないのでは…
• technical-term というフォルダ名が後々汎用性に欠けて困る予感がする
• rootディレクトリにファイル散らかすと成長した後クソ辛いとDTで学んだのでrootはなるべく綺麗にしたい
• reviewerはファイル単位で適当に決めていってPR来たら雑に対処したりすればいいですね(たぶん
• 共有ルール内部について組織間で齟齬が発生した場合どう調整するのか
  • 除外フィルタを書ける機能はやっぱ必要そう
  • 両者が同じくらい利益が得られる運用がすぐには思いつかないので一旦放置
• 何か実行ファイルが必要になったら scripts/ 配下にフォルダ切って置くという方針でいいすかね _scripts/ とか？

[mhidaka]

背景として書籍、主に同人誌や電子書籍の作成頒布、将来的な商業利用、出版系をターゲットにしてる @mhidaka より。どのように使っているかで要望がかわったり受け取り方が変わると思ったので先に立場を書いておきました。

構成への意見です（というかいろいろ考えてる内容を吐き出してるので結論は最後だけみてもらえるとわかりやすいとおもいます。）。

現在のTechBoosterという団体の運用では次の点が明確に分かれてない課題があります。
書籍を作るときに必要なLintと文章を書くときに必要なLintをひとつの techbooster.yml にまとめてしまっている状況です。これは本来なら分離しておきたいです。

• 書き間違い、typo対応のためのprh
• 商標、用語に関するprh
• 書籍としてのprh

管理、運用できる統一リポジトリがあれば有用だし、prhの開発者（vvakame）が立ててくれるなら乗っかる。というか現在も乗っかってる。

また校正という観点では次のような議論があります（ありました）。

• 漢字の開きと閉じは組織や用途でさまざま。またそれらの方針は両立しないケースが多々ある（編集者依存）
• 日本語としての正しさとして文法上の間違いは「間違い」の判定が難しい一方でtypoの検出にLintはとても有効（JustSystemsさんやRedPenがフォローしている分野）
• 商標、用語は正しく表記するしたほうがいい（誤解がなくなる）。しかしモバイルの文脈では「Android」ですが、一般名詞としてandroidもあるのでここも最終的にはカスタマイズが必要になる（ガンガン集める必要があるが用語はジャンルに依存するので確認が難しい）

一方で使いやすい形でメンテナンスしたい思いがあります。手間がかかるのは嫌われるので。

なので

• medium 各組織・団体のymlをホールド
• term 用語、商標管理（トレードマークを統合）
• language typo、開き、口語

とかはどうでしょうか。
また mhidaka が利用するのであれば 依存関係を組み合わせた各書籍用configがほしくなります。
現状 techbooster.yml だけインポートしている状態ですが将来的には →

book.config
  - term/mobile_term.yml
  - language/ja/typos.yml  
  - techbooster.yml

みたいな表現を使うもしくはこういう表現が出来るものがmedium/dojin.yml があると嬉しいです。
なお除外表現もほしいですが、同一ルールがあった場合のオーバーライドも欲しくなると思います（漢字の開きなどは一部だけ差があるときに除外すればいいが、用語が商標やtyposと被ってしまったときに再定義したいケースがありそうだなとおもいました。）

[vvakame]

よく考えたら本職の方々にも聞いたほうがよかった @takahashim @murashitas

[azu]

language

自然言語(言語コード的)だけじゃなくてプログラミング言語も扱いたいです。
例えば、ソフトウェアの世界だとfluxboxはあるけど、CSSの世界ではかなりの確率でFlexboxのtypoであるとかがあるので。
こうなった場合に、自然言語とプログラミング言語どちらが上かという問題がディレクトリ構造的に出てきたりしますが… (基本的にはプログラミング言語を上とした方が扱いやすい)

自分としては prh.yml は単なる辞書のフォーマット(処理系ではなく)として捉えているので、prh.ymlで文法のチェックはできないと思っています。(チェックするのはその辞書を扱う処理系になると思います)
辞書として一番ユースケースとありそうな"用語"は、コンテキストが細分化されていれば、大体のケースで正解があるので、言語のコンテキストは細かく分けたいです。

共有ルール内部について組織間で齟齬が発生した場合どう調整するのか

これは基本的に考えなくていい気がします。
自分がazu/prh.ymlを作ったときのモデルとして考えたのはgithub/gitignoreでそのファイル内で問題が起きなければいいんじゃないかなと思います。(medium/*は基本組み合わせるの無理な気がします)
prh/rules からユーザが使いたいものを手元にコピーして使うというものをイメージしてます。
(ここを補助するツールとしてgitignore.ioとかgiboみたいなものがあるという立ち位置)

ルールファイル間で維持するのが目的ならもうちょっとオピニオンのあるリポジトリを作ってやったほうがいいと思います。

漢字の開きと閉じ

これ一番扱いに困るやつですね。。
azu/prh.ymlを作った一番の理由は、毎回漢字の開きと閉じを定義したファイルをコピーするのがだるいから、git subtreeで取ってこれるようにしようと思ったのがメインです。
個人的には重複ありで、medium/*以下の媒体毎に考えてしまうのが一番平和そうな気がする。

何か実行ファイルが必要になったら scripts/ 配下にフォルダ切って置くという方針でいいすかね _scripts/ とか？

普通のディレクトリと区別付けたいので . か _ つけたいですね。

https://github.com/azu/prh.yml/blob/13f47dca03f7e3d353ed3062e52757fc0679771a/package.json#L7 みたいにCIでチェックだけは回したい。

[takahashim]

現状あまり強い意見はないのですが、種類（用語・商標か文法的な揺れか）によって分けるより、団体共通ルールと作品別ルールを分けるようにする方がわかりやすいかなと思っています。

[murashitas]

そんなに使いこなせているわけでもないので文脈を誤読していたら申し訳ないのですが……とエクスキューズしたうえで。

私も @takahashim さんとだいたい同様で、あまり種類で分けすぎなくていいかなと思っています。だいたい下記2つくらいでいいのかなと。（実際にはこれに加えて、必要に応じて個別の作品単体のものを各自の手元で作る……程度のイメージでしょうか）

• 共通でチェックしたいルール：typo、商標、用語などの「間違い」のチェック
  • 「×オブジェクト志向／○オブジェクト指向」「×Java8／○Java 8」みたいな
• シリーズ、媒体別のルール：漢字の閉じ開きなどの「表記統一」のチェック
  • 「×気をつける／○気を付ける」「×プルリクエスト／○Pull Request」みたいな

@mhidaka さんのおっしゃるところでいえば、たぶん前者が「書き間違い、typo対応のため」および「商標、用語に関する」にあたり、後者が「書籍としての」にあたるのかな。
後者をカテゴリ別に分けてimportで適宜取り込むようにもできなくはないかもしれませんが…… @azu さんのおっしゃるとおり、あまり現実的ではなさそうに思います。

---

ちょっと関係ない話になるのですが、この手の校正補助については（すくなくとも現状）どうしても「完全に置換」というのが難しく、人の目を入れていかなきゃいけない場面が多々出てくるのは避けようがないかなと思っています。ので、インタラクティブな置換みたいなのができたほうがいろいろ嬉しい場面は多そうです。

[vvakame]

レスポンスが遅くてすみません…
じわじわ目を通していきます…！

[vvakame]

prh.ymlで文法のチェックはできないと思っています

完全に同意。そこはツール作成者の勉強時間が精度に直結してきそうだという理解なので、ルールベースでできる範囲以外はprhではやりません。素直にRedPenとか使おうという気持ち。

インタラクティブな置換みたいなのができたほうが

現在てくぶ内部で誰がGUI作るか内ゲバしてます…！(誰かが作るとはまだ言ってない

[vvakame]

#2 にて意見を反映し組み替えました。
ルール自体の移植とCIの設定をやったらとりあえず運用してみましょうという感じ。
(じわじわやります)

[mhidaka]

拝見しました。

基本的に同意しています。運用に関しての質問なのですが、各mediaを使う際に
依存関係を解決しながらざっくり取ってくる方法（azuさんのいっていた gitignore.ioとかgibo） に相当するものがないとつらそうです。どうしましょうか。

[vvakame]

現在はそうなってないけど techbooster.ymlから必要なものをimportする構造にしようかと。

依存関係を解決しつつ複数のファイルを持ってくる方法は今のところgit submodule的な何かでいいかなーと思っています。
既存のprh packageにrulesをバンドルして配布するのもよさそうかなーという気持ち。

dtsm の構造流用でrule manager的なものを作るのもアリかもしれないけどめんどくさいしそこまでのものは現時点では必要ないなーという気持ちです。

運用用のサンプルはあったほうがいいかもしれない。
てくぶについては僕がメンテナンス用スクリプト書くだろうからどうとでもなるでしょという感じ。

[vvakame]

ざっくり整備して、npm run test で各定義がspec通過するか見るようにしました。
また、prh本体も https://github.com/prh/prh に移動させました。

現時点で問題が無ければ閉じようと思います。
次の日曜が終わるまではこのIssueはopenとしておきます。
月曜移行に気がついたタイミングで特に議論が増えていなかったら閉じます。