doc/guide: add autogenerated chapter containing topics from "bmake help"

8 files changed, 97 insertions, 7 deletions

diff --git a/doc/guide/Makefile b/doc/guide/Makefile
index e5325a812af..dfeffee92b5 100644
--- a/doc/guide/Makefile
+++ b/doc/guide/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.52 2019/04/09 13:43:53 leot Exp $
+# $NetBSD: Makefile,v 1.53 2019/04/28 15:22:24 rillig Exp $
 
 DISTNAME=		pkgsrc-guide-${PKGVERSION}
 CATEGORIES=		# empty
@@ -16,6 +16,7 @@ PKGVERSION!=		date '+%Y%m%d'
 DIST_SUBDIR=		${PKGBASE}
 USE_LANGUAGES=		# empty
 MAKE_ENV+=		SED=${SED:Q}
+USE_TOOLS+=		perl
 
 PLIST_VARS=		ascii html pdf
 
@@ -63,6 +64,11 @@ pre-extract:
 	${MKDIR} ${WRKSRC}
 	${LN} -s ${FILESDIR}/* ${WRKSRC}
 
+post-extract: generate-help-topics
+generate-help-topics: .PHONY
+	${RUN} ${MAKE} help topic=:index > ${WRKSRC}/help-topics.data
+	${RUN} cd ${WRKSRC} && perl generate-help-topics.pl 
+
 do-build:
 .for _output_ in ${OUTPUTS}
 	@${ECHO} "-----> Building ${_output_} output"
diff --git a/doc/guide/files/Makefile b/doc/guide/files/Makefile
index a0f9126f8c0..b989fe42505 100644
--- a/doc/guide/files/Makefile
+++ b/doc/guide/files/Makefile
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.18 2019/04/28 13:41:18 rillig Exp $
+# $NetBSD: Makefile,v 1.19 2019/04/28 15:22:24 rillig Exp $
 
 WEB_PREFIX?=		${.CURDIR}/../htdocs
 DBX_XML_CATALOG?=	${SGML_PREFIX}/docbook/4.5/catalog.xml
@@ -25,6 +25,7 @@ SRCS+=	fixes.xml
 SRCS+=	ftp-layout.xml
 SRCS+=	getting.xml
 SRCS+=	help-devel.xml
+SRCS+=	help-topics.xml
 SRCS+=	help-user.xml
 SRCS+=	infr.design.xml
 SRCS+=	introduction.xml
diff --git a/doc/guide/files/chapters.ent b/doc/guide/files/chapters.ent
index ea1a4df7343..4f0000197f7 100644
--- a/doc/guide/files/chapters.ent
+++ b/doc/guide/files/chapters.ent
@@ -1,7 +1,7 @@
 <!--
 	Creates entities for each chapter in the pkgsrc book.
 
-	$NetBSD: chapters.ent,v 1.18 2019/04/28 13:41:18 rillig Exp $
+	$NetBSD: chapters.ent,v 1.19 2019/04/28 15:22:24 rillig Exp $
 -->
 
 <!ENTITY chap.intro			SYSTEM "introduction.xml">
@@ -43,4 +43,5 @@
 <!ENTITY chap.examples			SYSTEM "examples.xml">
 <!ENTITY chap.logs			SYSTEM "logs.xml">
 <!ENTITY chap.ftp-layout		SYSTEM "ftp-layout.xml">
+<!ENTITY chap.help-topics		SYSTEM "help-topics.xml">
 <!ENTITY chap.editing			SYSTEM "editing.xml">
diff --git a/doc/guide/files/generate-help-topics.pl b/doc/guide/files/generate-help-topics.pl
new file mode 100644
index 00000000000..354f8159467
--- /dev/null
+++ b/doc/guide/files/generate-help-topics.pl
@@ -0,0 +1,49 @@
+#! perl
+# $NetBSD: generate-help-topics.pl,v 1.1 2019/04/28 15:22:24 rillig Exp $
+
+use strict;
+use warnings;
+
+my $tmpl_file = "help-topics.tmpl.xml";
+my $data_file = "help-topics.data";
+my $out_file  = "help-topics.xml";
+
+sub read_topics() {
+	my @xmltopics;
+	open(my $topics, "<", $data_file) or die;
+	my $header1 = <$topics>;
+	my $header2 = <$topics>;
+
+	while (defined(my $topic = <$topics>)) {
+		chomp($topic);
+		$topic =~ s,&,\&amp;,g;
+		$topic =~ s,<,\&lt;,g;
+		push(@xmltopics, $topic);
+	}
+
+	close($topics) or die;
+	return @xmltopics;
+}
+
+sub merge() {
+	open(my $tmpl, "<", $tmpl_file) or die;
+	open(my $out, ">", "$out_file.tmp") or die;
+
+	while (defined(my $tmpl_line = <$tmpl>)) {
+		if ($tmpl_line =~ /\@topic\@/) {
+			foreach my $xmltopic (read_topics()) {
+				my $line = $tmpl_line;
+				$line =~ s,\@topic\@,$xmltopic,e;
+				print $out ($line);
+			}
+		} else {
+			print $out ($tmpl_line);
+		}
+	}
+	close($tmpl) or die;
+	close($out) or die;
+
+	rename("$out_file.tmp", $out_file) or die;
+}
+
+merge();
diff --git a/doc/guide/files/help-devel.xml b/doc/guide/files/help-devel.xml
index e1e685f332f..945b3346a01 100644
--- a/doc/guide/files/help-devel.xml
+++ b/doc/guide/files/help-devel.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: help-devel.xml,v 1.1 2019/04/28 13:41:18 rillig Exp $ -->
+<!-- $NetBSD: help-devel.xml,v 1.2 2019/04/28 15:22:24 rillig Exp $ -->
 
 <chapter id="help-devel">
 <title>Getting help</title>
@@ -17,6 +17,9 @@
 	<varname>BUILD_DEFS</varname>, a make target like
 	<command>do-build</command>, a missing C or C++ function like
 	<command>strcasecmp</command> or any other topic.</para>
+
+	<para>The available help topics are listed in <xref
+	linkend="help-topics" />.</para>
 </listitem>
 
 <listitem><para>
diff --git a/doc/guide/files/help-topics.tmpl.xml b/doc/guide/files/help-topics.tmpl.xml
new file mode 100644
index 00000000000..5ed9bc11f1e
--- /dev/null
+++ b/doc/guide/files/help-topics.tmpl.xml
@@ -0,0 +1,15 @@
+<!-- $NetBSD: help-topics.tmpl.xml,v 1.1 2019/04/28 15:22:24 rillig Exp $ -->
+
+<appendix id="help-topics">
+<title>Help topics</title>
+
+<para>
+	The following list contains all help topics that are available
+	when running <command>bmake help topic=:index</command>.
+</para>
+
+<itemizedlist>
+	<listitem><para>@topic@</para></listitem>
+</itemizedlist>
+
+</appendix>
diff --git a/doc/guide/files/help-user.xml b/doc/guide/files/help-user.xml
index a710fd5bb76..e17be838eba 100644
--- a/doc/guide/files/help-user.xml
+++ b/doc/guide/files/help-user.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: help-user.xml,v 1.1 2019/04/28 13:41:18 rillig Exp $ -->
+<!-- $NetBSD: help-user.xml,v 1.2 2019/04/28 15:22:24 rillig Exp $ -->
 
 <chapter id="help-user">
 <title>Getting help</title>
@@ -10,6 +10,19 @@
 </para>
 
 <itemizedlist>
+
+<listitem><para>
+	The built-in pkgsrc help, which is available after bootstrapping
+	pkgsrc. Run <command>bmake help topic=&#x2026;</command> to get
+	help for any topic, such as a variable name like
+	<varname>BUILD_DEFS</varname>, a make target like
+	<command>do-build</command>, a missing C or C++ function like
+	<command>strcasecmp</command> or any other topic.</para>
+
+	<para>The available help topics are listed in <xref
+	linkend="help-topics" />.</para>
+</listitem>
+
 <listitem><para>
 	The pkgsrc-users mailing list, to which
 	<ulink url="https://www.NetBSD.org/mailinglists/#pkgsrc-users">you
@@ -24,6 +37,7 @@
 	<ulink url="http://xchat.org/">XChat</ulink>.
 	Pick any user name and join the channel #pkgsrc.</para>
 </listitem>
+
 </itemizedlist>
 
 </chapter>
diff --git a/doc/guide/files/pkgsrc.xml b/doc/guide/files/pkgsrc.xml
index 29793d111ef..2bab23e60b5 100644
--- a/doc/guide/files/pkgsrc.xml
+++ b/doc/guide/files/pkgsrc.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<!-- $NetBSD: pkgsrc.xml,v 1.34 2019/04/28 13:41:18 rillig Exp $ -->
+<!-- $NetBSD: pkgsrc.xml,v 1.35 2019/04/28 15:22:24 rillig Exp $ -->
 
 <!DOCTYPE book PUBLIC "-//NetBSD//DTD DocBook XML V4.5-Based DocBook Extension//EN" [
 
@@ -47,7 +47,7 @@
       <holder role="mailto:www@NetBSD.org">The NetBSD Foundation, Inc</holder>
     </copyright>
 
-    <pubdate>$NetBSD: pkgsrc.xml,v 1.34 2019/04/28 13:41:18 rillig Exp $</pubdate>
+    <pubdate>$NetBSD: pkgsrc.xml,v 1.35 2019/04/28 15:22:24 rillig Exp $</pubdate>
 
     <abstract>
 
@@ -120,5 +120,6 @@
   &chap.examples;
   &chap.logs;
   &chap.ftp-layout;
+  &chap.help-topics;
   &chap.editing;
 </book>