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-widthorg-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)


本日もお読みいただき、ありがとうございました。参考になれば嬉しいです。