1# Updating LFE Documentation 2 3## Structure 4 5In order to support multiple format document generation as well as inclusion 6in a LFE static documentation site generator, the LFE docs moved from ``.txt`` 7files to ``.md`` files. The old ``.txt`` files are still provided in their 8original locations (though their formatting has changed a little), however 9these files are now generated from the Markdown source files in ``doc/src``. 10 11In addition to generating the "classic" LFE text file documentation, LFE man 12pages are now also generated and provided in the LFE git repo. There are 13also ``make`` targets for generating ``.pdf`` and ``.epub`` versions of the 14LFE docs, but these are not maintained in the git repo. 15 16The layout of the LFE documentation files tracked by the LFE git repository is 17as follows: 18 19* ``doc/src/*.md`` - Canonical LFE documentation 20* ``doc/*.txt`` - Auto-generated LFE documentation in plain-text format 21* ``doc/man/*.[1-7]`` - Auto-generated LFE documentation in man-page format 22 23Files not tracked by the repository but present after running ``make docs-all`` 24are as follows: 25 26* ``doc/pdf/*.pdf`` 27* ``doc/epub/*.epub`` 28 29 30## (Re)Building the Docs 31 32There are two ways of updating the LFE documentation: 33 34* Native: running the ``make docs`` or ``make docs-all`` targets 35* Docker: running the ``make docker-docs`` target 36 37 38### Native 39 40Building LFE documentation natively on one's system depends upon Pandoc, which 41in turn depends upon Haskell. Furthermore, the ``groff`` and ``col`` utilities 42are used to required to convert man page files to the preferred plain-text 43format. 44 45On Debian-based systems, these may be installed with the following: 46 47``` 48$ sudo apt-get install -y pandoc groff groff-base bsdmainutils 49``` 50 51Since ``col`` will need to have a UTF-8 locate configured, we also recommend 52the following: 53 54``` 55$ sudo locale-gen en_US.UTF-8 UTF-8 56$ sudo dpkg-reconfigure locales 57``` 58 59After running the first command, if you're ``/etc/locale.gen`` file still has 60your preferred locale commented out, you may need to edit that file and then 61re-run ``sudo locale-gen && sudo dpkg-reconfigure locales``. 62 63At this point, you should have everything ready to generate the LFE docs from 64Markdown source. Regenerating the docs from the source ``.md`` files may then 65be performed by executing the following: 66 67``` 68$ make docs 69``` 70 71 72### Docker 73 74Since the overhead of installing the above documentation dependencies may be 75too much for some users, we have also provided a ``Dockerfile`` in the ``doc`` 76directory for building LFE docs from source without having to install Pandoc, 77Haskell, etc., on your own system. This does, of course, require that you have 78``docker`` installed and running on your system. 79 80You will need to use the LFE docs ``Dockerfile`` to generate an LFE Docker 81image for that has the latest LFE docs in it: 82 83``` 84$ make docker-build 85``` 86 87Then, to generate the LFE docs using the Docker image: 88 89``` 90$ make docker-docs 91``` 92 93This ``make`` target will generate the LFE docs inside the Docker image, but 94it will also mount the local/host ``./doc`` directory, over-writing the 95existing ``doc/*.txt`` and ``doc/man/*.[1-7]`` files. Since these files 96will be regenerated as ``root`` in the Docker image, the final step in the 97``make `` target is to ``chown`` these files to ``$USER:$USER``. 98