- org2elcomment 20170324.245(in MELPA)
- Convert Org file to Elisp comments
概要
今では多くのelispパッケージがGitHubで開発されています。
GitHubではREADMEを書くことでリポジトリのトップページにそれが載るようになっています。
READMEはorg-modeで書く(README.org)ことができます。
これは我々Emacsユーザにとっては朗報ですよね。
一方で、elispファイルの方でもCommentaryセクションで説明を書く必要があります。
ここでREADME.orgと別の内容を書いていたら、説明の二重化になり管理に問題が出てきます。
そこで登場するのがorg2elcomment.elです。
これを使えばカレントバッファのorgファイルをelispのCommentaryのコメントに変換してくれます。
つまりREADME.orgを更新した後にM-x org2elcommentを実行すれば自動的にCommentaryがREADME.orgの内容になるわけです。
インストール
パッケージシステムを初めて使う人は
以下の設定を ~/.emacs.d/init.el の
先頭に加えてください。
(package-initialize) (setq package-archives '(("gnu" . "http://elpa.gnu.org/packages/") ("melpa" . "http://melpa.org/packages/") ("org" . "http://orgmode.org/elpa/")))
初めてorg2elcommentを使う方は
以下のコマンドを実行します。
M-x package-install org2elcomment
アップグレードする方は、
以下のコマンドでアップグレードしてください。
そのためにはpackage-utilsパッケージが必要です。
M-x package-install package-utils (初めてアップグレードする場合のみ) M-x package-utils-upgrade-by-name org2elcomment
使用例
試しに/tmp/test.elを作成し、autoinsertによるヘッダが挿入された状態にします。
;;; test.el --- org2elcomment test -*- lexical-binding: t; -*- ;; Copyright (C) 2016 rubikitch ;; Author: rubikitch <rubikitch@ruby-lang.org> ;; Keywords: ;; This program is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with this program. If not, see <http://www.gnu.org/licenses/>. ;;; Commentary: ;; ;;; Code: (provide 'test) ;;; test.el ends here
そこでorg2elcommentのREADME.orgでM-x org2elcomment RET /tmp/test.el を実行すると、/tmp/test.elは以下の内容に変わります。
;;; test.el --- org2elcomment test -*- lexical-binding: t; -*- ;; Copyright (C) 2016 rubikitch ;; Author: rubikitch <rubikitch@ruby-lang.org> ;; Keywords: ;; This program is free software; you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with this program. If not, see <http://www.gnu.org/licenses/>. ;;; Commentary: ;; _______________ ;; ;; ORG2ELCOMMENT ;; ;; rubikitch ;; _______________ ;; ;; ;; Table of Contents ;; _________________ ;; ;; 1 Overview ;; 2 Usage ;; 3 Customization ;; ;; ;; Convert `org-mode' file to Elisp comments. ;; ;; ;; 1 Overview ;; ========== ;; ;; This simple package is mainly used for Elisp package writers. After ;; you've written the `README.org' for your package, you can use ;; `org2elcomment' to convert the org file to Elisp comments in the ;; corresponding source code file. ;; ;; ;; 2 Usage ;; ======= ;; ;; Make sure your source code file has `;;; Commentary:' and `;;; Code:' ;; lines. The generated comments will be put between these two lines. If ;; you use `auto-insert', it will take care of generating a standard file ;; header that contains these two lines in your source code. ;; ;; In your Org file, invoke `org2elcomment', select the source code file, ;; and done! Now take a look at your source code file, you can see your ;; Org file has been converted to the comments in your source code file. ;; ;; ;; 3 Customization ;; =============== ;; ;; Behind the scenes, this package uses `org-export-as' function and the ;; default backend is `ascii'. You can change to whatever backend that ;; your org-mode export engine supports, such as `md' (for markdown): ;;; Code: (provide 'test) ;;; test.el ends here
もちろん、README.orgを更新して再実行した場合は、以前の内容が消され、新しい内容が反映されます。
前の内容が残ったりはしません。
カスタマイズしている人は注意!
org-ascii-text-width や org-export-default-language を変更している人は、以下のアドバイスを使う必要があります。
org-ascii-text-widthが長すぎる場合は80桁を飛び出してしまいますし、org-export-default-languageをjaにしている場合はTable of Contentsが「目次」と出てきてしまいます。
(defun org2elcomment--export-settings (&rest them) (let ((org-ascii-text-width 72) (org-export-default-language "en")) (apply them))) (advice-add 'org2elcomment :around 'org2elcomment--export-settings)
本日もお読みいただき、ありがとうございました。参考になれば嬉しいです。