 @@ -1,14 +1,14 @@
-# $NetBSD: Makefile,v 1.59 2020/01/06 21:34:31 leot Exp $
+# $NetBSD: Makefile,v 1.60 2020/02/23 17:43:20 rillig Exp $
 DISTNAME=		pkgsrc-guide-${PKGVERSION}
 CATEGORIES=		# empty
 MASTER_SITES=		${MASTER_SITE_LOCAL}
 DISTFILES=		htdocs-share-20200106.tar.gz
 MAINTAINER=		pkgsrc-users@NetBSD.org
 HOMEPAGE=		http://www.NetBSD.org/docs/pkgsrc/
 COMMENT=		The pkgsrc guide
 # To regenerate pkgsrc/doc/pkgsrc.{html,txt} and
 # htdocs/docs/pkgsrc, just run "make regen".
 @@ -70,26 +70,29 @@ pre-extract:
 pre-configure: generate-help-topics
 generate-help-topics: .PHONY
 	${RUN} ${MAKE} help topic=:index > ${WRKSRC}/help-topics.data
 	${RUN} cd ${WRKSRC} && env PKGSRCDIR=${PKGSRCDIR} python fill-placeholders.py *.xml
 do-build:
 .for _output_ in ${OUTPUTS}
 	@${ECHO} "-----> Building ${_output_} output"
 	@cd ${WRKSRC} && ${SETENV} ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} ${_output_}
 .endfor
 post-build:
 	@${RM} -f ${WRKSRC}/pkgsrc.tmp.html
 	${RUN} cd ${WRKSRC};						\
 	${GREP} 'idm[0-9][0-9][0-9][0-9][0-9]' ./*.html || exit 0;	\
 	${FAIL_MSG} "[post-build] HTML files contain generated IDs."
 do-install:
 .if !empty(OUTPUTS:Mhtml) || !empty(OUTPUTS:Mhtml-split)
 	${INSTALL_DATA} ${WRKSRC}/*.html ${DESTDIR}${DOCDIR}
 	${INSTALL_DATA} ${WRKDIR}/htdocs/global.css ${DESTDIR}${DOCDIR}
 .endif
 .if !empty(OUTPUTS:Mascii)
 	${INSTALL_DATA} ${WRKSRC}/pkgsrc.txt ${DESTDIR}${DOCDIR}
 .endif
 .if !empty(OUTPUTS:Mpdf)
 	${INSTALL_DATA} ${WRKSRC}/pkgsrc.ps ${DESTDIR}${DOCDIR}
 	${INSTALL_DATA} ${WRKSRC}/pkgsrc.pdf ${DESTDIR}${DOCDIR}
 .endif

 @@ -1,115 +1,115 @@
-<!-- $NetBSD: devfaq.xml,v 1.14 2016/06/11 18:14:42 rillig Exp $ -->
+<!-- $NetBSD: devfaq.xml,v 1.15 2020/02/23 17:43:20 rillig Exp $ -->
 <chapter id="devfaq"> <?dbhtml filename="devfaq.html"?>
 <title>Frequently Asked Questions</title>
 	<para>This section contains the answers to questions that may
 	arise when you are writing a package. If you don't find your
 	question answered here, first have a look in the other chapters,
 	and if you still don't have the answer, ask on the
 	<literal>pkgsrc-users</literal> mailing list.</para>
-<qandaset>
+<qandaset id="devfaq.qandaset">
 <qandaentry id="devfaq.makeflags">
-	<question><para>What is the difference between
+	<question id="devfaq.makeflags.q"><para>What is the difference between
 	<varname>MAKEFLAGS</varname>, <varname>.MAKEFLAGS</varname> and
 	<varname>MAKE_FLAGS</varname>?</para></question>
 	<answer><para><varname>MAKEFLAGS</varname> are the flags passed
 	to the pkgsrc-internal invocations of &man.make.1;, while
 	<varname>MAKE_FLAGS</varname> are the flags that are passed to
 	the <varname>MAKE_PROGRAM</varname> when building the
 	package. [FIXME: What is .MAKEFLAGS for?]</para></answer>
 </qandaentry>
 <qandaentry id="devfaq.make">
-	<question><para>What is the difference between
+	<question id="devfaq.make.q"><para>What is the difference between
 	<varname>MAKE</varname>, <varname>GMAKE</varname> and
 	<varname>MAKE_PROGRAM</varname>?</para></question>
 	<answer><para><varname>MAKE</varname> is the path to the
 	&man.make.1; program that is used in the pkgsrc
 	infrastructure. <varname>GMAKE</varname> is the path to GNU
 	Make, but you need to say <varname>USE_TOOLS+=gmake</varname> to
 	use that. <varname>MAKE_PROGRAM</varname> is the path to the
 	Make program that is used for building the
 	package.</para></answer>
 </qandaentry>
 <qandaentry id="devfaq.cc">
-	<question><para>What is the difference between
+	<question id="devfaq.cc.q"><para>What is the difference between
 	<varname>CC</varname>, <varname>PKG_CC</varname> and
 	<varname>PKGSRC_COMPILER</varname>?</para></question>
 	<answer><para><varname>CC</varname> is the path to the real C
 	compiler, which can be configured by the pkgsrc user.
 	<varname>PKG_CC</varname> is the path to the compiler wrapper.
 	<varname>PKGSRC_COMPILER</varname> is <emphasis>not</emphasis> a
 	path to a compiler, but the type of compiler that should be
 	used. See <filename>mk/compiler.mk</filename> for more
 	information about the latter variable.</para></answer>
 </qandaentry>
 <qandaentry id="devfaq.bl3flags">
-	<question><para>What is the difference between
+	<question id="devfaq.bl3flags.q"><para>What is the difference between
 	<varname>BUILDLINK_LDFLAGS</varname>,
 	<varname>BUILDLINK_LDADD</varname> and
 	<varname>BUILDLINK_LIBS</varname>?</para></question>
 	<answer><para>[FIXME]</para></answer>
 </qandaentry>
 <qandaentry id="devfaq.bl3prefix">
-	<question><para>Why does <command>make show-var
+	<question id="devfaq.bl3prefix.q"><para>Why does <command>make show-var
 	VARNAME=BUILDLINK_PREFIX.<replaceable>foo</replaceable></command>
 	say it's empty?</para></question>
 	<answer><para>For optimization reasons, some variables are only
 	available in the <quote>wrapper</quote> phase and later. To
 	<quote>simulate</quote> the wrapper phase, append
 	<command>PKG_PHASE=wrapper</command> to the above
 	command.</para></answer>
 </qandaentry>
 <qandaentry id="devfaq.master_sites">
-	<question><para>What does
+	<question id="devfaq.master_sites.q"><para>What does
 	<code>${MASTER_SITE_SOURCEFORGE:=package/}</code> mean? I
 	don't understand the <code>:=</code> inside
 	it.</para></question>
 	<answer><para>The <code>:=</code> is not really an
 	assignment operator, although it looks like it.
 	Instead, it is a degenerate form of
 	<code>${LIST:<replaceable>old_string</replaceable>=<replaceable>new_string</replaceable>}</code>,
 	which is documented in the &man.make.1; man page and which is
 	commonly used in the form <code>${SRCS:.c=.o}</code>. In the
 	case of <varname>MASTER_SITE_*</varname>,
 	<replaceable>old_string</replaceable> is the empty string and
 	<replaceable>new_string</replaceable> is
 	<code>package/</code>. That's where the
 	<code>:</code> and the <code>=</code> fall
 	together.</para></answer>
 </qandaentry>
 <qandaentry id="devfaq.mailinglists">
-	<question><para>Which mailing lists are there for package
+	<question id="devfaq.mailinglists.q"><para>Which mailing lists are there for package
 	developers?</para></question>
 	<answer><variablelist>
 	<varlistentry><term><ulink
 	url="http://www.NetBSD.org/mailinglists/index.html#tech-pkg">tech-pkg</ulink></term>
 	<listitem><para>This is a list for technical discussions related
 	to pkgsrc development, e.g. soliciting feedback for changes to
 	pkgsrc infrastructure, proposed new features, questions related
 	to porting pkgsrc to a new platform, advice for maintaining a
 	package, patches that affect many packages, help requests moved
 	from pkgsrc-users when an infrastructure bug is found,
 @@ -118,27 +118,27 @@
 	<varlistentry><term><ulink
 	url="http://www.NetBSD.org/mailinglists/index.html#pkgsrc-bugs">pkgsrc-bugs</ulink></term>
 	<listitem><para>All bug reports in category "pkg" sent with
 	&man.send-pr.1; appear here. Please do not report your bugs here
 	directly; use one of the other mailing
 	lists.</para></listitem></varlistentry>
 	</variablelist></answer>
 </qandaentry>
 <qandaentry id="devfaq.documentation">
-	<question><para>Where is the pkgsrc
+	<question id="devfaq.documentation.q"><para>Where is the pkgsrc
 	documentation?</para></question>
 	<answer><para>There are many places where you can find
 	documentation about pkgsrc:</para>
 	<itemizedlist>
 	<listitem><para>The pkgsrc guide (this document) is a collection
 	of chapters that explain large parts of pkgsrc, but some
 	chapters tend to be outdated. Which ones they are is hard to
 	say.</para></listitem>
 	<listitem><para>On the mailing list archives (see <ulink
 @@ -171,28 +171,28 @@
 	to see who has written it and ask on the
 	<literal>tech-pkg</literal> mailing list, so that others can
 	find your questions later (see above). To be sure that the
 	developer in charge reads the mail, you may CC him or
 	her.</para></listitem>
 	</itemizedlist>
 	</answer>
 </qandaentry>
 <qandaentry id="devfaq.too-much-time">
-<question><para>I have a little time to kill.  What shall I
+<question id="devfaq.too-much-time.q"><para>I have a little time to kill.
-do?</para></question>
+What shall I do?</para></question>
 <answer><para>This is not really an FAQ yet, but here's the answer
 anyway.</para>
   <itemizedlist>
     <listitem><para>Run <command>pkg_chk -N</command> (from the
     <filename role="pkg">pkgtools/pkg_chk</filename> package).  It
     will tell you about newer versions of installed packages that are
     available, but not yet updated in pkgsrc.</para></listitem>
     <listitem><para>Browse <filename>pkgsrc/doc/TODO</filename>
     &mdash; it contains a list of suggested new packages and a list of
     cleanups and enhancements for pkgsrc that would be nice to