[nongnu] elpa/adoc-mode a976f1ac84 085/199: edited commentary section

[ELPA Syncer]

branch: elpa/adoc-mode
commit a976f1ac84efa78ee1e7d53427d21f5cb61f6794
Author: Florian Kaufmann <sensorflo@gmail.com>
Commit: Florian Kaufmann <sensorflo@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.
+;; 
+;; ![screenshot](http://dl.dropbox.com/u/75789984/adoc-mode.png)
 ;;
 ;;
-;; 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: