EmacsModeAddOn

Emacs major mode for editing TWiki pages and a command line tool for interacting with the TWiki server.

1. Usage

1.1. Emacs: twiki-mode

1.1.1. Overview

This package is an Emacs major mode for editing TWiki pages. Twiki formatted pages are reformatted on import into a twiki buffer to enhance readibility and friendlier editing. After editing, the pages are "exported" back to the twiki format.

The key benefits to twiki mode:

• Keyboard shortcuts for common operations
• Auto-numbering of headings, numbered lists
• Better bullet list management
• orgtbl-minor mode for table editing
• table numbering
• font-lock support for syntax highlighting

1. In Web Browser, click edit in Twiki on the page to edit
2. Select all and copy to clipboard
3. In emacs, twiki-mport-for-edit - assuming you are not already in a buffer in twiki-mode, this will:
   • create a temp file
   • create buffer visiting that file,
   • set the major mode to twiki-mode
   • render the buffer for "editing", making bullet/lists more readable
4. Edit as necessary
5. Export to clipboard using C-c e (twiki-export-to-clipboard)
6. Back in Web Browser, Select All, and Paste from clipboard (replacing old text)
7. Optionally save the file elsewhere

1.1.2. Key Bindings

When saving the buffer to a file, the format is saved as twiki-format (the buffer is rendered for export, then saved).

1.1.3. Tables using org-mode orgtbl

Table editing is handled by orgtbl-mode (see Info topic of Org-mode). Tables are added by simply inserting vertical bars as the beginning of the line, one vertical bar on each end of a row:

| *Header 1* | *Header 2* |

With the cursor in a table line, the basic keys are as follows:

Just type away in any cell. On tab, realignment occurs, "beautifying" the table so all rows have the same columns and column width.

Column Spanning

Twiki tables support colspan by interpreting two adjacent vertical bars as an extention of the previous column:

| Col 1         | Col 2 |
| Colspan 1 & 2        ||

Unfortunately, orgtbl does not really do colspan and if the table is realigned (on Tab, for example), the table will be reformatted as follows:

| Col 1         | Col 2 |
| Colspan 2 & 2 |       |

To get around this, put "<<" in the column that should be merged with the previous column. On export, any columns that have only "<<" as the cell text will get turned back into "||" so that Twiki performs the appropriate colspan:

| Col 1         | Col 2 |
| Colspan 2 & 2 | << |

Column Width Specifiers

It's possible to specify display column-width in orgbl as follows:

(See org-table for more info on how this works and editing such fields)

On export, this descriptor row is put in a comment block so it's hidden from view on the page. On import again, the row is reinstated.

Note this is display width only in Emacs, not in Twiki. This is particularly useful for tables that have a large amount of text in a column.

Auto-Numbering Of Tables

Table number simply looks for any line that matches "| *Table [0-9]+:". The number matched is replaced with a simple sequence from the start of the file.

1.1.4. Customization

The following variables can be customzied:

1.2. twikish Command Line Tool

The twikish command line tool allows you to upload and download pages from a TWiki server. The tool tracks version information as well as whether the local copy has been modified.

Before using twikish, first create a file ~/.twikish as follows:

BASEURL="https://twiki.site.com"
TWIKIWEB="TwikiWebName"
USERNAME="user"
PASSWORD="pass"
MERGETOOL="kdiff3"
OPENCMD="open"

Set the variables as necessary to gain access. The password may be left off and the user will be prompted for a password each run. Password may also be specified via the -p command line switch. For non-interactive use, such as from twiki-mode in Emacs, the password must be present in the config file.

The OPENCMD variable should be set to the full path to open a URL:

1.2.1. Command Line Syntax

   twikish [options] <cmd> <file>

The following commands are supported:

The following options are supported:

Examples

Retrieve the TestPage from the default web:

  $ twikish up TestPage

Retrieve the TestPage from the Alt web:

  $ twikish -w Alt up TestPage

After modifying TestPage.twiki locally, you can preview the page your browser:

  $ twikish -w Alt preview TestPage

If you like what you see, it's best to save from the command line to keep the local versioning up to date:

  $ twikish -w Alt save TestPage

2. Installation Instructions

Note: Contrary to many TWiki Add Ons, this is not installed on the server. It is comprised of an Emacs Lisp file and an associated bash script.

• Download the ZIP File
• Create a new directory named twiki-mode and extract the files there, or extract the files in a location of your choice

2.1. Loading twiki-mode in Emacs

First, either:

• copy twiki.el into a shared lisp directory
• add the installation directoy by adding the following line to your ~/.emacs file:

     (push "~/twiki-mode" load-path)

Then add the following lines to your ~/.emacs file:

   (require 'twiki-mode)
   (add-to-list 'auto-mode-alist'("\\.twiki$" . twiki-mode))

This will associate any files opened with an extension of *.twiki as a twiki file and automatically set the mode to twiki-mode.

2.2. Setting up twikish command line tool

The command line tool twikish can be used independently from twiki-mode, but work nicely with key bindings directly from within Emacs.

To use twikish, either:

• copy twikish to a directory already in your executable path, or
• add "~/twiki-mode" to your path, or
• add the following to your ~/.emacs file, using the path where you extracted the zip file:

     (setq twiki-shell-cmd "~/twiki-mode/twikish")

3. Add-On Info

• Set SHORTDESCRIPTION = Emacs major mode for editing TWiki pages and a command line tool for interacting with the TWiki server.

Add-on Author:	TWiki:Main.ChristopherWhite
Copyright:	© 2010-2012, TWiki:Main.ChristopherWhite
License:	GNU CPL v3 (GNU General Public License v3)
Add-on Version:	2012-08-07 (V1.2)
Change History:
2012-08-07:	Version 1.2 - Added support for twikish command line tool, bug fixes
TWiki Dependency:	none)
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	none
Add-on Home:	https://github.com/christopherjwhite/emacs-twiki-mode
Zip File:	https://github.com/christopherjwhite/emacs-twiki-mode/zipball/master
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/EmacsModeAddOnDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/EmacsModeAddOnAppraisal

Related Topic: TWikiAddOns

-- TWiki:Main.ChristopherWhite - 2012-08-07