reStructuredText is perhaps the smartest smart ASCII yet devised.
Specification available as plain text or HTML. See also MeatBall:ReStructuredText
The home page has a cheat sheet, history, as well as user, reference, and developer documentation.
From ‘An Introduction to reStructured Text’:
To clarify the primary goal, here are specific design goals, in order, beginning with the most important:
David Mertz describes reST (as it is most commonly abbreviated) well in his IBM Developer Works column, XML Matters, as a “A Light, Powerful Document Markup” 2003-02-01, http://www-106.ibm.com/developerworks/library/x-matters24/
As of 2005-12, the emacs packages for reStructuredText have all been merged into one package: rst.el, available here: http://docutils.sourceforge.net/tools/editors/emacs/rst.el
(This package contains StefanMerten’s rst-mode.el, MartinBlais’ restructuretext.el and other, and DavidGoodger’s utility functions. All those original packages are obsoleted and should be replaced by rst.el)
Setup info and detailed documentation is available here: http://docutils.sourceforge.net/docs/user/emacs.html
I wrote rst file in Chinese, when typing C-c p t
to display contents, only English titles displayed, all other Chinese titles didn’t displayed at all. Is it a bug or I missed somthing?
Seems like this mode operates really slowly right now (05th April 2008). Trying to edit a reStructuredText file with about 800 lines forces me to wait at least one second before anything I’ve typed will show up. I found this message regarding the switch to jit-lock, and it helps a little, but not enough to make rst-mode actually usable with syntax highlighting. This is not exactly a slow machine either (3.0 GHz P4 HT). Does anybody have any ideas on how to speed it up, or is this more an implementation efficiency problem? (UPDATE: it turns out that currently setting “rst-mode-lazy” to nil disables section and block highlighting, but improves speed incredibly.) – TaylorVenable
Code to check that a buffer of reStructured Text is valid when saving:
(defun rst-validate-buffer () "Tests to see if buffer is valid reStructured Text." (interactive) (if (eq major-mode 'rst-mode) ; only runs in rst-mode (let ((name (buffer-name)) (filename (buffer-file-name))) (cond ((not (file-exists-p "/usr/bin/rst2pseudoxml")) ; check that the program used to process file is present (error "Docutils programs not available.")) ((not (file-exists-p filename)) ; check that the file of the buffer exists (error "Buffer '%s' is not visiting a file!" name)) (t ; ok, process the file, producing pseudoxml output (let* ((pseudoxml (split-string (shell-command-to-string (concat "rst2pseudoxml " filename)) "\n")) (firstline (car pseudoxml)) ; take first line of output (lastline (nth (- (length pseudoxml) 2) pseudoxml))) ; take last line of output text (if (or (string-match "ERROR/" firstline) (string-match "WARNING/" firstline) ;; for reasons I don't understand, sometimes the warnings/errors are at the end of output (string-match "ERROR/" lastline) (string-match "WARNING/" lastline)) (progn (ding) (message "There's an problem in this buffer.")) (message "Buffer is valid reStructured Text.")))))))) (add-hook 'rst-mode-hook (lambda() (add-hook 'after-save-hook 'rst-validate-buffer)))