From 701a7ec0b43d9ec444641c488efcdde2200ec74b Mon Sep 17 00:00:00 2001 From: Syohei YOSHIDA Date: Fri, 11 Oct 2013 23:17:47 +0900 Subject: [PATCH 1/2] Add package format page --- tips/package/format.md | 103 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 tips/package/format.md diff --git a/tips/package/format.md b/tips/package/format.md new file mode 100644 index 00000000..fce554c7 --- /dev/null +++ b/tips/package/format.md @@ -0,0 +1,103 @@ +--- +layout: page +title: "パッケージフォーマット" +description: "Package Format" +package: true +category: "package" +tags: ["package", "tips"] +--- +{% include JB/setup %} + +## 概要 +Emacs Lispのパッケージを配布する際は, 公式のパッケージフォーマットに +従うべきです. ここではパッケージのフォーマットについて示します. + + +## 1行目はパッケージファイル名とパッケージの説明を書く +1行目には, パッケージ名とパッケージの説明を書きます. バッファローカル変数を +1行目に書いているものが稀にありますが, それは誤りです(ただし `lexical-binding`のみ例外). + + +以下に [anzu.el](https://github.com/syohex/emacs-anzu)を例として示します. + +```common-lisp +;;; anzu.el --- Show number of matches in mode-line while searching +``` + +パッケージ名と説明の間のハイフンは 3つです. 2つや 4つではありませんので +注意してください. パッケージの説明は `package-list-packages`で表示される +パッケージの概要となりますので, 手抜きせずわかりやすい説明を考えてつけましょう. + + +## メタ情報 +メタ情報は `Author`, `Version`, (依存があれば)`Package-Requires`を必ず書くように +しましょう(あとは `URL`もあると良いです). + +以下に `helm-gtags.el`を例として示します + +```common-lisp +;; Author: Syohei YOSHIDA +;; URL: https://github.com/syohex/emacs-helm-gtags +;; Version: 0.9.9 +;; Package-Requires: ((helm "1.0")) +``` + +## Commentaryセクション +Commentaryセクションはパッケージの説明, 簡単な利用方法, 設定方法について示します. +このセクションの情報は `package-list-packages`で `?`で見ることができます. +以下に `deferred.el`の Commentaryセクションの内容を示します. + +```common-lisp +;;; Commentary: + +;; 'deferred.el' is a simple library for asynchronous tasks. +;; [https://github.com/kiwanami/emacs-deferred] + +;; The API is almost the same as JSDeferred written by cho45. See the +;; JSDeferred and Mochikit.Async web sites for further documentations. +;; [https://github.com/cho45/jsdeferred] +;; [http://mochikit.com/doc/html/MochiKit/Async.html] + +;; A good introduction document (JavaScript) +;; [http://cho45.stfuawsc.com/jsdeferred/doc/intro.en.html] +``` + + +## バッファローカル変数の宣言 +上述の `lexical-binding`を除いたものについては, 後述のファイルの末尾を示すコメントの +前に宣言すると良いでしょう. +以下に `helm-mode.el`を例として示します. + +```common-lisp +;; Local Variables: +;; byte-compile-warnings: (not cl-functions obsolete) +;; coding: utf-8 +;; indent-tabs-mode: nil +;; End: + +;;; helm-mode.el ends here +``` + +### `lexical-binding`を定義する場合 + +`lexical-binding`は現在のところ, 1行目に定義しなければ意味がありません. +そのため `lexical-binding`を設定する場合は, 1行目のパッケージの説明の後に +書くようにしてください. 以下は `flycheck.el`の例です. + +```common-lisp +;;; flycheck.el --- On-the-fly syntax checking (Flymake done right) -*- lexical-binding: t; -*- +``` + +## ファイル末尾 + +ファイルの最後は `;;; ファイル名 ends here`とします. 以下に例を示します + +```common-lisp +;;; quickrun.el ends here +``` + + +## 補足 +これらをいちいち気にして書くのは大変なので, パッケージを書く際は[yasnippet](https://github.com/capitaomorte/yasnippet)や +[autoinsert](http://www.gnu.org/software/emacs/manual/html_node/autotype/Autoinserting.html)機能を使い, ひな形から +作成するのが良いでしょう. From 25c022a4a8c1ba103b2bc5332f3a1112f22116ae Mon Sep 17 00:00:00 2001 From: Syohei YOSHIDA Date: Sat, 12 Oct 2013 14:12:10 +0900 Subject: [PATCH 2/2] Update by comment Thanks eiel!! --- tips/package/format.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tips/package/format.md b/tips/package/format.md index fce554c7..0efdc62d 100644 --- a/tips/package/format.md +++ b/tips/package/format.md @@ -81,8 +81,8 @@ Commentaryセクションはパッケージの説明, 簡単な利用方法, 設 ### `lexical-binding`を定義する場合 `lexical-binding`は現在のところ, 1行目に定義しなければ意味がありません. -そのため `lexical-binding`を設定する場合は, 1行目のパッケージの説明の後に -書くようにしてください. 以下は `flycheck.el`の例です. +そのため `lexical-binding`を設定する場合は, 1行目のパッケージの説明に続けて書くように +してください. 以下は `flycheck.el`の例です. ```common-lisp ;;; flycheck.el --- On-the-fly syntax checking (Flymake done right) -*- lexical-binding: t; -*-