進捗どうですか
技術系サークルの皆さまこんにちは。夏コミ原稿書いてますか?私はまだです。
文章を書く心構えや書き方という話については他の人々が書いている技術的な文章を書くための1歩、2歩、3歩や技術的な文章を書くための第0歩 ～読者に伝わる書き方～を読んでもらうとして、ここでは文書フォーマットとエディタについて書きます。
文章を書く際にフォーマット選びは重要です。
私はこの2年ぐらい、雑誌原稿や技術同人誌、書籍原稿など技術系の文章に関わる際には多くの場合Re:VIEWというフォーマットで書いてきました。
Re:VIEWというフォーマット
Re:VIEWをご存知ない方も多いかと思います。ここでは簡単に紹介します*1。「Sphinxでよくね?」という方は多分それで良いので、タブを閉じて原稿へ戻りましょう。原稿しろ。
「Wordでよくね?」という方、一人で作業してかつレビュアーも立てない場合にはそれで良いので、タブを閉じましょう。原稿しろ。
複数人で分担して書くサークルや、書いたものを誰かにレビューしてもらうような場合は、原稿を書く前にもう少しお付き合いください。
Re:VIEWは、Markdown(含GitHub-flavored)よりもしっかりとした構文を持ち、入稿用PDFなどを比較的作りやすい、技術文書に適したプレーンテキストフォーマットです。
@kmutoさん、@takahashimさんを中心に、オライリー・ジャパン刊の書籍/電子書籍や達人出版会刊の電子書籍の執筆にて多くの利用実績があります。
多分Sphinxに近い立ち位置だと思っていますが、なにぶんSphinxについてほとんど知らないのでイメージだけです。
個人的には
- 技術文書でよくあるレイアウト面の需要にほどよく応えてくれる程度に表現力のある構文
- 行番号付きリストとか、コマンド入力ブロックとか、図版の番号振りと参照自動更新とか、章/節間の参照とか脚注あたりが特にラクで良いです
- PDF、HTML、EPUBへの出力がサクッとできる点
- Wordよりもdiffを確認しやすい点
- GitHubのprivate repoに原稿を置いて、コミットされたRe:VIEWのファイルをピアレビューしたり、原稿のpushをトリガーとしてPDFの自動ビルドをおこなっている同人サークルもあると聞きます
- 適当にフィルタしてざっくり情報を拾い出すのが簡単な点
- 表記ゆれを疑った時に雑にgrepで確認できるのはとてもラクです
他にもメリットは多いのですが、そのあたりの一部はblogをRe:VIEWで書くことを考えるを参照してください。
ちなみに、このblogもRe:VIEWで書いて(図1)HTMLへ変換したものをBloggerへ流し込んだものです。
図1 Re:VIEWで書いたblogの原文
さて、あるフォーマットで文章を書く際に環境は重要です。
[*1] Re:VIEWはやっぱりぐぐらびりてぃが低いので、詳細は「kmuto review」でぐぐるのが定番です。
文章を書く環境の重要性
しばらく前まで、私はRe:VIEWでの文章作成にMacVim+Vim用シンタックスハイライト+保存時フックでのHTML出力(自前)+Firefox(HTMLプレビュー用)を使っていました。しかし、ここ半年ほどはAtomとAtom用のRe:VIEW構文サポートパッケージであるlanguage-review(@vvakame作)を使っています(図2)。
図2 Atom+language-reviewで文書編集している様子
図3 Atom+language-reviewがLintをかけてくれるところ
[*2] コマンドラインからは適当に apm install language-review で入るようですね
環境に手を入れられることの重要性
Atomは「21世紀の、ハックできるエディタ」を標榜するだけあって、かなり深いレイヤまで簡単にソースコードを追えます。そして、language-reviewはオープンソースで開発されていて、誰でもソースへアクセスできます。
私も、しばらく前からlanguage-reviewの中身を調べ、手を加えてはPRをこさえるようにしています。この話は長くなるので別のエントリにまとめますが、いじるの自体がなかなか楽しく、そして実用的という一粒で二度美味しい感じです。
まずは使ってみて、なんじゃこりゃーーーーと思った箇所についてはぜひissueを立ててください。きっとよくなっていきます。
0 件のコメント:
コメントを投稿