v1.2.4 auto update version in zero-pkg.el file;

- fix almost all checkdoc problems. the rest I don't know how to fix.
- add git pre-commit hook

.gitignore

 *.zip
 *.elc
+*.tar

Makefile

 VERSION := $(shell grep 'setq zero-version' zero-framework.el | cut -d'"' -f2)
 
+default: compile
+pkg-el:
+	sed "s/PKG_VERSION/$(VERSION)/g" zero-pkg.el.tpl > zero-pkg.el
 compile:
 	emacs -Q --batch -l zero-reload-all.el -f zero-rebuild -l zero-table.el -f ert-run-tests-batch
-zip:
+zip: pkg-el
 	git archive -o zero-el-$(VERSION).zip --prefix=zero/ HEAD
-pkg:
-	echo "Creating tar for package.el distribution..."
-	git archive -o zero-$(VERSION).tar --prefix=zero/$(VERSION) HEAD
-	echo "Done"
-.PHONY: compile zip pkg
+pkg: pkg-el
+# Note: install from tar is not working. install from dir does work.
+	@echo "Creating tar for use with M-x package-install-file"
+	git archive -o zero-$(VERSION).tar --prefix=zero-$(VERSION)/ HEAD
+	@echo "Done"
+install-git-hooks:
+	rsync -air git-hooks/ .git/hooks/
+version:
+	@echo $(VERSION)
+.PHONY: default pkg-el compile zip pkg install-git-hooks version

git-hooks/pre-commit

+#!/bin/sh
+set -e
+make pkg-el compile
+git add zero-pkg.el

operational

@@ -76,10 +76,14 @@ cd ~/lisp/elisp/zero/
     without converting char to string.
 
     (zero-table-can-start-sequence) can use this.
+** 2019-10-10 documents
+- Using of D-Bus
+  https://www.gnu.org/software/emacs/manual/html_mono/dbus.html
 
 * later                                                               :entry:
 * current                                                             :entry:
 ** 
+* done                                                                :entry:
 ** 2019-10-09 release zero-el on melpa
 melpa/CONTRIBUTING.org at master · melpa/melpa · GitHub
 https://github.com/melpa/melpa/blob/master/CONTRIBUTING.org
@@ -110,8 +114,10 @@ https://github.com/melpa/melpa/blob/master/CONTRIBUTING.org#preparing-a-pull-req
     checked github
     tag 1.2.0 already include these functions.
     https://github.com/magnars/s.el/blob/1.2.0/s.el
-  - TODO Note that there is no way to control the order in which files are
+  - Note that there is no way to control the order in which files are
     byte-compiled.
+
+    // seems my pkg compile just fine.
   - how to add autoload magic comments?
 
     https://www.gnu.org/software/emacs/manual/html_node/elisp/Autoload.html
@@ -131,9 +137,40 @@ https://github.com/melpa/melpa/blob/master/CONTRIBUTING.org#preparing-a-pull-req
     function reference. E.g., (seq-filter #'evenp list).
 
     I don't think this is necessary in my code.
-  - 
+  - do I need to fix all checkdoc problems for my pkg to be accepted by melpa?
+    search: melpa checkdoc one liner functions docstring
+
+    yes. they require all checkdoc problem be fixed.
+    Add recipe for a.el by dotemacs · Pull Request #4830 · melpa/melpa
+    https://github.com/melpa/melpa/pull/4830
+
+    how to specify minimum emacs version?
+    ;; Package-Requires: ((emacs "24"))
+  - DONE fix all checkdoc problems.
+    // except for zero-mode, which I don't know how to fix. all other problems
+    fixed.
+    - Disambiguate zero-mode by preceding w/ function,command,variable,option
+      or symbol. (C-h,f,e,n,p,q) [4 times]
+
+      this one is really confusing.
+      org-mode-map doesn't do this.
+      magit-mode-map doesn't do this.
+  - TODO how to add dbus as dependencies?
+    some emacs build may not have dbus.
+    (require 'dbus)
+
+    also how to only allow install on linux? when I test it dbus only worked
+    in linux.
+
+    what's the correct syntax for specifying dbus as dependency?
+    (dbus "1.0")
+    didn't work.
+  - search: package-install-file package--description-file: Wrong type argument: stringp, nil
+    search: emacs package-install-file install tar package--description-file: Wrong type argument: stringp, nil
+
+    install from dir is okay.
+    install from tar is not. Not sure what's wrong.
 
-* done                                                                :entry:
 ** 2019-10-08 support full-width characters and symbols.
 全角 半角
 

zero-framework.el

@@ -139,7 +139,7 @@ If item is not in lst, return nil."
 
 ;; zero-el version
 (defvar zero-version nil "Zero-el package version.")
-(setq zero-version "1.2.3")
+(setq zero-version "1.2.4")
 
 ;; FSM state
 (defconst *zero-state-im-off* 'IM-OFF)
@@ -211,9 +211,15 @@ Otherwise, next single quote insert close quote.")
 
 ;;; concrete input method should define these functions and set them in the
 ;;; corresponding *-func variable.
-(defun zero-build-candidates-default (_preedit-str _fetch-size) nil)
-(defun zero-can-start-sequence-default (_ch) nil)
-(defun zero-get-preedit-str-for-panel-default () zero-preedit-str)
+(defun zero-build-candidates-default (_preedit-str _fetch-size)
+  "Default implementation for `zero-build-candidates-func'."
+  nil)
+(defun zero-can-start-sequence-default (_ch)
+  "Default implementation for `zero-can-start-sequence-func'."
+  nil)
+(defun zero-get-preedit-str-for-panel-default ()
+  "Default implementation for `zero-get-preedit-str-for-panel-func'."
+  zero-preedit-str)
 (defvar zero-build-candidates-func 'zero-build-candidates-default
   "Contains a function to build candidates from preedit-str.  The function accepts param preedit-str, fetch-size, returns candidate list.")
 (defvar zero-build-candidates-async-func 'zero-build-candidates-async-default
@@ -611,13 +617,13 @@ N is the argument passed to `self-insert-command'."
   (zero-hide-candidate-list))
 
 (defun zero-focus-in ()
-  "A hook function, run when focus in a `zero-mode' buffer."
+  "A hook function, run when focus in a buffer."
   (when (eq zero-state *zero-state-im-preediting*)
     (zero-show-candidates zero-candidates)
     (zero-enter-preedit-state)))
 
 (defun zero-focus-out ()
-  "A hook function, run when focus out a `zero-mode' buffer."
+  "A hook function, run when focus out a buffer."
   (when (eq zero-state *zero-state-im-preediting*)
     (zero-hide-candidate-list)
     (zero-leave-preedit-state)))
@@ -646,7 +652,7 @@ N is the argument passed to `self-insert-command'."
     (define-key map [remap self-insert-command]
       'zero-self-insert-command)
     map)
-  "`zero-mode' keymap.")
+  "Keymap for `zero-mode'.")
 
 (defun zero-enable-preediting-map ()
   "Enable preediting keymap in `zero-mode-map'."

zero-pinyin-service.el

@@ -24,7 +24,9 @@
 (require 's)
 
 (defun zero-pinyin-service-error-handler (event error)
-  "Handle dbus errors."
+  "Handle dbus errors.
+
+EVENT, ERROR are arguments passed to the handler."
   (when (or (string-equal "com.emacsos.zero.ZeroPinyinService1"
 			  (dbus-event-interface-name event))
 	    (s-contains-p "com.emacsos.zero.ZeroPinyinService1" (cadr error)))
@@ -74,6 +76,7 @@ GET-CANDIDATES-COMPLETE the async handler function."
    "GetCandidates" get-candidates-complete :string preedit-str :uint32 fetch-size))
 
 (defun zero-pinyin-candidate-pinyin-indices-to-dbus-format (candidate_pinyin_indices)
+  "Convert CANDIDATE_PINYIN_INDICES to Emacs dbus format."
   (let (result)
     (push :array result)
     ;; (push :signature result)
@@ -92,7 +95,10 @@ GET-CANDIDATES-COMPLETE the async handler function."
 			  (:struct :int32 7 :int32 55)))))
 
 (defun zero-pinyin-service-commit-candidate-async (candidate candidate_pinyin_indices)
-  "Commit candidate asynchronously."
+  "Commit candidate asynchronously.
+
+CANDIDATE the candidate user selected.
+CANDIDATE_PINYIN_INDICES the candidate's pinyin shengmu and yunmu index."
   ;; don't care about the result, so no callback.
   (zero-pinyin-service-async-call
    "CommitCandidate" nil

zero-pinyin.el

@@ -16,7 +16,7 @@
 
 ;; To use this input method, add in Emacs init file:
 ;;
-;;   (add-to-list 'load-path "~/fromsource/zero")
+;;   (add-to-list 'load-path "~/fromsource/zero")  ;; omit if install from melpa
 ;;   (require 'zero-pinyin)
 ;;   (zero-set-default-im 'pinyin)
 
@@ -50,6 +50,7 @@
 ;;=====================
 
 (defun zero-pinyin-reset ()
+  "Reset states."
   (setq zero-pinyin-state nil)
   (setq zero-pinyin-used-preedit-str-lengths nil)
   (setq zero-pinyin-pending-str "")
@@ -76,7 +77,10 @@
   "If t, `zero-pinyin-build-candidates' will use `zero-pinyin-build-candidates-test'.")
 
 (defun zero-pinyin-build-candidates (preedit-str fetch-size)
-  "zero-pinyin-build-candidates synchronous version."
+  "Synchronously build candidates list.
+
+PREEDIT-STR the preedit string.
+FETCH-SIZE fetch at least this many candidates if possible."
   (if zero-pinyin--build-candidates-use-test-data
       (progn
 	(zero-pinyin-build-candidates-test preedit-str)
@@ -89,7 +93,12 @@
       (cl-first result))))
 
 (defun zero-pinyin-build-candidates-async (preedit-str fetch-size complete-func)
-  "Build candidate list, when done call complete-func on it."
+  "Asynchronously build candidate list, when done call complete-func on it.
+
+PREEDIT-STR the preedit string.
+FETCH-SIZE fetch at least this many candidates if possible.
+COMPLETE-FUNC the callback function when async call completes.  it's called with
+              fetched candidates list as parameter."
   (zero-debug "zero-pinyin building candidate list asynchronously\n")
   (zero-pinyin-service-get-candidates-async
    preedit-str
@@ -122,6 +131,7 @@
   (should-not (zero-pinyin-can-start-sequence ?v)))
 
 (defun zero-pinyin-pending-preedit-str-changed ()
+  "Update zero states when pending preedit string changed."
   (setq zero-fetch-size 0)
   (setq zero-current-page 0)
   (zero-pinyin-build-candidates-async zero-pinyin-pending-preedit-str zero-initial-fetch-size 'zero-build-candidates-complete))
@@ -181,6 +191,7 @@
        (t (error "Unexpected zero-pinyin-state: %s" zero-pinyin-state))))))
 
 (defun zero-pinyin-commit-first-candidate-or-preedit-str ()
+  "Commit first candidate if there is one, otherwise, commit preedit string."
   (unless (zero-pinyin-commit-nth-candidate 0)
     (zero-commit-preedit-str)))
 
@@ -223,7 +234,9 @@ This is different from zero-framework because I need to support partial commit"
 
 (defun zero-pinyin-handle-preedit-char (ch)
   "Hanlde character insert in `*zero-state-im-preediting*' state.
-Override `zero-handle-preedit-char-default'."
+Override `zero-handle-preedit-char-default'.
+
+CH the character user typed."
   (cond
    ((= ch ?\s)
     (zero-pinyin-commit-first-candidate-or-preedit-str))
@@ -248,6 +261,7 @@ Override `zero-handle-preedit-char-default'."
 	  (zero-append-char-to-preedit-str ch))))))
 
 (defun zero-pinyin-get-preedit-str-for-panel ()
+  "Return the preedit string that should show in panel."
   (if (eq zero-pinyin-state *zero-pinyin-state-im-partial-commit*)
       (concat zero-pinyin-pending-str zero-pinyin-pending-preedit-str)
     zero-preedit-str))

zero-pkg.el

@@ -12,9 +12,10 @@
 ;; See the License for the specific language governing permissions and
 ;; limitations under the License.
 
-;; Version: 1.2.3
-;; Package-Version: 1.2.3
+;; Version: 1.2.4
 ;; URL: https://gitlab.emacsos.com/sylecn/zero-el
+;; Package-Version: 1.2.4
+;; Package-Requires: ((emacs "24") (s "1.2.0"))
 
 ;;; Commentary:
 
@@ -22,9 +23,10 @@
 
 ;;; Code:
 
-(define-package "zero" "1.2.3"
+(define-package "zero" "1.2.4"
   "a Chinese input method framework"
-  '((s "1.2.0")))
+  '((emacs "24")
+    (s "1.2.0")))
 
 (provide 'zero-pkg)
 

zero-pkg.el.tpl

+;;; zero-pkg.el --- Zero package file -*- lexical-binding: t -*-
+
+;; Licensed under the Apache License, Version 2.0 (the "License");
+;; you may not use this file except in compliance with the License.
+;; You may obtain a copy of the License at
+;;
+;;     http://www.apache.org/licenses/LICENSE-2.0
+;;
+;; Unless required by applicable law or agreed to in writing, software
+;; distributed under the License is distributed on an "AS IS" BASIS,
+;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+;; See the License for the specific language governing permissions and
+;; limitations under the License.
+
+;; Version: PKG_VERSION
+;; URL: https://gitlab.emacsos.com/sylecn/zero-el
+;; Package-Version: PKG_VERSION
+;; Package-Requires: ((emacs "24") (s "1.2.0"))
+
+;;; Commentary:
+
+;; defines zero package.
+
+;;; Code:
+
+(define-package "zero" "PKG_VERSION"
+  "a Chinese input method framework"
+  '((emacs "24")
+    (s "1.2.0")))
+
+(provide 'zero-pkg)
+
+;;; zero-pkg.el ends here

zero-quickdial.el

@@ -26,14 +26,17 @@
 ;;; Code:
 
 (defun zero-quickdial-insert-one ()
+  "Insert \"one\"."
   (interactive)
   (insert "one"))
 
 (defun zero-quickdial-insert-two ()
+  "Insert \"two\"."
   (interactive)
   (insert "two"))
 
 (defun zero-quickdial-insert-three ()
+  "Insert \"three\"."
   (interactive)
   (insert "three"))
 
@@ -42,7 +45,7 @@
     (49 . zero-quickdial-insert-one)
     (50 . zero-quickdial-insert-two)
     (51 . zero-quickdial-insert-three))
-  "zero-quickdial-mode keymap.")
+  "Keymap for zero-quickdial-mode.")
 
 (define-minor-mode zero-quickdial-mode
   "a simple input method written as an emacs minor mode"

zero-reload-all.el

@@ -17,7 +17,9 @@
 ;;; Code:
 
 (defun zero-rebuild (&optional source-dir)
-  "rebuild zero-el"
+  "Rebuild zero-el.
+
+SOURCE-DIR where to find the zero source dir."
   (interactive)
   ;; for loading s
   (package-initialize)
@@ -30,6 +32,7 @@
       (byte-compile-file (concat source-dir f) t))))
 
 (defun zero-reload-all ()
+  "Recompile and load all zero files."
   (interactive)
   (byte-recompile-directory "~/lisp/elisp/zero/" 0)
   (dolist (f '("zero-quickdial.elc"

zero-table.el

@@ -35,7 +35,8 @@
 ;; basic data and emacs facility
 ;;===============================
 
-(defvar zero-table-table nil "zero-table's table, map string to string.")
+(defvar zero-table-table nil
+  "The table used by zero-table input method, map string to string.")
 (defvar zero-table-sequence-initials nil "Used in `zero-table-can-start-sequence'.")
 
 ;;=====================
@@ -47,6 +48,7 @@
   (string< (car lhs) (car rhs)))
 
 (defun zero-table-build-candidates (preedit-str &optional _fetch-size)
+  "Build candidates by looking up PREEDIT-STR in `zero-table-table'."
   (mapcar 'cdr (sort (cl-remove-if-not (lambda (pair) (string-prefix-p preedit-str (car pair))) zero-table-table) 'zero-table-sort-key)))
 
 (ert-deftest zero-table-build-candidates ()