More than 5 years have passed since last update.

@i_completely_understand(completely understand)

エクセル方眼紙をやめてAsciiDoc大好きおじさんになろう

Last updated at 2018-12-08Posted at 2018-12-08

はじめに

皆さんはエクセル方眼紙が好きですか？
エクセル方眼紙で設計書や手順書を作っている現場は未だに多いですよね。
私は好きではありません。正直つらいです…。やめたいです…。

なにがつらいのか

目次を自動生成できない
項番を振り直せない
相互参照機能がない
条件付き書式や名前定義がすぐに壊れる¹
Gitホスティングサービスでプレビューできない
Git上で差分が見れない
好きなツールでgrepできない

本来の表計算ソフトとしての使い方をした上で補足文章を記載する程度に留めたり、
作りっぱなしでメンテしなくていいような場合はエクセル方眼紙でも別段かまわないのですが、
メンテを考えると上記のような問題点が浮き彫りになります。

大規模システムのテーブル構造に変更があったときの影響範囲調査のために
エクセルファイルを一つ一つ開いて確認したことがありましたが、あれは中々に地獄でした…。

代替案を考えてみる

昔からエクセル方眼紙やめたいなとずっと思っていたので、何年か前にも一度調べたことがあります。
ぱっと思いつくのはこの辺りでしょうか？

Word
HTML
LaTeX
MarkDown

Word

定型文書くならエクセル方眼紙ではなくこれ、と思っていた時代もありました。
ただ、エクセルと同じでテキストファイル感覚でgrepできないのがやっぱり辛いんですよね…。

良い点

目次の自動生成ができる
項番が振り直せる
相互参照機能がある

悪い点

スタイルがすぐに壊れる²
Gitホスティングサービスでプレビューできない
Git上で差分がみれない
好きなツールでgrepできない

HTML

一時期HTML+JavaScript+CSSで全てをなんとかしようと思っていた時代もあったのですが、
人間が読むのはつらいし下手にJavaScriptやCSS書くと管理が大変なことになるので諦めました。

良い点

Gitホスティングサービスでプレビューできる
Git上で差分がみれる
好きなツールでgrepできる
JavaScriptで計算できる

悪い点

記述量が多い
テキストから表示結果が予測しづらい
相互参照機能がない

LaTeX

学生時代の苦い思い出がよみがえる…！！
学会とかで使われているだけあってやはり高機能なのですが、記述量が多くどう描画されるかが自分にはわかりづらかったです。

良い点

目次の自動生成ができる
項番の振り直しが簡単
相互参照機能がある
文章校正ができる
Git上で差分がみれる
好きなツールでgrepできる

悪い点

記述量が多い
テキストから表示結果が予測しづらい
Gitホスティングサービスでプレビューできない
環境構築がもの凄く大変

MarkDown

比較的見やすいし書きやすいが、独自の拡張記法が多すぎてあるサービスで覚えた記法を別のサービスでは使えない。
拡張記法を使わないと表現力に乏しく実用に欠けるというのが使ってみた感想です。

良い点

テキストから表示結果を予測できる
Gitホスティングサービスでプレビューできる
Git上で差分がみれる
好きなツールでgrepできる
文章校正ができる

悪い点

標準仕様が規定されていない
独自拡張があまりにも多すぎる
目次の自動生成ができない³
項番の振り直しができない³
相互参照がない³

ということでどれも一長一短だな、というのがこれまでの自分の中の結論でした。

他にないのか

一度結論が出た後は、エクセル方眼紙つらいなーと悶々とした日々を過ごしながら業務をこなしていました。
そんな中でエクセル方眼紙の代替案としてこれなら活用できる！という記法を
半年ぐらい前にたまたま見つけたので紹介したいと思います。

AsciiDoc

MarkDownのような軽量マークアップ言語の一つで、ある程度読みやすく書きやすい構文になっています。
自動採番や相互参照も表現可能となっており、色々拡張されて使いやすくなったMarkDownみたいな印象を受けますが
登場時期は2002年、MarkDownが2004年登場だそうなのでAsciiDocの方が古かったりするみたいです。

GitHubやGitLabでも採用されていて、README.mdの代わりにREADME.adocを作っておくと
プロジェクトページ開いたときにREADME.mdみたいに説明文がプレビュー表示が可能です。

AsciiDocの良い点

比較的書きやすい
テキストから表示結果を予測できる
HTML,PDF,DocBook,Slideなど多彩な形式に変換できる
ファイルを変換しなくてもプレビューできる
目次を自動生成できる
自動採番できる
相互参照が利用できる
注釈表現が簡単に書ける
ファイルインクルード機能があり、長い文章を分割管理できる
PNGやSVGの画像を読み込める。HTMLやPDF変換時に埋め込みもできる
色んな言語のソースコードをハイライト表示できる
テーブルレイアウトの表現方法が多彩で、読みやすいように工夫できる
CSVやTSVのファイルをテーブルレイアウトとして利用できる
Font Awesomeのアイコンフォントが利用できる
カウントアップ機能がある
AsciiMathやLaTeXの数式表現が記載できる
Gitホスティングサービスでプレビューできる
Git上で差分がみれる
好きなツールでgrepできる

AsciiDocの悪い点

プレーンテキストほど簡単ではない
カウントアップはできるが、複雑な計算はできない⁴
記法の習得に時間がかかる⁵
環境構築が大変⁶

エクセル方眼紙で不満に思っていた部分がほぼ全て解消できます。

試しに書いてみる

1.サンプルソースをローカルに保存する

社内での宣伝用に自分で作ったテキストの、一部を抜粋したサンプルソースを載せてみました。
test.adocというファイルを作成し、下記のコードを貼り付けて保存してください。

test.adoc

= AsciiDoc完全に理解した
:author: i_completely_understand
:toc: left
:toc-title: 目次
:icons: font
:xrefstyle: basic
:sectnums:
:source-highlighter: highlightjs

== AsciiDocは軽量マークアップ言語
MarkDownと同じ軽量マークアップ言語なので、テキストから完成形を想像することが容易です。 +
記法さえわかれば、直感的に文章が記述できます。

[[browser,本稿]]
== ファイルを変換しなくてもプレビューできる
比較的読みやすいとはいえ、文章が長くなると完成形を想像することが難しくなってきます。 +
AsciiDocはHTML,PDFなどに変換することができますが、変換しなくともプレビューが可能です。 +

具体的なプレビューの方法については色々ありますが、ブラウザ拡張を導入するのが一番簡単です。

* Firefox +
https://addons.mozilla.org/ja/firefox/addon/asciidoctorjs-live-preview/
* Chrome +
https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia

[WARNING]
====
AsciiDocは適用するスタイルやテンプレートを変更することができます。 +
そのため、本稿で記載しているプレビューの結果と、最終的な出力結果が異なる場合があります。 +
例えば目次の左側に表示する設定は、<<browser>>で紹介している拡張機能では機能しません。 +
====

== HTML,PDFなど多彩な形式に変換できる
Asciidoctorの標準機能や拡張機能でHTML,PDF,DocBook,Slideなど多彩な形式に変換できます。 +
Pandocなどの外部ツールを組み合わせれば、MS WordやMarkDown,LaTeX形式などにも変換可能です。

変換作業の煩わしさも、RubyのGuard Gemなどのローカルファイルの更新監視機能や、 +
CircleCIなどのCIサービスの利用で自動化することにより解消できます。

== 目次を生成できる
`:toc:` と記述するだけで、見出しから目次が自動生成されます。 +
目次についての詳細は下記を参考にしてください。 +
http://ytyaru.hatenablog.com/entry/2018/02/07/000000[AsciiDocで目次を自動作成する(ToC) - やってみる]

== 自動採番できる
`:sectnums:` と記述するだけで、以降の見出しには自動で採番されます。 +
`:sectnums!:` と記述すると、以降の見出しでは採番されません。

== 相互参照が利用できる
`:xrefstyle:` を利用することで章や節、図、表番号などを本文中で流用することが可能です。 +
詳細については
https://asciidoctor.org/docs/user-manual/#customizing-the-cross-reference-text[公式マニュアル]
を参照してください。

== 注釈表現が簡単に書ける
`:icons: font` と記載した上で、下記のコードを書くことで注釈表現が簡単にできます。

コード例
....
NOTE: ノート

TIP: チップス

IMPORTANT: 重要事項

CAUTION: 警告

WARNING: 注意
....

NOTE: ノート

TIP: チップス

IMPORTANT: 重要事項

CAUTION: 警告

WARNING: 注意

詳細については
https://asciidoctor.org/docs/user-manual/#admonition[公式マニュアル]
を参照してください。

== アイコンフォントが使える
`:icons: font` と指定しておくだけで、手軽に
https://fontawesome.com/[Font Awesome]
のアイコンフォントを利用できます。 +
下記にアイコンフォントの一例を記載しておきます。

[source]
.コード例
----
icon:facebook-official[] icon:twitter[] icon:circle-thin[] icon:credit-card[] icon:firefox[] icon:edge[] icon:chrome[] icon:battery-2[] icon:file-o[] icon:file-photo-o[] icon:file-text-o[]
----

出力結果 +
icon:facebook-official[] icon:twitter[] icon:circle-thin[] icon:credit-card[] icon:firefox[] icon:edge[] icon:chrome[] icon:battery-2[] icon:file-o[] icon:file-photo-o[] icon:file-text-o[]

詳細については、
https://asciidoctor.org/docs/user-manual/#icons[公式マニュアル]
を参照してください。

QiitaだとAsciiDocのコードってハイライトされないので見辛いですね…。
SublimeText、VS Codeなど有名どころのエディタの拡張機能でハイライト表示できるので、ハイライト表示した後の画像を貼っておきます。

2.ブラウザのプレビュー用の拡張機能で表示してみる

下記の拡張機能を導入して、ブラウザでtest.adocを開いて見てください。
(※Chrome拡張の場合は、対象の拡張機能の設定項目にある「ファイルのURLへのアクセスを許可」にチェックを入れないと恐らく動きません。)

良い感じですね。

3.HTMLに変換してみる

AsciidoctorというRuby製のツールを使うと、AsciiDocファイルをHTMLファイルに変換できます。
AsciidoctorはRubyのパッケージ管理ソフトであるGemを使うと簡単にインストール可能です。

Windowsの場合

choco install ruby
gem install asciidoctor

chocoがよくわからない方はこちらの記事を参考にしてください。

Ubuntuの場合

sudo apt install ruby
gem install asciidoctor

インストールが終わったら、test.adocの存在するディレクトリ上で下記のコマンドを実行してみてください。
test.htmlが生成されるはずです。

asciidoctor test.adoc

test.htmlをブラウザで開いてみると、ちゃんと変換されていることがわかります。
ハイライト表示した元のテキストの文と見比べてみてください。
AsciiDocの可読性がかなり高く、表現力に富んでいる事が伝わるかと思います。

4.PDFに変換してみる

Asciidoctor PDFを使うことで、AsciiDocファイルをPDFに変換できます。

gem install asciidoctor-pdf --pre
gem install asciidoctor-pdf-cjk

インストールが終わったら、下記のコマンドを叩いてください。
test.pdfが作成されると思います。

asciidoctor-pdf -r asciidoctor-pdf-cjk test.adoc

PDFを開いて見るとこんな感じ。
デフォルト設定からそのままでも綺麗に表示されてますね。

使いどころ

設計書、手順書、議事録、業務マニュアルのような管理が必要な定型文書と相性がいいです。
HTMLやPDFに変換もできますが、上記でお試しで使ってみたとおり、FirefoxやChromeの拡張機能を利用すれば
ローカル上でも簡単にプレビューできるため、変換せずにそのまま管理、閲覧するのがいいと思います。

HTMLやPDFで納品が必要なプロジェクトの場合は、CIサービスを利用して自動ビルドされるような仕組みを作っておけば、
都度変換用のコマンドを叩くような悩みから解消されるかと思います。
AsciiDocのRuby実装であるAsciidoctorは、Maven,Gulp,Grunt等色々な仕組みで利用できるようなので、
各々の知見のある方法で変換の仕組みを実装することが可能です。

私の場合はたまたま自分が書きやすそうだと思ったRakeで変換の仕組みを実現しました。
ローカルの自動ビルドもGuard::Rakeでファイル更新の検知することで実現しています。

例としてRakefileとGuardfileの内容を記載しておきます。

Rakefile

# coding: utf-8
###############################################################################
# タイトル
#   AsciiDocビルド用Rakefile
#
# 説明
#   bookディレクトリ以下のAsciiDocのファイルを、指定のファイルに変換します。
#   変換したファイルはそれぞれ下記のディレクトリに出力されます。
#   ・htmlファイル : output/html
#   ・pdfファイル : output/pdf
#
# 使用方法
#   bundle exec rake
#     book/*.adocから、output/html/*.html,output/pdf/*.pdfを生成します。
#
#   その他の使用方法については、下記コマンドをご確認ください。
#     bundle exec rake --tasks
#
###############################################################################
# -----------------------------------------------------------------------------
# Build Html
# -----------------------------------------------------------------------------
namespace :html do
  desc "AsciiDocファイルから、HTMLファイルを生成する"
  task :build do

    # 出力先ディレクトリ生成
    FileUtils.mkdir_p("output/html/css")

    # CSSコピー
    cp_r "book/css" ,"output/html", {:preserve => true, :remove_destination => true}

    # AsciiDoc To Html
    # -a relative-ext : 別のAsciiDocファイルへの外部リンクをする際に利用する拡張子
    # -a data-uri : 画像ファイルを埋め込む
    # -a imagesdir : asciidoctor-diagramで生成される画像ファイルの保存先
    # -a linkcss : スタイルシートをHTMLに埋め込まない
    # -a stylesdir : スタイルシートの読み込み先ディレクトリパス
    # -a stylesheet : スタイルシートのファイル名
    # -D : 出力先ディレクトリ
    `bundle exec asciidoctor -r asciidoctor-diagram -a relative-ext=.html -a data-uri -a imagesdir=img -a linkcss -a stylesdir=css -a stylesheet=foundation.css -D output/html book/*.adoc`
  end
end

# -----------------------------------------------------------------------------
# Build Pdf
# -----------------------------------------------------------------------------
namespace :pdf do
  desc "AsciiDocファイルから、PDFファイルを生成する"
  task :build do

    # 出力先ディレクトリ生成
    FileUtils.mkdir_p("output/pdf")

    # AsciiDoc To Pdf
    # -a relative-ext : 別のAsciiDocファイルへの外部リンクをする際に利用する拡張子
    # -a data-uri : 画像ファイルを埋め込む
    # -a imagesdir : asciidoctor-diagramで生成される画像ファイルの保存先
    # -D : 出力先ディレクトリ
    `bundle exec asciidoctor-pdf -r asciidoctor-diagram -r asciidoctor-pdf-cjk -a relative-ext=.pdf -a data-uri -a imagesdir=img -D output/pdf book/*.adoc`
  end
end

# -----------------------------------------------------------------------------
# Clean, Clobber
# -----------------------------------------------------------------------------
require "rake/clean"
CLEAN.include("output/*")
CLOBBER.include("output/*")

# -----------------------------------------------------------------------------
# Default
# -----------------------------------------------------------------------------
task :default => ["html:build", "pdf:build"]

Guardfile

# coding: utf-8
guard 'rake', :task => 'default' do
  watch(%r{^book/.+})
end

HugoみたいなAsciiDocに対応した静的サイトジェネレータを利用して、
ソフトウェアの使用方法のページをGitHub PagesやGitLab Pagesに公開するような事も可能です。
この業界に関連するようなドキュメントにこだわらないで、AsciiDocで書いた料理のレシピを
黙々と載せる専用サイトみたいなのを作ってみても面白いかもしれませんね。

「AsciiDocいいね！」と思ったら

一緒にAsciiDoc大好きおじさんになりませんか。
導入までのハードルを低くするために、下記のような資料を作成して一緒に布教活動をしていきましょう。

エクセル方眼紙の利点・欠点の説明資料
AsciiDocの利点・欠点の説明資料
AsciiDocのプレビュー方法
AsciiDocの構文の説明資料
自動ビルドの仕組みについての資料
チュートリアル

導入資料をしっかり作って、仲間を増やして行けば行くほど、エクセル方眼紙からAsciiDoc移行へのハードルは低くなるはずです。
自分がいなくなっても資料を読めばわかるような、技術的負債にならないレベルのものを目指して行くのが理想です。

おわりに

記事投稿時点ではまだエクセル方眼紙からは脱却できてはいませんが、
社内の人をAsciiDoc沼に落とすべくAsciiDocで資料を書いては周りの人に薦めています。

道はまだ遠いですが、改めてエクセル方眼紙の問題点や代替案をどうすべきかについて考える良い機会となりました。
RubyのRも知らない状態でRakefileをいきなり書いてみたり、CIの仕組みを確認するためにGitLabで試してみたりと、
副次的に他の事にも触れるのが中々に面白いので走れるだけ走ってみようと思っています。

今回の記事では箇条書きになってしまい、良い点、悪い点の詳細な説明がしきれなかったので、
ゆくゆくは社内向け想定で作成している資料類(※まだ未完成)の外部公開も考えていきたいですね。
この手の資料であれば静的サイトジェネレータなどとも相性よさそうですし。

また、AsciiDocにどはまりした後で知ったのですが、Re:ViewやreStructuredTextやKARASなど
軽量マークアップ言語に分類される記法高機能な記法は他にも色々あるようなので、
落ち着いたらそちらも試してみたいですね。

参考リンク

AsciiDoc公式
http://asciidoc.org/

Asciidoctor公式
https://asciidoctor.org/

■AsciiDocの文法関連
脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレ - Qiita
https://qiita.com/tamikura@github/items/5d3f62dae55617ee42bb

Asciidoctor 文法クイックリファレンス(日本語訳)
https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/

なんと、Asciidocはソースコードをインポートできるよ！ - Qiita
https://qiita.com/v97ug/items/c5e4e5b8e985a6a44cf8

Asciidoctor 1.5.6 で :xrefstyle が新規実装 - Qiita
https://qiita.com/azarasi/items/9aa5a10d72a6c22f6523

AsciiDoc + VSCodeでかっこいい文書作る - Gaming Life
http://ai-gaminglife.hatenablog.com/entry/2018/11/13/232608

■CIの仕組みを利用して、AsciiDocから別の形式に変換する方法について書かれたもの
技術文書をAsciidoc で書いて、GitlabでCIしている話 - Qiita
https://qiita.com/ihgs/items/ca9330053d4b469f027a

Githubで書く電子書籍
https://azu.github.io/slide/individual/

■AsciiDocでスライドを作成する
スッとスライドを作れ！ | 社員ブログ | リグレックス株式会社 | REGREX Co.,Ltd.
https://blog.regrex.jp/2018/08/31/%E3%82%B9%E3%83%83%E3%81%A8%E3%82%B9%E3%83%A9%E3%82%A4%E3%83%89%E3%82%92%E4%BD%9C%E3%82%8C%EF%BC%81/

■AsciiDocを使って本を執筆した人達の活用法に関するお話しなどについて書かれたもの
JavaScript Promiseの本を書きました | Web Scratch
https://efcl.info/2014/0623/res3943/

執筆活動を支える技術 #ruby超入門 - Qiita
https://qiita.com/machu/items/4a133e83f58f82459e56

そもそも使っている事に気がついていないケースが大半を占める ↩
スタイルを意識して書いている人が残念ながらほとんどいません…。 ↩
素のMarkDown前提の話です。独自拡張で実装されているものはあるかもしれません ↩
プログラム言語じゃないから仕方ないんだけど、表計算ソフトであるExcelと比較なので… ↩
自分の体感だと任意のサービスの拡張MarkDown記法を一通り覚える労力ぐらいは必要だった ↩
プレビューやシンスタックハイライトするだけなら簡単。AsciiDocから色々なファイル形式に変換しようと思うと、途端に大変になる ↩

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up