Major mode for editing Twiki wiki files for emacs, plus 'twikish' command line tool to retrieve and save twiki pages from text files.
;;; 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 ;;