From 381e1230d6614ea6267080404ce25f65e06c1ef3 Mon Sep 17 00:00:00 2001 From: "Kyle J. McKay" Date: Tue, 13 Feb 2018 14:45:17 -0800 Subject: [PATCH] docs: add rules to make .html files The documentation files are written in GFM (Girocco Flavored Markdown) for which we conveniently have a formatter located in the markdown.git submodule. Add a suitable POSIX-compatible Makefile in the docs subdirectory that knows how to process all *.txt files into *.html files using the Markdown.pl script from the markdown.git submodule. Add a "doc" rule to the top-level makefile to facilitate building these "docs" and at the same time enhance the top-level "clean" rule to actually do a clean. The only things required to build the "docs" are: 1) "perL" 5.8 or later is available in the $PATH somewhere 2) the "markdown.git" submodule has been inited (i.e. checked out) 3) a POSIX-compatible make is available No other submodules need be checked out nor is a "special" version of make required. Just running: (cd docs && make) will build the .html versions of all the docs provided the above conditions have been met. Signed-off-by: Kyle J. McKay --- GNUmakefile | 6 +++++ docs/.gitignore | 1 + docs/Makefile | 56 ++++++++++++++++++++++++++++++++++++++++++++++ docs/technical/gc-mini.txt | 3 --- docs/technical/gc.txt | 2 -- 5 files changed, 63 insertions(+), 5 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile diff --git a/GNUmakefile b/GNUmakefile index 78d4894..e22f414 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -20,6 +20,12 @@ install:: all @./install.sh clean:: + rm -f apache.conf + @"$(MAKE)" -C src clean + @"$(MAKE)" -C docs clean + +doc:: + @"$(MAKE)" -C docs apache.conf: apache.conf.in Girocco/Config.pm ./make-apache-conf.sh diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..2d19fc7 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +*.html diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..374ad41 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,56 @@ +.POSIX: + +# Use make V=1 for verbose rule output + +# default target +all: + +AT = @ +Q_ = $(AT) +Q_0 = $(Q_) +Q = $(Q_$(V)) +SILENT = -s +S_ = $(SILENT) +S_0 = $(S_) +S = $(S_$(V)) +QHTML_ = $(AT)echo "[HTML] $@" && +QHTML_0 = $(QHTML_) +QHTML = $(QHTML_$(V)) + +PERL = perl +MDOPTS = --stub +MDSCRIPT = ../markdown.git/Markdown.pl +MARKDOWN = $(PERL) $(MDSCRIPT) $(MDOPTS) + +# Clean out the standard six single suffix inference rules +.SUFFIXES: +.SUFFIXES: .c .sh .f .c˜ .sh˜ .f˜ +.c:; +.f:; +.sh:; +.c~:; +.f~:; +.sh~:; +.SUFFIXES: +.SUFFIXES: .txt .html + +$(MDSCRIPT) : + $(AT)echo "error: missing \"$(MDSCRIPT)\"" >&2 && \ + echo "error: did you forget to init the markdown.git submodule?" >&2 && \ + ! : + +# Pacify stupid makes +Makefile: + @true + +.txt.html: + $(QHTML)$(MARKDOWN) $< >$@ + +all : doc + +doc : $(MDSCRIPT) + +$(AT)f=; for t in *.txt howto/*.txt technical/*.txt; do test "$${t%?????}*.txt" = "$$t" || f="$$f $${t%.txt}.html"; done; \ + test "$$f" = "" || $(MAKE) $(S) $$f + +clean : + +$(Q)rm -f *.html howto/*.html technical/*.html diff --git a/docs/technical/gc-mini.txt b/docs/technical/gc-mini.txt index 900125b..51abc40 100644 --- a/docs/technical/gc-mini.txt +++ b/docs/technical/gc-mini.txt @@ -106,6 +106,3 @@ collection capability for Girocco. As long as `jobd.pl` runs continuously (or often enough in `--all-once` mode), Girocco's repositories will generally be kept in a well-maintained state. - - - diff --git a/docs/technical/gc.txt b/docs/technical/gc.txt index fc206e3..dbb4671 100644 --- a/docs/technical/gc.txt +++ b/docs/technical/gc.txt @@ -431,5 +431,3 @@ use of linked working trees) are now reluctantly "tolerated." [1]: http://repo.or.cz/girocco.git/a7ea68a8a80e43d5 "gc: retain recently unreferenced objects for 1 day, 2015-10-02" - - -- 2.11.4.GIT