This document provides a brief overview of the LISF documentation; in particular, the format used to write it and how to read it.
The LISF documentation is written 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 LISF documentation uses the Asciidoctor implementation of the AsciiDoc light weight markup language. Please consult the AsciiDoc online documentation for more information.
I will describe three ways to read the LISF documentation.
Since AsciiDoc is plain text, you may read the LISF 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 render 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.) With the browser extension installed and enabled, use the links below or navigate to the desired document here on GitHub and click the "Raw" button located at the top-right of the document pane. After several seconds the extension will render the document; et voilà, pretty documentation!
If you have the LISF source code on your personal computer you can also view the rendered documentation by dragging the desired document (e.g., LISF/docs/LIS_users_guide/LIS_usersguide.adoc) to an open browser window.
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 LISF 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 (LISF developers).
Here are some tips for reading the LISF 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.