This document provides a brief overview of the LIS documentation; in particular, the format used to write it and how to read it.
The LIS documentation is written using LaTeX. TeX along with the LaTeX macros is a powerful typesetting system for writing documents. The LIS documentation, however, does not need the full power that TeX/LaTeX provides. The LIS documentation is being rewritten using AsciiDoc. Like LaTeX, AsciiDoc is text-based markup, thus it plays nicely with version control systems. Like LaTeX, AsciiDoc may be processed into other formats like HTML or PDF. Unlike LaTeX, the AsciiDoc syntax is simple, making the source files both easier to write and easier to read.
The LIS documentation uses the Asciidoctor implementation of the AsciiDoc light weight markup language. Please consult their online documentation for more information.
I will describe three ways to read the LIS documentation.
Since AsciiDoc is plain text, you may read the LIS documentation using a pager like more or less or using an editor like vim or emacs. Since the signal to noise ratio is high for AsciiDoc, this method of reading works very well, especially when working on an HPC system where you may not have many fancy tools installed.
AsciiDoc easily converts to HTML; there are even Firefox and Chrome plugins that can process AsciiDoc on the fly. To use this method, first install either the Firefox or Chrome browser and then install the ‘Asciidoctor.js Live Preview’ extension. (Please consult your sysadmin for help.) Then open the desired document in Firefox/Chrome and click on the ‘A’ in the toolbar; et voilà, pretty documentation. This method works well when you have the LIS source code on your laptop.
Please note that development for the Chrome extension is more active.
You can process the AsciiDoc source yourself, using the asciidoctor toolset. With this toolset, you can generate an HTML or PDF version of the documentation. If you are masochistic, then you can even generate a DocBook version. And, then using various DocBook tools, you can render whatever you want. It is beyond the scope of this README to describe how to install asciidoctor and its dependencies. Please see the asciidoctor website and consult your sysadmin. This method is not recommended for the general LIS user. The Pager/Editor and Web Browser methods are better choices. Also note that a PDF version of the documentation will be available on the LIS web-site. This method is recommended only for documentation writers (LIS developers).
Here are some tips for reading the LIS documentation using vim or emacs. It is beyond the scope of this README to teach how to use either vim or emacs. Please consult your local guru for additional help.
What about us vi users?
Please run
% vi
Did you get something like
~ ~ ~ VIM - Vi IMproved ~ ~ version 8.0.94 ~ by Bram Moolenaar et al. ~ Vim is open source and freely distributable ~ ~ Help poor children in Uganda! ~ type :help iccf<Enter> for information ~ ~ type :q<Enter> to exit ~ type :help<Enter> or <F1> for on-line help ~ type :help version8<Enter> for version info ~ ~
Surprise! you are actually a vim user.
Open the documentation in read-only mode, unless of course you actually need to edit it.
% vim -R README
vim understands the AsciiDoc syntax. After opening the documentation, execute these vim command-line mode commands:
:set syntax on :autocmd BufRead,BufNewFile *.adoc setfiletype asciidoc
Each paragraph is written as a single line. This may look bad in vim. Execute these vim command-line mode commands:
:set textwidth=0 :set wrap :set linebreak
The vim normal mode commands j and k move down one line and up one line, respectively. For this document that is the same as down one paragraph and up one paragraph. The vim normal mode commands gj and gk respectively move up and down one virtual line. You should need these movement commands only when editing this document. When simply reading it, use the vim normal mode commands <C-f> and <C-b> (vim-speak for control-f and control-b) to move forward and backwards, respectively, one page at a time.