From e7867fb0d9979c550e6e3d7597ece73b680c4af6 Mon Sep 17 00:00:00 2001
From: Robin Haberkorn <robin.haberkorn@googlemail.com>
Date: Fri, 26 Feb 2016 02:02:50 +0100
Subject: implemented self-documenting (online) help system

 * the new "?" (help) command can be used to look up
   help topics.
 * help topics are index from $SCITECOPATH/women/*.woman.tec
   files.
 * looking up a help topic opens the corresponding "womanpage"
   and jumps to the position of the topic (it acts like an anchor
   into the document).
 * styling is performed by *.woman.tec files.
 * Setting up the Scintilla view and munging the *.tec file
   is performed by the new "woman.tes" lexer.
   On supporting UIs (Gtk), womanpages are shown in a variable-width
   font.
 * Woman pages are usually not hand-written, but generated from manpages.
   A special Groff post-processor grosciteco has been introduced for this
   purpose. It is much like grotty, but can output SciTECO macros for styling
   the document (ie. the *.woman.tec files).
   It is documented in its own man-page.
 * grosciteco also introduces sciteco.tmac - special Troff macros
   for controlling the formatting of the document in SciTECO.
   It also defines .SCITECO_TOPIC which can be used to mark up
   help topics/terms in Troff markup.
 * Woman pages are generated/formatted by grosciteco at compile-time, so
   they will work on platforms without Groff (ie. as on windows).
 * Groff has been added as a hard compile-time requirement.
 * The sciteco(1) and sciteco(7) man pages have been augmented with
   help topic anchors.
---
 doc/Makefile.am | 72 ++++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 59 insertions(+), 13 deletions(-)

(limited to 'doc/Makefile.am')

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9909122..e63284a 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,33 +1,79 @@
 # Make sure that $BOOTSTRAP_SCITECO and the SciTECO-based
 # substitutor is available.
-# The target `sciteco` binary has already been built,
-# but using $BOOTSTRAP_SCITECO ensures that we use
-# a version running on the host machine when cross-compiling
-# with --disable-bootstrap.
 include $(top_srcdir)/bootstrap.am
 
-man_MANS = sciteco.1
-EXTRA_DIST = sciteco.1.in
-CLEANFILES = sciteco.1
+# grosciteco is a troff postprocessor similar to grotty
+# which can be used to produce SciTECO-friendly output
+# (woman pages).
+dist_bin_SCRIPTS = grosciteco.tes
+# grosciteco, like many other postprocessors, works
+# best with its own macro package.
+# Unfortunately, there is no way to query the built-in
+# Groff tmac path.
+# Therefore, the "sciteco" macros are installed into
+# SciTECO's pkgdatadir. Users can copy this file, set up
+# environment variables like $GROFF_TMAC_PATH or pass
+# the directory via `groff -M`.
+dist_pkgdata_DATA = sciteco.tmac
+
+# Fix up the hash-bang line of grosciteco upon installation
+# to refer to the installed sciteco binary.
+# This takes --program-prefix into account.
+install-exec-hook:
+	@SED@ -i "1s,#!.*sciteco,#!$(bindir)/`echo sciteco | @SED@ '$(transform)'`$(EXEEXT)," \
+	         $(DESTDIR)$(bindir)/grosciteco.tes
+
+womendir = $(scitecolibdir)/women
+
+women_DATA = grosciteco.tes.1.woman grosciteco.tes.1.woman.tec
+CLEANFILES = grosciteco.tes.1.intermediate
+
+women_DATA += sciteco.1.woman sciteco.1.woman.tec
+CLEANFILES += sciteco.1.intermediate
+
+women_DATA += sciteco.7.woman sciteco.7.woman.tec
+CLEANFILES += sciteco.7.intermediate
+
+CLEANFILES += $(women_DATA)
+
+# NOTE: *.intermediate files are only generated since SciTECO scripts
+# cannot currently read stdin, so the grosciteco postprocessor
+# has to be run on a separate file.
+%.woman %.woman.tec : %.intermediate grosciteco.tes
+	$(SCITECO_FULL) -m @srcdir@/grosciteco.tes \
+	                   $(basename $<).woman $(basename $<).woman.tec $<
+
+%.intermediate : % sciteco.tmac
+	@GROFF@ -Z -Tascii -t -man -M@srcdir@ -msciteco $< >$@
+
+man_MANS = grosciteco.tes.1
+EXTRA_DIST = grosciteco.tes.1.in
+
+man_MANS += sciteco.1
+EXTRA_DIST += sciteco.1.in
 
 man_MANS += sciteco.7
 EXTRA_DIST += sciteco.7.template
-CLEANFILES += sciteco.7 sciteco.7.in sciteco.7.htbl
+CLEANFILES += sciteco.7.in sciteco.7.htbl
 SOURCES = $(wildcard @top_srcdir@/src/*.cpp)
 
-EXTRA_DIST += generate-docs.tes htbl.tes
+CLEANFILES += $(man_MANS)
+
+dist_noinst_SCRIPTS = generate-docs.tes htbl.tes
 
 %.in : %.template generate-docs.tes $(SOURCES)
-	$(BOOTSTRAP_SCITECO) -m @srcdir@/generate-docs.tes \
-			     $@ $< $(SOURCES)
+	$(SCITECO_FULL) -m @srcdir@/generate-docs.tes \
+	                $@ $< $(SOURCES)
 
 if BUILD_HTMLMAN
-html_DATA = sciteco.1.html sciteco.7.html
+html_DATA = grosciteco.1.html sciteco.1.html sciteco.7.html
 CLEANFILES += $(html_DATA)
 endif
 
+# NOTE: The *.htbl files are only generated since SciTECO
+# scripts cannot be integrated into pipelines easily yet.
 %.htbl : % htbl.tes
-	$(BOOTSTRAP_SCITECO) -m @srcdir@/htbl.tes $< $@
+	$(SCITECO_FULL) -m @srcdir@/htbl.tes $< $@
 
 %.html : %.htbl
 	@GROFF@ -Thtml -man $< >$@
-- 
cgit v1.2.3