Homepage: https://github.com/christopherjwhite/emacs-twiki-mode
Author: Christopher J. White
Updated:
Mode for editing Twiki wiki files for emacs
This package is a major mode for editing TWiki pages
(http://twiki.org). 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-import-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
Interesting twiki-mode keys:
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 lists:
Tab Indent bullet list
S-Tab Unindent bullet list
Headings:
Tab Hide/show direct subtree
S-Tab Hide/show all subtrees
Server:
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).
INSTALLATION:
Put this in your .emacs to associate "*.twiki" files with twiki-mode:
(add-to-list 'auto-mode-alist'("\\.twiki$" . twiki-mode))
COMMAND LINE TOOL:
Install the command line tool 'twikish' in a location in the default path,
or set `twiki-shell-cmd' to the proper location.
This enables the following integrations from within emacs. See the
Server section in the section above.
Additional command `twiki-open-topic' can be called to download
a topic that hasn't yet been stored locally.
FIREFOX ITS-ALL-TEXT ADDON INTEGRATION
Firefox supports "It's All Text!", a plug-in that will allow using emacs (or
any editor) to edit the contents of text areas.
1. Install the add-on from:
https://addons.mozilla.org/en-US/firefox/addon/its-all-text/
2. Setup the auto-mode-alist for ".twiki" above
3. Right-click in a text area in Firefox, select It's All Text ->
Preferences
4. Configure the editor to be "emacsclient", whereever that is on
your system
5. Add ".twiki" to the list of file extensions. If you put it
first, all text areas will default to .twiki when pressing the
hot key or clicking the "Edit" button
Note, on Windows if you have emacs installed and you get errors
about not finding the socket, you may need to specify the full path
to the server socket file that is used by the emacs server you're using.
This would have to go into a ".bat" file that in turn calls emacsclient
with the additional "--server-file=<>" argument, as that can't be put in
the editor command in the Its-All-Text preferences.
To get your server-file, try: (process-get server-process :server-file)
CUSTOMIZATION
M-x customize-group twiki
AUTO-NUMBERING OF HEADINGS
On import or load of a twiki file, if headings were previously
numbered, the numbering and min-level will automatically be
detected. If not, the user must call 'twiki-setup-heading-numbers'
to setup the minimum and maximum heading levels to be numbered.
This sets the variables 'twiki-min-heading-level and
twiki-max-heading-level. All subsequent renumbering will only
affecting headings between min and max inclusive.
All headings are number using "1.2.3" notation, one additional level
of decimal notation for each level deeper than 'twiki-min-heading level:
1. First level
1.1. Next level
1.2. Same level as above
2. Back to first level
TABLES USING 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.
COLSPAN
Twiki tables support colspan by interpreting two adjacent vertical bars
as an extention of the previous column:
| Col 1 | Col 2 |
| Colspan 2 & 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 column-width in orgbl as follows:
| <10> | | <20> |
| *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.
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.
KNOWN ISSUES:
- Two lists that are separated by a blank line in twiki syntax get munged
together as a single list by twiki-render-for-edit