branch: elpa/adoc-mode
commit a976f1ac84efa78ee1e7d53427d21f5cb61f6794
Author: Florian Kaufmann <sensor...@gmail.com>
Commit: Florian Kaufmann <sensor...@gmail.com>
edited commentary section
- added chapter for installing via packages, features and a screenshot
- changed syntax to Markdown
- fixed typos
- changed todo list
---
adoc-mode.el | 176 ++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 120 insertions(+), 56 deletions(-)
diff --git a/adoc-mode.el b/adoc-mode.el
index b9b08e8d48..1c4f33bf7d 100644
--- a/adoc-mode.el
+++ b/adoc-mode.el
@@ -27,85 +27,149 @@
;; Floor, Boston, MA 02110-1301, USA.
;;
;;
+;; The syntax of the following commentary section is Markdown, so the same text
+;; can be used for the wiki page on GitHub. Also, each paragraph, including
list
+;; items, are separated by blank lines, so it also looks good on Marmalade.
;;; Commentary:
;;
-;; AsciiDoc (http://www.methods.co.nz/asciidoc/) is a text document format for
+;; # Introduction
+;;
+;; [AsciiDoc](http://www.methods.co.nz/asciidoc/) is a text document format for
;; writing short documents, articles, books and UNIX man pages. AsciiDoc files
;; can be translated to HTML and DocBook markups.
-;;
-;; This is just a first version which works not too bad for my small uses of
-;; AsciiDoc. It's mostly about syntax highlighting. I still like to play a lot
-;; and thus it's not stable at all.
-;;
-;; I actually would like to improve it, but realistically will invest
-;; my time in other activities.
-;;
-;; Installation:
-;;
+;;
+;; adoc-mode is an Emacs major mode for editing AsciiDoc files. It emphasizes
on
+;; the idea that the document is highlighted so it pretty much looks like the
+;; final output. What must be bold is bold, what must be italic is italic etc.
+;; Meta characters are naturally still visible, but in a faint way, so they can
+;; be easily ignored.
+;;
+;;
+;; # Download
+;;
+;; The raw file (adoc-mode.el) can be found
+;; [here](https://raw.github.com/sensorflo/adoc-mode/master/adoc-mode.el).
+;; Optionally you can get the sources from the [git
+;; repository](https://github.com/sensorflo/adoc-mode).
+;;
+;; You will also need to download the library
+;; [markup-faces](https://github.com/sensorflo/markup-faces). If you install
+;; adoc-mode via Emacs Lisp Packages, see below, markup-faces is installed
+;; automatically if you don't have it yet.
+;;
+;;
+;; # Installation
+;;
;; Installation is as usual, so if you are proficient with Emacs you don't need
;; to read this.
-;;
-;; 1. Copy this file to a directory in `load-path'. To add a specific directory
-;; to the load path, add this to your initialization file (~/.emacs or
~/_emacs):
-;; (add-to-list 'load-path "mypath")
-;;
-;; 2. Add either of the two following lines to your initialization file:
-;; a) (autoload 'adoc-mode "adoc-mode")
-;; b) (require 'adoc-mode)
-;; The first only loads adoc mode when necessary, the 2nd always during
-;; startup of Emacs.
-;;
-;; 3. To use adoc mode, call adoc-mode after you opened an AsciiDoc file
-;; M-x adoc-mode
-;;
+;;
+;; ## Install the traditional way
+;;
+;; 1. Copy the file adoc-mode.el to a directory in your load-path, e.g.
+;; \~/.emacs.d. To add a specific directory to the load path, add this to
our
+;; initialization file (probably ~/.emacs): `(add-to-list 'load-path
+;; "mypath")`
+;;
+;; 2. Add either of the two following lines to your initialization file. The
+;; first only loads adoc mode when necessary, the 2nd always during startup
+;; of Emacs.
+;;
+;; * `(autoload 'adoc-mode "adoc-mode")`
+;;
+;; * `(require 'adoc-mode)`
+;;
+;; 3. Optionally byte compile adoc-mode.el for faster startup: `M-x
+;; byte-compile`
+;;
+;; 4. To use adoc mode, call adoc-mode after you opened an AsciiDoc file: `M-x
+;; adoc-mode`
+;;
+;;
+;; ## Install via Emacs Lisp Packages (on Marmalade)
+;;
+;; For this way you either need packages.el from
+;; [here](https://github.com/technomancy/package.el) and or Emacs 24, where the
+;; packages library is already included. adoc-mode is on the
+;; [Marmalade](http://marmalade-repo.org/) package archive.
+;;
+;; * Type `M-x package-install RET adoc-mode RET`.
+;;
+;;
+;; ## Possible steps after installation
+;;
;; Each of the following is optional
-;;
-;; * Byte compile this file (adoc-mode.el) for faster startup:
-;; M-x byte-compile
-;;
-;; * According to AsciiDoc manual, '.txt' is the standard file extension for
+;;
+;; * According to AsciiDoc manual, .txt is the standard file extension of
;; AsciiDoc files. Add the following to your initialization file to open all
-;; '.txt' files with adoc-mode as major mode automatically:
-;; (add-to-list 'auto-mode-alist (cons "\\.txt\\'" 'adoc-mode))
-;;
+;; .txt files with adoc-mode as major mode automatically: `(add-to-list
+;; 'auto-mode-alist (cons "\\.txt\\'" 'adoc-mode))`
+;;
;; * If your default face is a fixed pitch (monospace) face, but in AsciiDoc
;; files you liked to have normal text with a variable pitch face,
-;; `buffer-face-mode' is for you:
-;; (add-hook 'adoc-mode-hook (lambda() (buffer-face-mode t)))
+;; buffer-face-mode is for you: `(add-hook 'adoc-mode-hook (lambda()
+;; (buffer-face-mode t)))`
+;;
+;;
+;; # Features
+;;
+;; - sophisticated highlighting
+;;
+;; - promote / denote title
+;;
+;; - toggle title type between one line title and two line title
+;;
+;; - adjust underline length of a two line title to match title text's length
+;;
+;; - goto anchor defining a given id, default reading from xref at point
+;;
+;; - support for outline (however only with the one-line title style)
+;;
+;;
+;; ## Coming features
+;;
+;; The next features I plan to implement
+;;
+;; - Denote / promote for list items
+;; - Outline support also for two line titles
+;; - Correctly highlighting backslash escapes
+;;
+;;
+;; # Screenshot
+;;
+;; The highlighting emphasizes on how the output will look like. _All_
+;; characters are visible, however meta characters are displayed in a faint
way.
+;;
+;; 
;;
;;
-;; Todo:
+;;; Todo:
;; - Fontlock
-;; - make font-lock regexps based upon AsciiDoc configuration file, or
-;; make them configurable in a way similar to that configuration file
+;; - make font-lock regexps based upon AsciiDoc configuration file, or make
+;; them configurable in a way similar to that configuration file
;; - respect font-lock-maximum-decoration
-;; - Other common emacs functionality/features
-;; - indent functions
-;; - imenu / outline / hideshow
+;; - delimited blocks are supported, but not well at all
+;; - Most regexps for highlighting can spawn at most over two lines.
+;; - font-lock's multi line capabilities are not used well enough. At least 2
+;; line spawns should be covered - replace all .*? by .*?\\(?:\n.*?\\)??
+;; - backslash escapes are seldom highlighted correctly
+;; - Other common Emacs functionality/features
+;; - denote/promote/create/delete titles/list-items. Also put emphasis on a
+;; convenient simple user interface.
+;; - imenu / hideshow
+;; - outline mode shall support two line titles
;; - tags tables for anchors, indixes, bibliography items, titles, ...
-;; - Make 'compilation', i.e. translating into the desired output format more
-;; conventient
-;; - tempo-templates
-;; - spell check shall ignore text that is not part of the output
+;; - spell check shall ignore meta characters
;; - supply a regexp for magic-mode-alist
;; - Is there something that would remove hard newlines within a paragraph,
;; but just for display, so the paragraph uses the whole buffer length.
;; - are there generic base packages to handle lists / tables?
-;; - a readonly view mode where commands for navigation are on short key
+;; - a read only view mode where commands for navigation are on short key
;; bindings like alphanum letters
;; - study what other markup modes like rst offer
;; - AsciiDoc related features
-;; - Two (or gruadualy fading) display modes: one emphasises to see the
+;; - Two (or gradually fading) display modes: one emphasises to see the
;; AsciiDoc source text, the other emphasises to see how the output will
-;; look like.
-;; - invisible text property could be used to hide meta characters
-;;
-;; Bugs:
-;; - delimited blocks are supported, but not well at all
-;; - Most regexps for highlighting can spawn at most over two lines.
-;; - font-lock's multi line capabilities are not used well enough. At least 2
-;; line spawns should be covered - replace all .*? by .*?\\(?:\n.*?\\)??
-;;
+;; look like. Or even hide meta characters all together
;;; Variables:
