[elpa] externals/lentic 9ac92a57fa 247/333: Improved README and added getting started.

[ELPA Syncer]

branch: externals/lentic
commit 9ac92a57fa9bacdb0a21a25f603cdb4a568672f6
Author: Phillip Lord <phillip.lord@newcastle.ac.uk>
Commit: Phillip Lord <phillip.lord@newcastle.ac.uk>

    Improved README and added getting started.
---
 README.md      |  4 ++-
 lenticular.org | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b52334559c..aab77c1f14 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+
 Lentic allows two buffers to share the same or similar content but
 otherwise operate independently. This can be used for several different
 purposes. Different buffers can be in the same mode, with different locations
@@ -16,7 +17,8 @@ an entirely valid Lisp file. The lentic documentation is 
self-hosting -- the
 source code contains all of the documentation written in Org-mode. It can be
 generated and viewed using the menu items (Edit->Lentic->Read Doc), or it can
 be viewed at
-http://homepages.cs.ncl.ac.uk/phillip.lord/lentic/lenticular.html.
+http://homepages.cs.ncl.ac.uk/phillip.lord/lentic/lenticular.html. Getting
+Started documentation is [available](lenticular.org#getting-started).
 
 As well as the core library, this package also contains various syntactic
 transformations, and a minor-mode for manipulating lentic buffers from a user
diff --git a/lenticular.org b/lenticular.org
index 92c9908676..f8a3af3a13 100644
--- a/lenticular.org
+++ b/lenticular.org
@@ -29,6 +29,85 @@ this makes it both harder to read than ideal, nor the best 
advert for lentic.
 It will improve!
 
 
+* Getting Started
+
+In this section, I describe how to use one particular use of lentic --
+translating between Emacs-Lisp and Org-mode. This is not the only use of
+lentic as it neither specific to Emacs-Lisp nor Org-mode, but it's an easy one
+to get started with.
+
+** Installing
+
+Lentic can be installed using MELPA or Marmalade. Personally, I like MELPA
+stable, so add the following to your ~.emacs~ file.
+
+#+begin_src emacs-lisp
+(add-to-list 'package-archives
+             '("melpa-stable" . "http://stable.melpa.org/packages/";) t)
+#+end_src
+
+Now install "lentic" and then type ~M-x global-lentic-mode~.
+
+
+** With existing lentic source
+
+The easiest way to use lentic is with source which is already formatted
+appropriately for lentic, including the source code for lentic. 
+
+First, clone the lentic repository. This contains a ~.dir-locals.el~ file, in
+addition to the source, which tells lentic how to create a lentic-buffer.
+
+#+begin_example
+git clone https://github.com/phillord/lentic.git
+#+end_example
+
+Now, open lentic.el in Emacs. You should get prompted to accept a unsafe
+directory local variable. If you trust me, then type "y" or "!".
+
+To create the lentic buffer, press ~C-c,c~ or "Edit->Lentic->Create All",
+followed by ~C-c,b~ or "Edit->Lentic->Split Below" to show both Emacs-Lisp and
+Org-mode file at the same time.
+
+** Converting legacy source
+
+To convert some an existing source file called, say, blah.el into a lentic
+file.
+
+ - Add ~;; #+BEGIN_SRC emacs-lisp~ after introductory comments but before any
+   source.
+ - Add ~;; #+END_SRC~ as the last line.
+ - Before the file header (if you have one!), add ~;;; Header:~
+ - Add a ~.dir-local.el~ as follows:
+
+#+begin_src emacs-lisp
+((emacs-lisp-mode
+  (lentic-init . lentic-orgel-org-init)))
+#+end_src
+
+You should now have something like this:
+
+#+begin_src emacs-lisp
+;;; blah.el --- stuff, stuff stuff
+
+;;; Header:
+
+;; This file is not part of Emacs
+
+;;; Code:
+
+;; #+BEGIN_SRC emacs-lisp
+(provide 'blah)
+;; #+END_SRC
+#+end_src
+
+Your buffer should now be set up for lentic. Either close and reopen or type
+~M-x revert-buffer~ to ensure `lentic-init' has been configured.
+
+To add documentation, I make heavy use of `org-babel-demarcate-block' to split
+the single large Emacs-Lisp code blocks into smaller blocks as I go. The whole
+buffer remains properly formatted throughout this way.
+
+
 * Lentic
 
 lentic.el is the central point of this package. It provides the base
@@ -44,7 +123,6 @@ lentic buffers.
 
 #+include: "lentic-mode.org" :minlevel 2
 
-
 * Lentic Rot13
 
 lentic-rot13.el is entirely useless for practical purposes but demonstrates