diff options
author | rillig <rillig@pkgsrc.org> | 2019-04-28 15:22:24 +0000 |
---|---|---|
committer | rillig <rillig@pkgsrc.org> | 2019-04-28 15:22:24 +0000 |
commit | d0afa28db92eada10921f615622feb25373c1cf0 (patch) | |
tree | ec451d2feb2dc7a801e5d492407c23a10810f109 /doc/guide | |
parent | c178b464195a8d380b90b50dd9d07dbf2e420ba1 (diff) | |
download | pkgsrc-d0afa28db92eada10921f615622feb25373c1cf0.tar.gz |
doc/guide: add autogenerated chapter containing topics from "bmake help"
Diffstat (limited to 'doc/guide')
-rw-r--r-- | doc/guide/Makefile | 8 | ||||
-rw-r--r-- | doc/guide/files/Makefile | 3 | ||||
-rw-r--r-- | doc/guide/files/chapters.ent | 3 | ||||
-rw-r--r-- | doc/guide/files/generate-help-topics.pl | 49 | ||||
-rw-r--r-- | doc/guide/files/help-devel.xml | 5 | ||||
-rw-r--r-- | doc/guide/files/help-topics.tmpl.xml | 15 | ||||
-rw-r--r-- | doc/guide/files/help-user.xml | 16 | ||||
-rw-r--r-- | doc/guide/files/pkgsrc.xml | 5 |
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,&,\&,g; + $topic =~ s,<,\<,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=…</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> |