This package implements lenticular text: simultaneous editing and viewing of the same (or closely related) text in two or more buffers. While lentic has many potential uses it also enables a form of literate programming. This is the literate documentation for lentic.
Documentation for each package is organised according to approximate usage in documentation terms. So the core package (lentic) comes first, then that associated with the mode, and then a package which is useless but good for understanding how to configure lentic for new environments.
The general idea of using lentic to document itself is a good one; I think the general principle of dogfooding making sense. It has a disadvantage, though. At the moment, lentic is not finished, nor is the transformation that I am using to generate the documentation. So, the output is currently not ideal; this makes it both harder to read than ideal, nor the best advert for lentic.
It will improve!
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.
Lentic can be installed from GNU ELPA, e.g. with M-x list-packages.
Once “lentic” is installed, type M-x global-lentic-mode.
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.
git clone https://github.com/phillord/lentic.git
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.
To convert some an existing source file called, say, blah.el into a lentic file.
- Add
;; #+BEGIN_SRC emacs-lispafter introductory comments but before any source. - Add
;; #+END_SRCas the last line. - Before the file header (if you have one!), add
;;; Header: - Add a
.dir-local.elas follows:
((emacs-lisp-mode
(lentic-init . lentic-orgel-org-init)))You should now have something like this:
;;; blah.el --- stuff, stuff stuff
;;; Header:
;; This file is not part of Emacs
;;; Code:
;; #+BEGIN_SRC emacs-lisp
(provide 'blah)
;; #+END_SRCYour 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.el is the central point of this package. It provides the base configuration options, the hooks into emacs change notification and the default transformation (which copies text exactly).
lentic-mode.el provides end-user functions for creating and manipulating lentic buffers.
lentic-rot13.el is entirely useless for practical purposes but demonstrates how new lenticular transformations can be configured.
Lentic Block provides configurations where blocks of the buffer are commented in one buffer and not in the others. There are quite a few extensions of this configuration, including the one that is used to document this file.
A lentic block configuration for use with asciidoc.
A lentic block configuration for use with latex.
A lentic block configuration for use with org. This includes a more specialised and complex transformation between Emacs-Lisp and Org.
Tools for developers of new configurations.
Lentic has a self-hosting documentation system which is defined here.