Emacs Wiki 簡易使用指南

這是我之前發表在 Newzilla 線上雜誌上的文章，不確定能否直接轉錄回我的 blog，先用連結吧。

點進去看吧

Emacs Wiki 後一章 -- 專案、遠端連線與註腳模式

原文撰寫於 2005 年 3 月 2 日，本來是接受某線上雜誌邀稿，該雜誌因故停刊，故未刊出，這其實只是草稿而已，我也懶得改寫了。

黃俊傑 jjhuang AT cm-nctu-edu-tw

前言

在上一期中, 我們學習了如何用 Emacs Wiki 來快速產生網頁, 本期我們將會介紹 Emacs Wiki 相關的工具; 使用 Emacs Wiki 的專案功能來管理不同的網頁, 將網頁傳到遠端的網頁伺服器上, 以及使用 Emacs 內建的註腳次要模式(footnote-mode) 來幫助我們輸入註腳。

Emacs Wiki 專案

如果你像筆者這樣有好幾個獨立的 Wiki 要編輯, 那麼你很可能需要使用到 Emacs Wiki 專案來管理這些檔案。 新增專案的方法如下，首先你要先進入 Emacs 的 customization

M-x customize-group  emacs-wiki 

然後再進入 Emacs Wiki Project 這個目錄, 進入之後把 Emacs Wiki Projects 這個變數打開來。 一開始 Emacs Wiki 是沒有任何專案的, 只有 default 這個專案, 而這個專案是沒有列在這個變數中。 若要新增一個專案, 首先要按 INS 這個按鈕, 然後輸入專案名稱於 Project name: 一欄, 接下來在 Project name: 的下方中間也有一個 INS 按鈕, 請按下這個按鈕, 然後輸入開啟這個專案時要改變的變數。 筆者所知道需要改變的變數至少有下列幾個：

emacs-wiki-publishing-directory

這個專案的網頁放置目錄

emacs-wiki-directories

這個專案的 Wiki 檔案放置目錄

記得 emacs-wiki-directories 是複數名詞, 代表這是一個 list, 所以在 Value 那一欄必需將你的目錄用括號刮起來, 如:

("~/Documents/MyWebPage")

增加完成之後, 記得按 State 這個按鈕把這次改變的專案設定儲存起來。 以後要使用專案, 可以直接開啟該專案的檔案, 或是在 Emacs Wiki Mode 中下 C-c C-v 改變專案。

傳送網頁至遠端伺服器

目前 Emacs Wiki 要編輯遠端的網頁, 可以放在本地端, 然後再用 rsync 等同步程式來做同步, 或是把專案放置在遠端的機器上。 要把專案放置載遠端的機器上, 可以把 emacs-wiki-directory 放在本地端, 把 emacs-wiki-publishing-directory 填上

"/user@host:/path/to/your/web/page"

如此, 當你下 C-c C-p (emacs-wiki-publish) 時, Emacs 就會透過 tramp 程式把檔案送到遠端的伺服器上。 M-x emacs-wiki-publish 會將所有的 Wiki 檔案都轉換成 html, 並且傳送到遠端, 在頻寬較小的情況下, 相當的耗費時間, 可以利用 M-x emacs-wiki-publish-this-page 來傳送目前編輯的頁面。
如果你嫌每次都要按 M-x emacs-wiki-publish-this-page 打太多字, 可以參考 Emacs Wiki 專案首頁的建議¹, 將 C-x C-p 按鍵定義成 M-x emacs-wiki-publish-this-page, 只要你在 ~/.emacs 加入以下幾行即可:

(add-hook 'emacs-wiki-mode-hook
       (lambda () (global-set-key "\C-x\C-p" 'emacs-wiki-publish-this-page)))

這樣就會在每一次進入 Emacs Wiki 模式時將此按鍵加入。 你就可以在每一次編輯完一個檔案, 想要上傳時, 按 C-x C-p 來上傳目前編輯的檔案, 以節省傳輸時間。

註腳模式

說明

註腳模式(footnote-mode) 是一個次要模式(minor mode), 與 Emacs Wiki 並無直接關聯, 是 Emacs 內建的次要模式。 筆者通常用這個模式配合 gnus 使用, 在編輯文章的時候加一些註腳用。 Emacs Wiki 採用的註腳格式與註腳模式產生出來的格式完全一樣, 所以我們也可以利用註腳模式來協助編輯 Emacs Wiki 檔案。
與其他的次要模式一樣, 註腳模式的命令可以開啟或關閉註腳模式。 註腳模式的命令是

M-x footnote-mode

當註腳模式開啟的時候, Emacs 視窗下方的模式列會顯示 FN 的字樣。 當我們要新增一個註腳的時候, 只要在想要新增的位置鍵入

M-x footnote-add-footnote

接下來註腳模式會自動在新增的位置填上一個數字前後加上方括號, 並且跳到文章的最後, 加上註腳(Footnote) 字樣, 游標會停在要編輯的註腳後面等待使用者輸入註腳的說明文字。 輸入完之後, 我們可以輸入

M-x footnote-back-to-message

然後游標會回到剛剛新增註腳的位置, 使用者可以繼續本文的編輯。 其餘的註腳模式功能請參考快速鍵列表, Emacs Wiki 可以完全處理註腳模式產生的格式, 這篇文章就是利用註腳模式來來產生註腳的。

快速鍵列表

註腳模式的快速鍵不多, 只有六個, 表列如下：

按鍵	命令(鍵入之前先按 M-x)	說明
C-c ! a	M-x footnote-add-footnote	增加註腳
C-c ! b	M-x footnote-back-to-message	由註腳說明處回到引用處
C-c ! d	M-x footnote-delete-footnote	刪除註腳
C-c ! g	M-x footnote-goto-footnote	跳到註腳解釋
C-c ! r	M-x footnote-renumber-footnotes	重新編排註腳號碼
C-c ! c	M-x footnote-cycle-style	變換註腳形式

---

^[1] Emacs Wiki 專案首頁, http://repose.cx/emacs/wiki/#sec5

How to use HHKB Pro 2 as an external keyboard to an iPad

Happy Hacking Keyboard Professional 2 (HHKB Pro 2), which is produced by PFU Limited of Japan, is a great keyboard with a small footprint, and it contains only 60 keys. As a new iPad owner, I wonder if I can combine these two gadgets and write notes on-the-go.

After some trial-and-error, finally I make it work! Here is how to make it. First you need to buy iPad Camera Connectivity Kit from Apple. This kit is designed for connecting to a digital camera, so if you ask any salesperson in Apple store, he or she will probably tell you it's not designed to connect to an external keyboard. Never mind what he or she says, just buy it. And then you'll need a USB hub with external power supplied, i.e. you actually need to plug the external power cord to a power source because HHKB Pro 2 draws larger current from USB port than an iPad can supply. Now connect your HHKB Pro 2 to the USB hub with external power supplied, and then connect the USB hub to your iPad via the camera connectivity kit. Open any text-oriented application, e.g. OmniOutliner, and then you can type by your HHKB Pro 2!

To use these gadgets on-the-go, I bought a mobile battery with me so that the USB hub can be supplied by the battery. Here are the photos of them:

What you need

How to connect HHKB Pro 2 to a new iPad


Requirements:
- a new iPad, or iPad 3
- a Happy Hacking Keyboard Professional 2
- a USB hub with external power source
- a mobile battery if you want to use them on-the-go

Note I'm not sure if older iPad works this way.

Emacs etags 簡介

這也是筆者多年前發表在 NNTP news 上的文章，留存備份。

etags 簡介 -*- Outline -*-

* 前言
  有許多的 IDE(Integrated Development Environment) 都提供了函數名稱的
  自動完成功能( 亦即，輸入前面幾個字元之後，編輯器可以自動幫你完成後面
  的函數名稱）。Vi 裡面有 ctags 可以做到這件事，那麼 Emacs 呢？答案是
  etags. 在這篇文章裡，我會簡短的介紹如何使用 etags.

* etags 使用方法
** 建立函數及關鍵字列表
   在使用之前，你必須先在你的發展環境目錄底下建立列表; 假設你的發展環
   境目錄名稱叫做 /path/to/developer/, 建立列表的方法如下：

   % cd /path/to/developer/
   % etags *.h *.c

   這樣就建立完成了，根據 etags/ctags 的手冊, etags/ctags 可以處理的語
   言有 C, Objective C, C++, Java, Fortran, Ada, Cobol, Erlang, LaTeX,
   Emacs Lisp/Common Lisp, makefiles, Pascal, Perl, Postscript,
   Python,  Prolog, Scheme  and most assembler-like  syntaxes.
   預設的列表檔名是 TAGS.

** 把函數及關鍵字列表讀進 Emacs
   開始用 Emacs 編輯檔案, 比如說你正在編輯 foo.c, 你先用 C-x C-f 把
   foo.c 讀進來之後，你需要使用 etags 的功能，那麼你就執行
   M-x visit-tags-table /path/to/developer/TAGS
   把 /path/to/developer/TAGS 檔案讀進來。註： 表示 Return 鍵，或
   是在鍵盤上通常標示為 Enter.

** 在 Emacs 中搜尋函數內容
   有的時候我們會想要直接跳到某個函數裡面去修改他的內容，你可以使用
   M-. (沒錯，就是 Meta 跟一個句點) 然後輸入函數名稱就會跳到該函數的
   code 那裡去; 如果你按 M-. 的時候游標指著一個函數名稱，你可以在輸入
   函數名稱的時候直接按 即可跳到該函數源碼的地方。跳過去之後，如
   果你想要回來原來地方，你可以用 M-* 來做到。

   如果你想要在另一個視窗內看到該函數源碼，而不是你現在的這個視窗(對照
   方便), 那麼你可以用 C-x 4 . TAG 來達成這件事。

   如果你要搜尋某些函數與關鍵字，你可以用 M-x tags-search 的功能，這個
   可以用 regular expression 來搜尋。當你用 M-x tags-search
   REGEXP 之後，你可以用 M-, (Meta 逗點), 找下一個搜尋到的函數名
   或關鍵字。

** 函數及關鍵字自動完成
   etags 並沒有提供函數及關鍵字自動完成(auto-completion)的功能, 但是
   Emacs 有提供一個功能可以達成這件事，叫做 dynamic abbreviation
   expansion. 這個功能事實上是把去找在開啟的 buffer 裡面有那些字串是你
   輸入字串的完整字串，而 TAGS 列表就在一個 buffer 裡面，所以可以達成
   函數及關鍵字自動列表。當你輸入一個函數名稱或是一個變數名稱的前面幾
   個字母，比如說: foo-, 然後按 M-/, 這時候 Emacs 會把所有可能的字串找
   到，並把第一個可能的字串直接完成，所以你按了一次 M-/ 之後可能會變成
   foo-bar-function, 你繼續按 M-/ 可以變換成其他可能的字串，直到沒有為
   止。或者是你也可以按 C-M-/, 這時候 Emacs 會像其他時候的
   auto-completion 的行為一樣，跳出一個視窗把所有的可能列表列出來給你
   選擇。

* 結語
  當我開始使用 etags 的功能之後，我就沒有辦法不用這個功能了，因為實在
  是太方便了。etags 也可以幫你自動完成標準函式庫裡的名稱，只要你在
  etags 的時候把 /usr/include 裡的表頭檔案也包含進來就可以了。etags 還
  有其他比較進階的功能，我沒有一一列出來，有興趣的人可以去看看 M-x
  info 裡的 Emacs 手冊。最後我做一個這次提到的功能列表，供讀者參考用。

* 按鍵列表
  M-x visit-tags-table TAGS-file
      把 TAGS-file 檔案讀進 Emacs
  M-. TAG 尋找函數或關鍵字定義的源碼
  C-x 4 . TAG 在另一個視窗尋找函數或關鍵字定義
  M-* 回到尋找關鍵字定義之前的地方
  M-x tags-search REGEXP 用正規表示式搜尋函數或關鍵字定義
  M-, 找下一個搜尋到的函數或關鍵字
  M-/ 自動完成可能的函數或關鍵字
  C-M-/ 列出所有函數或關鍵字名稱的自動完成列表

Emacs 大綱模式簡介(Outline mode)

這是筆者很多年前寫的文章，發表在 NNTP news 上面，留存在本 blog 中。


* 簡介 
我想很多人在作筆記或是絞盡腦汁想問題的時候，常常會用大綱來把自己的想法 
記錄下來，比如說像以下的方法： 
I. 棒球 
A. 職棒 
1. 台灣職棒 

2. 美國職棒 
a. 國家聯盟 
b. 

3. 日本職棒 
a. 中央聯盟 
b. 太平洋聯盟 

B. 業餘棒球 

II. 籃球 
A. 職籃 

這樣的階層架構可以在 Emacs 中使用他的大綱模式(outline mode) 來做到，幫 
助我們來紀錄我們的想法或是像筆者就常常在聽完演講之後，把用筆記上的演講 
大綱筆記，用 Emacs outline mode 記錄下來，供日後查詢。Emacs 也可以把這 
些 outline 轉換成其他格式，比如說: LaTeX 或是 Info 檔格式。在本文中提 
到的 Emacs 以 GNU Emacs 為準，XEmacs 應該也是差不多，不過我建議你們用 
GNU Emacs, 因為 Emacs 處理字型比較清晰，而且對於中文支援較佳。 

* Outline mode 
** 進入大綱模式 
使用者可以用 M-x outline-mode 來進入大綱模式，打完這個命令之後就可以看 
到目錄列上出現 "Headings" "Show" "Hide" 三個下拉式選單項目，不過，先別 
急，先了解一些基本概念再來使用。如果你有開啟 font-lock-mode 的話，你打 
完上述命令之後就可以看到這篇文章的標題顏色變了，因為筆者就是用 
outline-mode 來打這篇文章的。如果沒有看到顏色，你可以用 M-x 
font-lock-mode 來啟動。M-x 意思是按住 Alt(Emacs 裡稱為 Meta 鍵) 以及 
x, 然後輸入 outline-mode，再按 [Enter] 即可。 

** 階層架構 
Outline mode 的階層架構是以幾個 "*" 符號來分隔的，就如同本文章一樣。一 
個星號("*") 的就是最高層，也就是類似簡介的例子中的 I, II, 等等，而兩個 
星號則是第二層，類似例子中的 A, B, 等等。但是要注意的是這些星號一定要 
在該行的最前面。如果沒有星號開頭的就是該層（或稱為該標題）下的本文。 

** 顯示及隱藏標題與本文 
*** 隱藏 
想要隱藏某個標題下的全部文字，你可以選擇目錄選單『Hide->Entry』，你可 
以將游標移到這裡，然後選擇『Hide-Entry』，如果你沒有看到選單，你可以直 
接輸入 C-c C-c (連續兩個 Control C)。好，現在就輸入 C-c C-c 

*** 顯示 
別急別急，看不到隱藏的文字了？先看看隱藏兩字後面是不是出現了三個句點 
"..."? 那就表示那個標題以下的文字被隱藏了。你可以用目錄選單 
『Show->Entry』來回復剛剛的文字，或是按 C-c C-e 來顯示隱藏的文字。 

*** 在標題間移動 
有的時候你會想要在同個層級的標題間移動，這樣比較方便寫作。那麼你可以使 
用『Headings->Previous Same Level』，或是按 C-c C-b 到前一個同層級的標 
題。如果你照指示的話，你會看到現在游標停在『顯示』那一行上面。如果要上 
一個層級，你可以選擇『Headings->Up』，或是 C-c C-u, 如果你照做的話，你 
的游標現在會是在『顯示及隱藏標題及本文』那一行。 

* 結語 
有沒有搞錯？這麼快就要結束了？沒錯，我已經把主要功能介紹完了，其他的功 
能，請自行看下拉式選單，全部都在 Headings, Show, Hide 裡面。或是找 
Emacs manual 裡的 Outline Mode 一節，有更詳盡的說明。 

大綱模式是一個很小，但很方便的功能。筆者曾經有一次要做 simulation 
program 的除錯, 我把所有的 events 全部輸出到一個檔案裡，但是 events 很 
多啊，那可是上千上萬的。Events 有分不同的層級，上層的是比較高階的動作， 
下層是比較細節的動作，如果分層輸出到不同個檔案可以解決 events 太多的問 
題，但是卻比較不容易看出不同層級的時間先後。於是筆者便將 events 依照層 
級在那一行的最前面加上星號，全部輸出到一個檔案裡（最後還是有分檔案啦， 
不過是五千個 events 一個檔案，而不是分層級）。這樣，我就可以分顏色看到 
events 的層級，我也可以顯示或隱藏某一個 events 以下做的事，要找下一個 
同層級的 event 也很快。如果你想照做，筆者提醒你，Windows 版的Emacs 處 
理這樣大的檔案會頗慢的，這也是筆者改用 Linux 的原因之一。 

在 GNU Emacs 的 Help 文件系統

GNU Emacs 有一個功能很好用, 他的 key binding 一般來說是 C-h S, 或是 M-x info-lookup-symbol, 使用的方法是把游標移到你要查詢的 symbol 上面, 然後按下 C-h S, 這時候 Emacs 會自動幫你找到相對應的 Info 文章, 並顯示在另一個視窗(這裡的視窗是 Emacs 的術語) 上。

如果你想要試用這個功能, 可以試著開啟任何一個 Emacs Lisp 檔案, 然後對著任何一個 function 鍵入 C-h S, 就會出現文件, 舉例來說, 如果對著 require 按下 C-h S, 在筆者的 Emacs 24.1.1 就會出現下列的文件:

-- Function: *require* feature &optional filename noerror
    This function checks whether FEATURE is present in the current
    Emacs session (using `(featurep FEATURE)'; see below).  The
    argument FEATURE must be a symbol.

    If the feature is not present, then `require' loads FILENAME with
    `load'.  If FILENAME is not supplied, then the name of the symbol
    FEATURE is used as the base file name to load.  However, in this
    case, `require' insists on finding FEATURE with an added `.el' or
    `.elc' suffix (possibly extended with a compression suffix); a
    file whose name is just FEATURE won't be used.  (The variable
    `load-suffixes' specifies the exact required Lisp suffixes.)

    If NOERROR is non-`nil', that suppresses errors from actual
    loading of the file.  In that case, `require' returns `nil' if
    loading the file fails.  Normally, `require' returns FEATURE.

    If loading the file succeeds but does not provide FEATURE,
    `require' signals an error, `Required feature FEATURE was not
    provided'.

上述作法是當你目前的 major mode 有相對應的 Info 檔案的時候, 可以直接使用 C-h S 來查詢, 如果沒有的話, Emacs 會先問你要使用哪一個 major mode 的 help 檔案, 然後再查詢該 symbol 的文件。那麼, 如果要為新的 major mode 增加 Info 文件呢? 這時候你可以在 .emacs 裡加上 info-lookup-maybe-add-help 來把某個 Info 檔案加入 major mode 裡面, 範例如下:

(require 'info-look)

(info-lookup-maybe-add-help
 :mode 'asm56k-mode :topic 'symbol
 :regexp "[a-zA-Z]+"
 :doc-spec '(("(dsp563xx)Index")
             ("(dsp563xx)Concept Index")))

上述的範例是指定 major mode asm56k-mode 的 Info 文件是 dsp563xx, 這個檔案必須在 Info 系統能找到的路徑上, 透過 Index 與 Concept Index 這兩個 Info node 來查詢關鍵字的 Info 文件, 而可以被查詢的關鍵字的 regular expression 則由 :regexp 來指定, 本範例的關鍵字是由純英文字母組成。上述的範例是筆者為了要在 GNU Emacs 裡面寫 Motorola DSP56300 的組合語言而增加的, 這樣筆者在 asm56k-mode 編輯組合語言的時候, 就可以隨時透過 C-h S 來查詢某個助憶碼(mnemonic) 的用法以及 instruction encoding, 而這些是存在另一個 Info 文件上。

Info 檔案在 GNU Emacs 中是一個重要的文件系統, 可以由 Texinfo 檔案編譯而成, 現在也有很多文件系統也可以產生 Texinfo 的格式, 比如 Sphinx, 對 Texinfo 有興趣的讀者可以參考一下 Arnold Robbins 在 Linux Journal 所寫的介紹文章 What's GNU: Texinfo. 不管是用什麼方法產生 Info 檔案之後, 透過設定, 結合 C-h S 的便利性, 你就可以在 GNU Emacs 裡面很便利的查詢文件。

--