Deprecated: The each() function is deprecated. This message will be suppressed on further calls in /home/zhenxiangba/zhenxiangba.com/public_html/phproxy-improved-master/index.php on line 456
emacs trac-wiki mode - Trac
[go: Go Back, main page]

trac-wiki.el -- Trac Wiki Page Editing Mode for Emacs

News

  • 2008-06-07: Version 1.8 is released. Fixed two bugs on interactive end-point url input. (changes)
    And it also tested with emacs 22.1 and 23.0.60 on debian etch.
  • 2007-11-14: Version 1.7 is released. Fixed a serious bugs which is introduced in version 1.6 and cause memory exhaust. (changes)
  • 2007-11-14: Version 1.6 is released. Many bugs are fixed to work with Emacs 21.4. Emacs 21.4 and 22.1 are tested (on debian serge). (changes)
  • 2007-03-24: My patch against xml-rpc.el is now included xml-rpc.el (rev. 1.7) on Savannah. So I removed xml-rpc.el from trac-wiki's repository.
  • 2006-12-22: Version 1.5 is released. It contains many bug fix and enhanced support of old Emacs (xml-rpc.el is updated). And also add/enhance some features like C-c C-o. See changes.

Overview

trac-wiki.el is a emacs lisp module to edit wiki page of trac. It allows accessing to the remote trac site via XML-RPC and editing page content on emacs. The features are:

  • Works on Emacs 21.4 and 22.x
  • Multiple project access.
  • Retrieve page from remote site and edit it with highlighting.
  • Commit page with version check.
  • Diff / Ediff between editing text and original.
  • Revert local edit.
  • Merge with most recent version if it is modified by other user.
  • Show history of page (but not so informative).
  • Preview page in emacs with w3m (textual).
  • Preview page with external browser with CSS.
  • Search words in trac site for all pages and view result.
  • Completion for macro name and wiki page name in buffer.

And it has following restrictions:

  • Cannot operate attachments.
  • It is not well on error handling (auth fail, spam-filtered, etc.)
  • Cannot delete page version.
  • Cannot operates tickets.
  • Cannot handle tags provided by TagsPlugin.
  • Problem with digest authentication.

Download

Latest code is availabe in source browser and repository. The source code is version controled with Mercurial. You can get source codes by cloning this repository: 

hg clone http://www.meadowy.org/~gotoh/hg/trac-wiki/

Requirements

  • Emacs 21.4, 22.1 or later, Meadow 3.00-dev or later.
  • You must have xml-rpc.el (rev. 1.7 or later) from Emacs Weblogging project).
  • And emacs-w3m (and w3m program) is required for preview.
  • You need gnutls-cli or openssl to use https access.
  • For Emacs 21 user, mule-ucs is required to use CJK characters.
  • For Emacs 21 user, url (sub-project of w3) library package is required. And also ssl.el is required for https. (See also #2)
  • On the server, Trac 0.10.2 or later is required. And also XmlRpcPlugin (r1735 or later) is required.

Configuration

  1. Get and enable XmlRpcPlugin on your trac site.
  2. Set project information variable trac-projects in your .emacs.
  3. Set proxy information variable url-proxy-services in your .emacs.

Server side

Get XmlRpcPlugin then install it then enable it. See install instruction for details.

Then you need to allow users to use XML-RPC feature. For example, if you want to allow editing pages for users who logged in, add action XML_RPC to the predefined psudo user authenticated. You can do that with trac-admin command like this: 

$ trac-admin your-env permission add authenticated XML_RPC

You can do the same thing via web-admin interface (see WebAdmin).

Client side

If you have a trac site frequently visit to edit, you can register the url of that site with alias name. To do this use trac-wiki-define-project like this: 

(trac-wiki-define-project "trac-hacks"
                          "http://trac-hacks.org/" t)

1st argument is alias name which is used on selection. 2nd arugment is actual url. 3rd optional argument indicates login is required for the site access. If you have multiple instance in one site, you can use trac-wiki-define-multiple-projects. 

(trac-wiki-define-multiple-projects '("proj1" "proj2" "test")
                                    "http://www.foo.bar.org/" t)

An example above is equivalent to three trac-wiki-define-project definition. 

(trac-wiki-define-project "proj1" "http://trac-hacks.org/proj1" t)
(trac-wiki-define-project "proj2" "http://trac-hacks.org/proj2" t)
(trac-wiki-define-project "test" "http://trac-hacks.org/test" t)

To use http proxy server, you need to set proxy information as url package's way because trac-wiki.el uses url package.

See info of url pakage for more detail.
... by evalueate (Info-goto-node "(url)Proxies")

Finaly, set autoload for convenience: 

(autoload 'trac-wiki "trac-wiki" "Trac wiki editing entry-point." t)

NOTICE for mod_auth_sspi user

(For user using emacs 22.0.50/90 before 2006-11-03.)

There is a warning around multiple authentication. If your target trac site provides multiple authentication, you may fail to login. Because url-http.el has bug of handling multiple authentication, you may encount endless user/pass query. For example of case, if you setup trac on apache with mod_auth_sspi with allowing fallback to basic authentication, the first WWW-Authenticate: line in response header is NTLM auth.

To avoid this, apply mult-auth patch to url-http.el or set auth information by your hand (into url-http-real-basic-auth-storage for basic auth). For example, if you are using basic authentication, put following code in *scratch* buffer and evaluate it (by C-x C-e at end of last line): 

(let ((auth (base64-encode-string (format "%s:%s" "yourname" "yourpassword"))))
   (setq url-http-real-basic-auth-storage)
        `(("www.some.org:80" ("realm string for the site" . ,auth))))

If you success with this, put the code in your ~/.emacs for the next time.

For digest auth, sorry, I cannot get success.

This patch is not required for recent version of url-http.el (after 2006-11-03).

Usage

After configuration above, you can start editing by M-x trac-wiki. Simple flow of editing is:

  1. M-x trac-wiki
  2. Specify project name.
  3. Specify page name.
  4. Edit page contents.
  5. Check difference (C-c C-d).
  6. Preview page output (C-c C-p).
  7. Commit it (C-c C-c).
  8. Edit other page (C-c C-o).

The command trac-wiki asks you the project name with completion. If you want to specify end-point URL directly, simply hit ENTER instead of project name then program asks you raw end-point URL. After that, trac-wiki.el accesses to the site to retrieve page names for. So you can use completion on entering page name. Entering non existing name means creating new page.

After fetched the page content, edit it, then commit by trac-wiki-commit (C-c C-c). Note that you cannot save editing buffer because the page is not assigned to local file. You shoul hold as modified, then commit.

On editing page contents, the buffer is trac-wiki-mode which is based on text-mode. you can specify some mode specific commands:

trac-wiki-commit
C-c C-c
Commit current editing contents. Same project (end-point) is used, or ask project with C-u.
trac-wiki-edit
C-c C-o
Edit another page in new buffer. If point is on wiki page link or camel-case name, use it as default on page name prompt. (enhanced in ver-1.5)
trac-wiki-preview
C-c C-p
Preview current contents by w3m (text base). With C-u, preview by external browser (graphical).
trac-wiki-view-page
C-c C-v
View visiting page in external browser. It's not preview but actual page on site. It may help you to switch page operation in browser. (new in ver-1.5)
trac-wiki-diff
C-c =
C-c C-d
Make diff between current contents and original contents With C-u, execute ediff instead of diff.
trac-wiki-merge
C-c C-m
Merge with most recent page contents using ediff-merge. If not modified, turn current buffer to newest version.
trac-wiki-revert
C-c C-u
Revert to original contents discarding current modification. It shows diff and confirm you before do it.
trac-wiki-show-info
C-c C-i
Show some informations of current editing page in echo area:
  • End-point url
  • page name with modification state,
  • Base version of the page and its author and date.
trac-wiki-complete-at-point
M-C-i
Complete macro name or page name on current point. The macro names are collected from "WikiMacros" page on the site (and cached).
trac-wiki-history
C-c C-h
Show page history in other buffer. History is information returned from xmlrpc plugin. On each revision entry, you can show diff on its revision by '=' key.
trac-wiki-search
C-c C-s
Search on project site for specified keywords. You can specify keywords and filters. The result is shown in another buffer with highlighting.

Tips

  • FireFox Add-on programs like It's All Text! and MozEx are useful to edit pages on the site without XML-RPC service. They invoke external editor to edit content of text area via local temporary file. Once you get wiki text in emacs buffer, you can change major mode by M-x trac-wiki-mode to get some benefits. Of course, you cannot do XML-RPC operation in this case but you'll get color.
    If you automate this, following function and adding to hook might be useful: 
    (defun trac-wiki-auto-mode-function ()
  (if (and (eq major-mode 'text-mode)
	   (member (file-name-extension (buffer-file-name))
		   '("txt" "wiki"))
	   (re-search-forward "^=+ [^=\n]+ =+\\s *$" nil t))
      (trac-wiki-mode)))

(add-hook 'find-file-hook
	  'trac-wiki-auto-mode-function)
    This hook checks the content is text and having trac wiki style header line, then change to trac-wiki-mode automatically if matched. Note that this way does not worked for new empty page.
  • Page informations by trac-wiki-history does not have a comment of page updating. This is a limitation to be exact for the specification. But I guess everyone want to see the comment in page history. There's a patch to do this and trac-wiki.el support it.

Bug Report

If you find a bug, search a ticket then create new ticket if not exist.

References

Attachments