Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
executable file 287 lines (286 sloc) 9.9 KB
;;; Commentary:
;;
;; 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
;;
;;; TODO:
;;
;; - Handle heading / table number references on renumber
;;
;; - Cell-alignment with orgtbl is different than twiki as twiki
;; uses amount of spaces on either side of the content to align
;; the cell. orgtbl is a little smarter about numbers vs not, and
;; supports left or right alignment. Unclear the best way to
;; combine the two.
;;
;;
;;; CHANGE LOG
;;
;; 2011-07-19 (chris)
;; - First public release
;;
;; 2011-07-21 (chris)
;; - Eliminated the question to add numbering on import, added function
;; "twiki-setup-heading-numbers"
;; - Fixed twiki-electric-space so that it does not break table lines
;;
;; 2011-07-22 (chris)
;; - Fixed bugs with renumbering and non-TOC headers containing "!!"
;; - Added supported for file-save to write twiki-format
;;
;; 2011-07-22 (chris)
;; - Fixed hang on export on a bullet list with an empty bullet
;;
;; 2011-07-22 (chris)
;; - Fixed a bug with list numbering of alphanumeric lists (1., A.)
;;
;; 2011-07-29 (chris)
;; - Added support for orgtbl column-descriptor row, commenting out the line
;; on export, reinstating it on import
;;
;; 2011-07-31 (chris) -- Version 1.0.0
;; - cleaned up the code, made a 'twiki' customozation group
;; - added boolean for disabling orgtbl
;; - fixed faces so they work for light and dark background modes
;;
;; 2011-09-03 (chris) -- Version 1.0.1
;; - fixed twiki-electric-space not to break links
;; of the form [[ref][title]] or [[ref]]
;;
;; 2012-05-14 (chris) -- Version 1.0.2
;; - Fixed twiki-electric-space so that it does not break headings
;;
;; 2012-05-19 (chris)
;; - Fixed handling of links so that they are not broken on save
;; - Added support for C-u C-c <num> to set a heading as invisible to the TOC
;; - Turn on outline-minor-mode and support [tab] and [S-tab] to toggle
;; visiblity of subtrees
;;
;; 2012-06-20 (chris) -- Version 1.1.0
;; - Better line break support when links are in a line
;; - Added `twiki-verbatim' [C-c v] to add <verbatim></verbatim>
;; around a block
;;
;; 2012-08-01 (chris) -- Version 1.2
;; - Drop '-' as bullet marker, as this causes problems when '-'
;; in a bullet line happens to end up after a line break
;; - Fixed logic regarding import and overwriting the buffer
;; - Fixed twiki-electric-space so that it does not break incomplete
;; table lines (ie, regonized a table line as starting with |, but
;; not necessarily ending with |)
;; - Added support for twikish command line tool
;;
;; 2012-11-05 (chris) -- Version 1.3
;; - Added font-lock for bumpy case links
;; - Fixed buffer showing modified after save
;; - Fixed problems with longlines-mode
;;
;; 2013-03-04 (chris) -- Version 1.3.1
;; - Fixed Git issue #1 - Emacs 24 filter-buffer-substring dropped NOPROPS arg
;;