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.

1 files changed, 320 insertions, 0 deletions

diff --git a/src/help.cpp b/src/help.cpp
new file mode 100644
index 0000000..9553f76
--- /dev/null
+++ b/src/help.cpp
@@ -0,0 +1,320 @@
+/*
+ * Copyright (C) 2012-2016 Robin Haberkorn
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifdef HAVE_CONFIG_H
+#include "config.h"
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+
+#include <glib.h>
+#include <glib/gstdio.h>
+#include <glib/gprintf.h>
+
+#include "sciteco.h"
+#include "string-utils.h"
+#include "parser.h"
+#include "qregisters.h"
+#include "ring.h"
+#include "interface.h"
+#include "help.h"
+
+namespace SciTECO {
+
+HelpIndex help_index;
+
+namespace States {
+	StateGetHelp gethelp;
+}
+
+void
+HelpIndex::load(void)
+{
+	gchar *lib_path;
+	gchar *women_path;
+	GDir *women_dir;
+	const gchar *basename;
+
+	lib_path = QRegisters::globals["$SCITECOPATH"]->get_string();
+	women_path = g_build_filename(lib_path, "women", NIL);
+	g_free(lib_path);
+
+	women_dir = g_dir_open(women_path, 0, NULL);
+	if (!women_dir) {
+		g_free(women_path);
+		return;
+	}
+
+	while ((basename = g_dir_read_name(women_dir))) {
+		gchar *filename, *filename_tec;
+		FILE *file;
+		gchar buffer[1024];
+		gchar *topic;
+
+		if (!g_str_has_suffix(basename, ".woman"))
+			continue;
+
+		/*
+		 * Open the corresponding SciTECO macro to read
+		 * its first line.
+		 */
+		filename = g_build_filename(women_path, basename, NIL);
+		filename_tec = g_strconcat(filename, ".tec", NIL);
+		file = g_fopen(filename_tec, "r");
+		g_free(filename_tec);
+		if (!file) {
+			/*
+			 * There might simply be no support script for
+			 * simple plain-text woman-pages.
+			 * In this case we create a topic using the filename
+			 * without an extension.
+			 */
+			topic = g_strndup(basename, strlen(basename)-6);
+			set(topic, filename);
+			g_free(topic);
+			g_free(filename);
+			continue;
+		}
+
+		/*
+		 * Each womanpage script begins with a special comment
+		 * header containing the position to topic index.
+		 * Every topic will be on its own line and they are unlikely
+		 * to be very long, so we can use fgets() here.
+		 * NOTE: Since we haven't opened with the "b" flag,
+		 * fgets() will translate linebreaks to LF even on
+		 * MSVCRT (Windows).
+		 */
+		if (!fgets(buffer, sizeof(buffer), file) ||
+		    !g_str_has_prefix(buffer, "!*")) {
+			interface.msg(InterfaceCurrent::MSG_WARNING,
+			              "Missing or invalid topic line in womanpage script \"%s\"",
+			              filename);
+			g_free(filename);
+			continue;
+		}
+		/* skip opening comment */
+		topic = buffer+2;
+
+		do {
+			gchar *endptr;
+			tecoInt pos = strtoul(topic, &endptr, 10);
+			gsize len;
+
+			/*
+			 * This also breaks at the last line of the
+			 * header.
+			 */
+			if (*endptr != ':')
+				break;
+
+			/*
+			 * Strip the likely LF at the end of the line.
+			 */
+			len = strlen(endptr)-1;
+			if (G_LIKELY(endptr[len] == '\n'))
+				endptr[len] = '\0';
+
+			set(endptr+1, filename, pos);
+		} while ((topic = fgets(buffer, sizeof(buffer), file)));
+
+		fclose(file);
+		g_free(filename);
+	}
+
+	g_dir_close(women_dir);
+	g_free(women_path);
+}
+
+HelpIndex::Topic *
+HelpIndex::find(const gchar *name)
+{
+	Topic *ret;
+
+	/*
+	 * The topic index contains printable characters
+	 * only (to avoid having to perform string building
+	 * on the topic terms to be able to define control
+	 * characters).
+	 * Therefore, we expand control characters in the
+	 * look-up string to their printable forms.
+	 */
+	gchar *term = String::canonicalize_ctl(name);
+
+	Topic topic(term);
+	ret = (Topic *)RBTree::find(&topic);
+	g_free(term);
+
+	return ret;
+}
+
+void
+HelpIndex::set(const gchar *name, const gchar *filename, tecoInt pos)
+{
+	Topic *topic = new Topic(name, filename, pos);
+	Topic *existing;
+
+	existing = (Topic *)RBTree::find(topic);
+	if (existing) {
+		gchar *basename;
+
+		if (!strcmp(existing->filename, filename)) {
+			/*
+			 * A topic with the same name already exists
+			 * in the same file.
+			 * For the time being, we simply overwrite the
+			 * last topic.
+			 * FIXME: Perhaps make it unique again!?
+			 */
+			existing->pos = pos;
+			delete topic;
+			return;
+		}
+
+		/* in another file -> make name unique */
+		interface.msg(InterfaceCurrent::MSG_WARNING,
+		              "Topic collision: \"%s\" defined in \"%s\" and \"%s\"",
+		              name, existing->filename, filename);
+
+		String::append(topic->name, ":");
+		basename = g_path_get_basename(filename);
+		String::append(topic->name, basename);
+		g_free(basename);
+	}
+
+	RBTree::insert(topic);
+}
+
+/*
+ * Command states
+ */
+
+/*$
+ * ?[topic]$ -- Get help for topic
+ *
+ * Look up <topic> in the help index, opening
+ * the corresponding womanpage as a buffer and scrolling
+ * to the topic's position.
+ * The help index is built when this command is first
+ * executed, so the help system does not consume resources
+ * when not used (e.g. in a batch-mode script).
+ *
+ * \*(ST's help documents must be installed in the
+ * directory \fB$SCITECOPATH/women\fP, i.e. as part of
+ * the standard library.
+ * Each document consist of at least one plain-text file with
+ * the extension \(lq.woman\(rq.
+ * Optionally, a \*(ST script with the extension
+ * \(lq.woman.tec\(rq can be installed alongside the
+ * main document to define topics covered by this document
+ * and set up styling.
+ *
+ * The beginning of the script must be a header of the form:
+ * .EX
+ * !*\fIposition\fP:\fItopic1\fP
+ * \fIposition2\fP:\fItopic2\fP
+ * \fI...\fP
+ * *!
+ * .EE
+ * In other words it must be a \*(ST comment followed
+ * by an asterisk sign, followed by the first topic which
+ * is a buffer position, followed by a colon and the topic
+ * string.
+ * The topic string is terminated by the end of the line.
+ * The end of the header is marked by a single \(lq*!\(rq.
+ * Topic terms should be specified with printable characters
+ * only (e.g. use Caret+A instead of CTRL+A).
+ * When looking up a help term, control characters are
+ * canonicalized to their printable form, so the term
+ * \(lq^A\(rq is found both by Caret+A and CTRL+A.
+ * Also, while topic terms are not case folded, lookup
+ * is case insensitive.
+ *
+ * The rest of the script is not read by \*(ST internally
+ * but should contain styling for the main document.
+ * It is usually read by the standard library's lexer
+ * configuration system when showing a womanpage.
+ * If the \(lq.woman.tec\(rq macro is missing,
+ * \*(ST will define a single topic for the document based
+ * on the \(lq.woman\(rq file's name.
+ *
+ * The combination of plain-text document and script
+ * is called a \(lqwomanpage\(rq because these files
+ * are usually generated using \fBgroff\fP(1) with the
+ * \fIgrosciteco\fP formatter and the \fIsciteco.tmac\fP
+ * GNU troff macros.
+ * When using womanpages generated by \fIgrosciteco\fP,
+ * help topics can be defined using the \fBSCITECO_TOPIC\fP
+ * Troff macro.
+ * This flexible system allows \*(ST to access internal
+ * and third-party help files written in plain-text or
+ * with an arbitrary GNU troff macro package.
+ * As all GNU troff documents are processed at build-time,
+ * GNU troff is not required at runtime.
+ *
+ * The \fB?\fP command does not have string building enabled.
+ */
+void
+StateGetHelp::initial(void)
+{
+	/*
+	 * The help-index is populated on demand,
+	 * so we start up quicker and batch mode does
+	 * not depend on the availability of the standard
+	 * library.
+	 */
+	if (G_UNLIKELY(!help_index.min()))
+		help_index.load();
+}
+
+State *
+StateGetHelp::done(const gchar *str)
+{
+	HelpIndex::Topic *topic;
+
+	BEGIN_EXEC(&States::start);
+
+	topic = help_index.find(str);
+	if (!topic)
+		throw Error("Topic \"%s\" not found", str);
+
+	ring.undo_edit();
+	/*
+	 * ED hooks with the default lexer framework
+	 * will usually load the styling SciTECO script
+	 * when editing the buffer for the first time.
+	 */
+	ring.edit(topic->filename);
+
+	/*
+	 * Make sure the topic is visible.
+	 * We do need undo tokens for this (even though
+	 * the buffer is removed on rubout if the woman
+	 * page is viewed first) since we might browse
+	 * multiple topics in the same buffer without
+	 * closing it first.
+	 */
+	interface.undo_ssm(SCI_GOTOPOS,
+	                   interface.ssm(SCI_GETCURRENTPOS));
+	interface.ssm(SCI_GOTOPOS, topic->pos);
+
+	return &States::start;
+}
+
+} /* namespace SciTECO */