FPGA開発日記

カテゴリ別記事インデックス https://msyksphinz.github.io/github_pages , English Version https://fpgadevdiary.hatenadiary.com/

「ドキュメント作成システム構築ガイド」を購入(RedPenをカスタマイズしてみる)

book

前のブログでもちょっと書いたけど。

ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]

ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]

ドキュメントと仕様書(一緒か)、そして実装は常に一体であるべき、というのは基本的な考え方。 ドキュメントから実装が生成される、実装からドキュメントが作られる、というのは究極の理想だけど、もうちょっとドキュメント作成が簡単になればね、ということで購入。

主に内容はMarkdownやAsciiDoc、さらに著者らが開発に参加しているRedPenなどの使用方法の紹介。GitHubによるドキュメント管理の方法からgitの使い方まで書いてあるけど、簡単すぎるので省略。 一番しっかり読んだのはRedPenの使い方の部分だ。キュメントを書くときはAsciiDocかSphinxを使うつもりだから、AsciiDocとAsciiDoctorの部分もしっかり読まなければならない。 とりあえず現状は今ある文章を校正しなければならないということでRedPenに注力。

RedPenで今ある文章を校正してみる

これは前回もやった。前回はネットの情報だけで試してみたけど、今回は書籍も買ったし、いろいろカスタマイズできるはずだ！

msyksphinz.hatenablog.com

トライしたのは、例によって数年前に翻訳したxv6のドキュメントである。

github.com

MingWでRedpenを使える環境を構築する

書籍の中では、RedPenのインストール方法としてMacOS XかLinuxしか書いていなかった。ちょっとー、Windows使っている人だってたくさんいるんだよ！むしろ、WindowsのWordか何かで書いている人たちをRedPenに移行させたいなら、Windowsでの環境構築手順をしっかりしないと意味ないんじゃないかなあ？大企業でMac使っているところなんて、聞いたことがない。

といっても、MingWをインストールしているので、特に困ったことはなかった。RedPenのパッケージをダウンロードして、パスを通し、Javaをインストールすればそれで終了だ。 MingWの.bashrcに、以下を記述していればそれで終了。

export PATH=/c/Program\ Files\ \(x86\)/Java/jre1.8.0_77/bin/:${PATH}
export PATH=~/work/redpen-distribution-1.5.4/bin:${PATH}
export JAVA_HOME=/c/Program Files (x86)/Java/jre1.8.0_77/

一文字の接続詞で死ぬほど怒られる

エラーの大半は"DoubledWord"という、文章内に同じ文字を連続して書いてしまった時のものだ。

chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "動作" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。
chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "し" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。
chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "し" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。
chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "て" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。
chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "いる" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。

でも、これはひどいんじゃない？単純にセンテンスを解析しているだけとはいえ、これは直しようが無いよ？

最初は最小限のエラーを出力するようにすべきか

以上のように、RedPenの出してくるエラーはあまりにも過剰だ。 なので、最初はRedPenのルールをかなり甘々に設定し、エラーが減ってくると少しずつ厳しくしていくのが良いのではないだろうか？

半角括弧を許可する

技術文書なら、半角括弧はOKでしょ！redpenのconfに、以下を追加する。

  <symbols>
    <symbol name="LEFT_PARENTHESIS" value="(" invalid-chars="（" after-space="true" />
    <symbol name="RIGHT_PARENTHESIS" value=")" invalid-chars="）" after-space="true" />
  </symbols>

最初はかなり戸惑ったのだが、ドキュメントを一生懸命読むとわかった。半角とか、特定の文字のためのルールが存在するのね。

RedPen 1.5 Documentation

f:id:msyksphinz:20160403015642p:plain

doubledwordのルールをかなり甘めに設定する

そうでないとこの大量のエラーは処理しきれない。下の例では、「読点、で、を」を文中に2回以上登場させても良い設定にしているが、もっと別の接続詞も追加しておくべきだろう。そうでないと何のために文章を校正しているのかわからなくなる。

    <validator name="DoubledWord">
      <property name="list" value="、,で,を" />
    </validator>

かなり粗削りなツールな印象。今後の発展に期待

というわけで、デフォルトで使ってみると、申し訳ないが「相当使い物にならない」。自分でカスタマイズして、適材適所で使っていくべきツールだと思う。

とはいえ、これだけ大量に怒られると、「普段どういう部分に意識して文章を書くべきか」というのくらいはちょっと分かったかな。投稿する前にちゃんと読み直せとか(笑)

もしくは、今はやりのディープラーニングで、学習させて適切な校正をしてくれるように進化してくれてもいいよ！