Tags:
editing1Add my vote for this tag create new tag
, view all tags

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
Typical usage:

  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

Key binding Description
C-c h Make current line a header line (asks for level, or prefix arg)
C-c 1-6 Make a Header 1-6 line
C-c C-h Renumber all headers using 1.4.3 notation
C-c C-r Renumber all headers and tables
C-c C-t Renumber all tables
C-c i Import clipboard
C-c e Export to clipboard, rendering bullets/lists back to twiki format

Bullet List Keys
Tab Indent bullet list
S-Tab Unindent bullet list

Headings Keys
Tab Hide/show direct subtree
S-Tab Hide/show all subtrees

Server Keys
C-c t p Upload to the server for a preview
C-c t s Save as a new revision on the server
C-c t u Update the local copy from the latest on the server
C-c t t Return the status of the current document
C-c t d Diff the current buffer against the server version

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:

Tab next cell, or if at the end of the row, advance to next row, creating a new row if necessary
S-Tab prev cell
Ret move to next row in the same column, creating a row if necessary
C-c C-c Realign the table

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:

Name Age Address
Christo=> 25 1234 Really Long=>

(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:

Variable Default Description
twiki-tab-width 3 Spacing for bullet lists, etc.
twiki-min-heading-level 1 Min heading level to include for heading renumbering
twiki-max-heading-level 6 Max heading level to include for heading renumbering
twiki-use-orgtbl t Set to nil to disable usi of orgtbl-minor-mode for tables
twiki-silient-import nil If non-nil, import into a buffer already in twiki-mode will not ask about overwrites
twiki-shell-cmd twikish Shell command that supports commands to interact with the twiki server

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:

OPENCMD Description
open Mac OS X
start MS Windows
cygstart MS Windwos + Cygwig
firefox or other Favorite browser in Linux

1.2.1. Command Line Syntax

   twikish [options] <cmd> <file>

The following commands are supported:

up or update Update to the latest from version on the server
diff Diff the local copy against the server
revert Revert any local changes to the server copy
open Open the topic in a browser
status Display the status of each file
preview Upload local copy to the server in preview mode
save Upload local copy and save as a new version
cl or cleanup Update to latest and cleanup extraneous files

The following options are supported:

-u or --user Set the username
-p or --password password> Set the password
-b or --baseurl Set the base url for the twiki site
-w or --twikiweb Set the web
-n Non-interactive, don't prompot for anything

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

Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r4 - 2012-12-03 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2016 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.