
#+TITLE: Lenticular Text For Emacs
#+AUTHOR: Phillip Lord

# FIXME: `ox-texinfo` should use sane defaults like the file's name
#        for TEXINFO_DIR_TITLE and the TITLE for TEXINFO_DIR_DESC?
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: * lentic: (lenticular).
#+TEXINFO_DIR_DESC: Lenticular Text For Emacs

#+INFOJS_OPT: view:info toc:nil


* Introduction

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.

** Caveat

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!


* 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 from GNU ELPA, e.g. with ~M-x list-packages~.
Once "lentic" is installed, 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
configuration options, the hooks into emacs change notification and the
default transformation (which copies text exactly).

#+include: "lentic.org"  :minlevel 2

* Lentic Mode

lentic-mode.el provides end-user functions for creating and manipulating
lentic buffers.

#+include: "lentic-mode.org" :minlevel 2

* Lentic Rot13

lentic-rot13.el is entirely useless for practical purposes but demonstrates
how new lenticular transformations can be configured.

#+include: "lentic-rot13.org" :minlevel 2

* Lentic Chunk

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.

#+include: "lentic-chunk.org" :minlevel 2

* Lentic Asciidoc

A lentic block configuration for use with asciidoc.

#+include: "lentic-asciidoc.org" :minlevel 2

* Lentic Latex

A lentic block configuration for use with latex.

#+include: "lentic-latex-code.org" :minlevel 2

* Lentic Org

A lentic block configuration for use with org. This includes a more
specialised and complex transformation between Emacs-Lisp and Org.

#+include: "lentic-org.org" :minlevel 2

* Lentic Dev

Tools for developers of new configurations.

#+include: "lentic-dev.org" :minlevel 2

* Lentic Doc

Lentic has a self-hosting documentation system which is defined here.

#+include: "lentic-doc.org" :minlevel 2


