Proposal to address LibreOffice comment

Signed-off-by: Davide Scano <[email protected]>

docs/v1/Makefile

@@ -8,25 +8,20 @@ all: ${SPEC}.pdf ${SPEC}.html
 build:
 	mkdir -p build
 
-# Note: Brute-force image rendering; could use more precise file-by-file make rules
-figs: build resources/figs/*.odg
-	soffice --convert-to svg --outdir resources/figs/ resources/figs/*.odg > /dev/null 2>&1
-	soffice --convert-to png --outdir resources/figs/ resources/figs/*.odg > /dev/null 2>&1
-
-${SPEC}.pdf: ${SPEC}.adoc figs
+${SPEC}.pdf: ${SPEC}.adoc
 	time asciidoctor-pdf -v \
 	-a pdf-fontsdir=resources/fonts \
 	-r asciidoctor-mathematical \
 	-r asciidoctor-bibtex \
 	-r asciidoctor-lists \
 	-a rouge-style=$(ROUGE_STYLE) $<
 
-${SPEC}.html: ${SPEC}.adoc figs
+${SPEC}.html: ${SPEC}.adoc
 	time asciidoctor -v \
 	-r asciidoctor-mathematical \
 	-r asciidoctor-bibtex \
 	-r asciidoctor-lists \
 	-a rouge-css=$(ROUGE_CSS) $<
 
 clean:
-	/bin/rm -f ${SPEC}.pdf ${SPEC}.html resources/figs/stem-*.png
+	/bin/rm -f ${SPEC}.pdf ${SPEC}.html

docs/v1/README.md

@@ -26,6 +26,23 @@ Files:
       - `*.bib`  - Bibliography file that contains a list of bibliographical item, such as articles, books, and theses.
 - `Makefile` builds documentation in the build subdirectory
 
+## Document Figures
+
+Each image in the specification has a corresponding `.odg` file under
+`figures/`. These are LibreOffice drawing files. The files are rendered into
+`.svg` and `.png` images (for HTML and PDF output, resepectively) at build time,
+using the `soffice` command-line tool. The page size for each image should be
+adjusted manually by the author ("artist") to just fit the image on the
+apparrent "page," to minimize padding around the image in the rendered
+document. Use the menu item `Format | Page/Size Properties.` See the example
+screen shot below. (Do not check the "Fit object to paper format" box - it will
+change the object's aspect ratio.)
+![LibreOffice](libre-office.png)
+
+```
+soffice --convert-to svg --outdir resources/figs/ resources/figs/*.odg > /dev/null
+soffice --convert-to png --outdir resources/figs/ resources/figs/*.odg > /dev/null
+```
 
 ## Building