pkgsrc-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

[pkgsrc/trunk]: pkgsrc/doc/guide doc/guide: add autogenerated chapter contain...



details:   https://anonhg.NetBSD.org/pkgsrc/rev/eb9fca4910b0
branches:  trunk
changeset: 333008:eb9fca4910b0
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Sun Apr 28 15:22:24 2019 +0000

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

diffstat:

 doc/guide/Makefile                      |   8 ++++-
 doc/guide/files/Makefile                |   3 +-
 doc/guide/files/chapters.ent            |   3 +-
 doc/guide/files/generate-help-topics.pl |  49 +++++++++++++++++++++++++++++++++
 doc/guide/files/help-devel.xml          |   5 ++-
 doc/guide/files/help-topics.tmpl.xml    |  15 ++++++++++
 doc/guide/files/help-user.xml           |  16 ++++++++++-
 doc/guide/files/pkgsrc.xml              |   5 ++-
 8 files changed, 97 insertions(+), 7 deletions(-)

diffs (218 lines):

diff -r 4e75b16af519 -r eb9fca4910b0 doc/guide/Makefile
--- a/doc/guide/Makefile        Sun Apr 28 13:41:18 2019 +0000
+++ b/doc/guide/Makefile        Sun Apr 28 15:22:24 2019 +0000
@@ -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 @@
 DIST_SUBDIR=           ${PKGBASE}
 USE_LANGUAGES=         # empty
 MAKE_ENV+=             SED=${SED:Q}
+USE_TOOLS+=            perl
 
 PLIST_VARS=            ascii html pdf
 
@@ -63,6 +64,11 @@
        ${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 -r 4e75b16af519 -r eb9fca4910b0 doc/guide/files/Makefile
--- a/doc/guide/files/Makefile  Sun Apr 28 13:41:18 2019 +0000
+++ b/doc/guide/files/Makefile  Sun Apr 28 15:22:24 2019 +0000
@@ -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+= 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 -r 4e75b16af519 -r eb9fca4910b0 doc/guide/files/chapters.ent
--- a/doc/guide/files/chapters.ent      Sun Apr 28 13:41:18 2019 +0000
+++ b/doc/guide/files/chapters.ent      Sun Apr 28 15:22:24 2019 +0000
@@ -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 -r 4e75b16af519 -r eb9fca4910b0 doc/guide/files/generate-help-topics.pl
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/generate-help-topics.pl   Sun Apr 28 15:22:24 2019 +0000
@@ -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 -r 4e75b16af519 -r eb9fca4910b0 doc/guide/files/help-devel.xml
--- a/doc/guide/files/help-devel.xml    Sun Apr 28 13:41:18 2019 +0000
+++ b/doc/guide/files/help-devel.xml    Sun Apr 28 15:22:24 2019 +0000
@@ -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 -r 4e75b16af519 -r eb9fca4910b0 doc/guide/files/help-topics.tmpl.xml
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/guide/files/help-topics.tmpl.xml      Sun Apr 28 15:22:24 2019 +0000
@@ -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 -r 4e75b16af519 -r eb9fca4910b0 doc/guide/files/help-user.xml
--- a/doc/guide/files/help-user.xml     Sun Apr 28 13:41:18 2019 +0000
+++ b/doc/guide/files/help-user.xml     Sun Apr 28 15:22:24 2019 +0000
@@ -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 -r 4e75b16af519 -r eb9fca4910b0 doc/guide/files/pkgsrc.xml
--- a/doc/guide/files/pkgsrc.xml        Sun Apr 28 13:41:18 2019 +0000
+++ b/doc/guide/files/pkgsrc.xml        Sun Apr 28 15:22:24 2019 +0000
@@ -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>



Home | Main Index | Thread Index | Old Index