おまえらの議事録書く環境を改善してやるよ

おまえらの議事録書く環境を改善してやるよ

私が所属している香川大学SLP-KBITでは，独特な書式で議事録などが書かれる． メーリングリストに流れる内側向けのものも全てこの書式だ． この書式は，tmng-format （読み:たまねぎふぉーまっと） と言われ， 古くから自サークル内で使われている． 今回は，その独自ドキュメント書式である tmng-format に焦点を当て 書く環境の改善方法などについて触れる．

tmng-format 概要

Tmngフォーマットは，いわいる全角文字の記号を中心に採用した書式である． 具体的には，以下のようである

■ s00t000 個人報告 0000.00.00(月)

● 課題ページ

◎ 技術検討

○ 完了 [1180] Sample A
○ 新規 [1190] Sample B

● 研究の進捗

◎ 研究会合

ナバラ州は、スペインの 自治州である。1982年に発足。
歴史的背景が考慮されて大きな自治権を得ており、スペインの全17自治州の
うち課税自主権が認められているのはナバラ州とバスク州のみである。

● 今週の予定

◎ ゼミ

○ 0000.00.00(火) {ゼミ} 定例会合 [Semi] 16:30-17:00 (個人報告)
○ 0000.00.00(火) {ゼミ} 研究会合 [Semi] 15:00-16:30 (システム設計、データ分析)
○ 0000.00.00(金) {ゼミ} 定例会合 [Semi] 17:30-18:00 (週間予定)

● 備考

■ はタイトル

■ はメール本文最上部に書かれる．例を挙げると

■ s00x000 [SLP] 事務連絡 2017.01.10 (月)

のように使われる．

プロジェクトスコープなメールの場合，

■ s00x000 [SLP] {ETR} 事務連絡 2017.01.10 (月)

のような書式になる．中括弧の中がプロジェクト名だ．

● は大見出し

● の要素は，本文を持たず，小見出しをいくつか持つ．

例外的に、 ● 備考 などは，本文を持つことができる．

◎ は小見出し

◎ の要素は，● の要素の下にしか書くことができない． また，本文を持つことができる要素である．

○ はリスト

スケジュールや、要素の列挙には ○ を使う． 本文中で，同じ粒度の要素を列挙するときは，・を使うこともある． ○ による列挙は，予定や、課題ページ *1 などが多い．

  • *1 : 課題ページとは，卒業論文のためやシステム開発中に記録を示す， ドキュメントのことを指している．工夫をしないと（諸事情から）HTMLをべた書きすることを強いられる．

tmng-format を楽に書くための onion

github.com

f:id:maxmellon:20171130195314g:plain

端的に概要を書くと，tmng-format で書かれたドキュメントの書式チェックやよくあるミスを チェックしてくれるlinterだ．○ と ◯ の違いや，，と． を 、と。に 自動で置き換えたりしてくれる．

実装は，go言語で行った．これが自分が初めて書くgo言語なので，びしばし レビューしてほしい．

機能一覧

まだ，実装途中ということもありチェックできる項目はそこまで多くない． ぜひ，SLPのメンバは積極的にプルリクエストを送ってきてほしい．

  • 全角文字の置き換え
  • 行頭、行末空白の削除
  • よく間違える記号の自動置換
  • 課題ページのステータスラベルのチェック
  • ラインの横幅

設計

ほとんど思いつきで作ったので，かなり雑だけれど一応．

f:id:maxmellon:20171130202232p:plain

基本的には，上にある図の通りである． 実は，onionはtmngparserに依存しており，tmngparserを用いてastを生成している． ファイルを直接lintするのではなく，astをベースにチェックを行っている． これは，よくあるlint系のツールと同じだと思う． 特に，何かを参考にしたわけではないので，結構実装がグダってるかもしれない．

github.com

parserは関数だけでなく，CLIも一応提供しており，goが書けない人でも バイナリを通して利用できるようになっている．parserを分離して疎結合にしたことに よって，色々さらに遊ぶことができるようになっている．

例えば，

f:id:maxmellon:20171130202243p:plain

HTMLへのエクスポートができたり，マークダウンからのインポートが実現できる．

tmngparserを分離した背景には，もう一つあり，大量の過去のドキュメントを これを使ってマークダウンやHTMLに一括変換し，モダンなドキュメント管理 アプリケーションに以降したいという思いが大きい．

そして，それを自分で全部やるのは気が進まないので，go言語で実装し いろんなインターフェース，osから気軽に拡張が作れるようにしようと考えた．

onion の vim 連携

linterをコマンドラインで叩くのは僕は面倒に感じる． そこで，自分はVimで普段このドキュメントを書いているので， onionとVimを連携できるようにした．

なるべく，依存を小さくしたいという気持ちがあったので， プラグインなしでも連携できるように，makeprg と quickfix を使おうと考えた．

プラグインなしで利用する場合は，

set makeprg=onion \-f=errorformats\ %
set errorformat=%f\|%l\ col\ %c\|\ %m

を設定に追加すれば良い．

makeprgの設定やsyntaxハイライトの設定をすべて込めた Vim plugin がこれである．

github.com

下画面のエラメッセージ上でエンターキーを押すと，該当位置にジャンプすることができる．

このプラグインを入れて，go get -u github.com/TomiLabo/onion/cmd/onion すれば 連携できる．まだ，あまりしっかり動かしていないのでおかしな動作があれば， プルリクエストやissueを歓迎する．

Vimは，エラー箇所へのジャンプなども手軽にできるので素晴らしいと思う． （おそらく他のエディタもできるだろう）

今後の課題

ここ数週間，いそがしく全く触れていないのでなおしたいけど直せてない箇所を 今後の課題とする．

  • 1 : ルールが少ない ルールが少ないので，ありがたみが少ない． もっとルールを増やしたい．ただその前にリファクタリングをしてインターフェイスを 統一したほうがよさそうだ．

  • 2 : fixer と linterが対応していない linter という interface を実装し，lint() と fix() を実装するようにインターフェースを統一したい．fix() しない場合は，デフォルトの挙動で．（こいうことはgoでもかけるのだろうか？）

  • 3 : astが持っている情報が少ない，構造が平 今のところ，木構造と名乗っているのに葉がない．大見出しと小見出しに対して 親子関係をつけたり，リスト項目の中に日付要素や，箇所情報などを子要素としてもたせたい． メタ情報として送信日や，記述者なども取得できるようにしたい．これの意図としては， 研究室内のbotがメールから情報を取得するとき泥臭い正規表現を書いているからだ． もし，パーサーからきれいに情報がとれたら，そこの箇所の実装コードがよりクリアになるだろう．

  • 4 : test がない 本当は，この記事を書くまでにCI周りは整えておく予定だったが，忙しかったためにできなかった．テスト無いとメンテがだるくモチベが下がるので早いうちに書きたい．

  • 5 : emacs や Atom, VSCode との連携 だれかして

はじめて go を書いた感想

文法とかググりながらでもなんとなくかけて敷居の低さを感じた． 若干，エラーチェックのif文に冗長さを感じることはあるが， エラーが出たらすぐリターンという考え方は，逆にわかりやすいのではないかと思った．

また，エディタとの連携，とくにVimとの連携が充実しており，本当にストレスなく コードを書くことができた．

次は，goでWebApplicationなどを作りたい． 正月，実家に帰ったとかにでも．