build: update BUILD.md

Signed-off-by: Paul Moore <[email protected]>

Author: pcmoore

BUILD.md

@@ -1,60 +1,49 @@
-# Using Firefox with a Markdown Viewer
+# Viewing the Markdown Versions
 
-The Notebook \*.md files can be viewed using Firefox with the following
-Markdown Viewer: <https://github.com/KeithLRobertson/markdown-viewer>
+In addition to viewing the notebook markdown files on GitHub, the markdown
+files can be viewed with Firefox using the following Markdown Viewer:
 
-Extract from the README:
-
-On Linux: Firefox may not know how to handle markdown files by default.
-A workaround for this is to add a new MIME type for markdown file extensions.
-Add the following XML to *~/.local/share/mime/packages/text-markdown.xml*:
-
-```
-<?xml version="1.0"?>
-<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
-  <mime-type type="text/plain">
-    <glob pattern="*.md"/>
-    <glob pattern="*.mkd"/>
-    <glob pattern="*.mkdn"/>
-    <glob pattern="*.mdwn"/>
-    <glob pattern="*.mdown"/>
-    <glob pattern="*.markdown"/>
-  </mime-type>
-</mime-info>
-```
-
-Then run:
-
-`update-mime-database ~/.local/share/mime`
-
-<br>
-
-# Build Single HTML or PDF files
-
-The `Makefile` is work in progress as the PDF files produced have issues
-rendering complex tables and/or images to fit a page.
+* https://github.com/KeithLRobertson/markdown-viewer
 
-Pandoc is required to build the HTML version:
-
-`dnf install pandoc`
-
-and these build the PDF versions:
-
-```
-dnf install weasyprint
-dnf install texlive
-```
-
-Use `make html` or `make pdf`
-
-The `make html` target will build *html/SELinux_Notebook.html*, then use this
-to produce the PDF versions.
-
-The *html/SELinux_Notebook.html* renders in a brower ok, however the PDF
-versions have issues with either `make html` or `make pdf`, for example:
+Extract from the README:
 
--   With **--pdf-engine=weasyprint**, the larger images (e.g Figure 2) and
-    larger tables (e.g. those in the 'Using libselinux Functions' section)
-    are not rendered to fit page and are therefore chopped.
--   With **--pdf-engine=xelatex**, the more complex tables are not rendered
-    correctly.
+> On Linux: Firefox may not know how to handle markdown files by default.
+> A workaround for this is to add a new MIME type for markdown file extensions.
+> Add the following XML to *~/.local/share/mime/packages/text-markdown.xml*:
+> 
+> ```xml
+> <?xml version="1.0"?>
+> <mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
+>   <mime-type type="text/plain">
+>     <glob pattern="*.md"/>
+>     <glob pattern="*.mkd"/>
+>     <glob pattern="*.mkdn"/>
+>     <glob pattern="*.mdwn"/>
+>     <glob pattern="*.mdown"/>
+>     <glob pattern="*.markdown"/>
+>   </mime-type>
+> </mime-info>
+> ```
+> 
+> Then run:
+> 
+>     % update-mime-database ~/.local/share/mime
+
+# Build HTML or PDF Versions
+
+The SELinux Notebook can be rendered in both HTML and PDF using the included
+Makefile.  In order to build these versions of the notebook, "pandoc" and
+"weasyprint" must be installed on your system; consult your distribution
+documentation for information on installing these packages.
+
+Once the required packages are installed can generate the PDF notebook with the
+following command:
+
+	% make pdf
+
+... and the following will generate the HTML notebook:
+
+	% make html
+
+The PDF and HTML notebooks will be generated in newly created "pdf" and "html"
+directories.

README.md

@@ -65,6 +65,5 @@ Logo designed by [*Máirín Duffy*](http://pookstar.deviantart.com/)
 
 ## Building HTML/PDF Versions
 
-The [**BUILD.md**](BUILD.md) file describes how to build these, however
-the best way to view is using a browser with a
-[**Markdown Viewer**](BUILD.md) addon.
+The [**BUILD.md**](BUILD.md) file has more information on building HTML and PDF
+versions of the notebook as well as alternate ways to view the source markdown.