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