CVS commit: pkgsrc/doc/guide

["Roland Illig" <rillig%netbsd.org@localhost>]

Module Name:    pkgsrc
Committed By:   rillig
Date:           Sun Apr 28 15:22:24 UTC 2019

Modified Files:
        pkgsrc/doc/guide: Makefile
        pkgsrc/doc/guide/files: Makefile chapters.ent help-devel.xml
            help-user.xml pkgsrc.xml
Added Files:
        pkgsrc/doc/guide/files: generate-help-topics.pl help-topics.tmpl.xml

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


To generate a diff of this commit:
cvs rdiff -u -r1.52 -r1.53 pkgsrc/doc/guide/Makefile
cvs rdiff -u -r1.18 -r1.19 pkgsrc/doc/guide/files/Makefile \
    pkgsrc/doc/guide/files/chapters.ent
cvs rdiff -u -r0 -r1.1 pkgsrc/doc/guide/files/generate-help-topics.pl \
    pkgsrc/doc/guide/files/help-topics.tmpl.xml
cvs rdiff -u -r1.1 -r1.2 pkgsrc/doc/guide/files/help-devel.xml \
    pkgsrc/doc/guide/files/help-user.xml
cvs rdiff -u -r1.34 -r1.35 pkgsrc/doc/guide/files/pkgsrc.xml

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/doc/guide/Makefile
diff -u pkgsrc/doc/guide/Makefile:1.52 pkgsrc/doc/guide/Makefile:1.53
--- pkgsrc/doc/guide/Makefile:1.52      Tue Apr  9 13:43:53 2019
+++ pkgsrc/doc/guide/Makefile   Sun Apr 28 15:22:24 2019
@@ -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"

Index: pkgsrc/doc/guide/files/Makefile
diff -u pkgsrc/doc/guide/files/Makefile:1.18 pkgsrc/doc/guide/files/Makefile:1.19
--- pkgsrc/doc/guide/files/Makefile:1.18        Sun Apr 28 13:41:18 2019
+++ pkgsrc/doc/guide/files/Makefile     Sun Apr 28 15:22:24 2019
@@ -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
Index: pkgsrc/doc/guide/files/chapters.ent
diff -u pkgsrc/doc/guide/files/chapters.ent:1.18 pkgsrc/doc/guide/files/chapters.ent:1.19
--- pkgsrc/doc/guide/files/chapters.ent:1.18    Sun Apr 28 13:41:18 2019
+++ pkgsrc/doc/guide/files/chapters.ent Sun Apr 28 15:22:24 2019
@@ -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">

Index: pkgsrc/doc/guide/files/help-devel.xml
diff -u pkgsrc/doc/guide/files/help-devel.xml:1.1 pkgsrc/doc/guide/files/help-devel.xml:1.2
--- pkgsrc/doc/guide/files/help-devel.xml:1.1   Sun Apr 28 13:41:18 2019
+++ pkgsrc/doc/guide/files/help-devel.xml       Sun Apr 28 15:22:24 2019
@@ -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>
Index: pkgsrc/doc/guide/files/help-user.xml
diff -u pkgsrc/doc/guide/files/help-user.xml:1.1 pkgsrc/doc/guide/files/help-user.xml:1.2
--- pkgsrc/doc/guide/files/help-user.xml:1.1    Sun Apr 28 13:41:18 2019
+++ pkgsrc/doc/guide/files/help-user.xml        Sun Apr 28 15:22:24 2019
@@ -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>

Index: pkgsrc/doc/guide/files/pkgsrc.xml
diff -u pkgsrc/doc/guide/files/pkgsrc.xml:1.34 pkgsrc/doc/guide/files/pkgsrc.xml:1.35
--- pkgsrc/doc/guide/files/pkgsrc.xml:1.34      Sun Apr 28 13:41:18 2019
+++ pkgsrc/doc/guide/files/pkgsrc.xml   Sun Apr 28 15:22:24 2019
@@ -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@localhost";>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>

Added files:

Index: pkgsrc/doc/guide/files/generate-help-topics.pl
diff -u /dev/null pkgsrc/doc/guide/files/generate-help-topics.pl:1.1
--- /dev/null   Sun Apr 28 15:22:24 2019
+++ pkgsrc/doc/guide/files/generate-help-topics.pl      Sun Apr 28 15:22:24 2019
@@ -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();
Index: pkgsrc/doc/guide/files/help-topics.tmpl.xml
diff -u /dev/null pkgsrc/doc/guide/files/help-topics.tmpl.xml:1.1
--- /dev/null   Sun Apr 28 15:22:24 2019
+++ pkgsrc/doc/guide/files/help-topics.tmpl.xml Sun Apr 28 15:22:24 2019
@@ -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>