RFC: some patches to the Porter's Handbook
Mark Linimon
linimon at lonesome.com
Wed Jun 1 05:04:14 UTC 2011
When going through the "Using" sections, I always get irritated by
having to figure out where the makevars that they are talking about
are defined. This patch adds some crossrefs to the CVSWeb pages
for them. (In a few cases, the filenames were mentioned, but they
weren't CVSWeb references.)
Does anyone have any objection to the following?
mcl
Index: book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.1106
diff -u -r1.1106 book.sgml
--- book.sgml 1 Jun 2011 04:15:04 -0000 1.1106
+++ book.sgml 1 Jun 2011 04:58:40 -0000
@@ -68,7 +68,11 @@
<para>When this document is not sufficiently detailed, you should
refer to <filename>/usr/ports/Mk/bsd.port.mk</filename>, which
- all port Makefiles include. Even if you do not hack Makefiles
+ all port Makefiles include.
+ (For reference, you can view the
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk">
+ current contents of bsd.port.mk</ulink> on the web.)
+ Even if you do not hack Makefiles
daily, it is well commented, and you will still gain much
knowledge from it. Additionally, you may send specific questions
to the &a.ports;.</para>
@@ -441,7 +445,9 @@
<para>First, this is the sequence of events which occurs when the user
first types <command>make</command> in your port's directory.
- You may find that having <filename>bsd.port.mk</filename> in another
+ You may find that having
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk">bsd.port.mk</ulink>
+ in another
window while you read this really helps to understand it.</para>
<para>But do not worry if you do not really understand what
@@ -3545,7 +3551,7 @@
</note>
<table frame="none">
- <title>The <makevar>USE_<replaceable>*</replaceable></makevar>
+ <title>Common <makevar>USE_<replaceable>*</replaceable></makevar>
variables</title>
<tgroup cols="2">
@@ -4019,6 +4025,10 @@
<para>Use <command>make showconfig</command> to see the saved
configuration. Use <command>make rmconfig</command> to remove the
saved configuration.</para>
+
+ <para>For the complete details of how <makevar>OPTIONS</makevar> work, see
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.options.mk">
+ bsd.options.mk</ulink>.</para>
</sect3>
<sect3>
@@ -4888,6 +4898,10 @@
</tgroup>
</table>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.scons.mk">
+ bsd.scons.mk</ulink>.
+
<para>To make third party <filename>SConstruct</filename> respect
everything that is passed to SCons in <makevar>SCONS_ENV</makevar>
(that is, most importantly,
@@ -4940,6 +4954,10 @@
for cross-development work. This can also be accomplished
by installing the <literal>devel/autotools</literal> port.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.autotools.mk">
+ bsd.autotools.mk</ulink>.
+
</sect2>
<sect2 id="using-libtool">
@@ -5349,8 +5367,9 @@
xprintutil xpr oto xproxymngproto xrandr xrender xres xscrnsaver xt
xtrans xtrap xtst xv xvmc xxf86dga xxf86misc xxf86vm</literal>.</para>
- <para>Always up-to-date list can be found in
- <filename>/usr/ports/Mk/bsd.xorg.mk</filename>.</para>
+ <para>The most up-to-date list can be found in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.xorg.mk">
+ bsd.xorg.mk</ulink>.
<para>The Mesa Project is an effort to provide free OpenGL
implementation. You can specify a dependency on various components
@@ -5632,6 +5651,10 @@
list of these variables</ulink> exists within the FreeBSD/GNOME
project's homepage.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.gnome.mk">
+ bsd.gnome.mk</ulink>.
+
</sect1>
<sect1 id="using-qt">
@@ -5758,6 +5781,10 @@
<programlisting>CONFIGURE_ENV+= UIC="${UIC}" QMAKE="${QMAKE}" QMAKESPEC="${QMAKESPEC}"
MAKE_ENV+= QMAKESPEC="${QMAKESPEC}"</programlisting>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.qt.mk">
+ bsd.qt.mk</ulink>.
+
</sect2>
<sect2 id="qt4-components">
@@ -5987,6 +6014,10 @@
<sect1 id="using-kde">
<title>Using KDE</title>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.kde.mk">
+ bsd.kde.mk</ulink>.
+
<sect2 id="kde-variables">
<title>Variable definitions (KDE 3.x only)</title>
@@ -6422,6 +6453,10 @@
<xref linkend="plist-sub">) and
<makevar>SUB_LIST</makevar>.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.java.mk">
+ bsd.java.mk</ulink>.
+
</sect2>
<sect2 id="java-building-with-ant">
@@ -6444,7 +6479,7 @@
</sect2>
<sect2 id="java-best-practices">
- <title>Best practices</title>
+ <title>Best practices for Java ports</title>
<para>When porting a Java library, your port should install the
JAR file(s) in <filename>${JAVAJARDIR}</filename>, and everything
@@ -6664,6 +6699,11 @@
</tbody>
</tgroup>
</table>
+
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.apache.mk">
+ bsd.apache.mk</ulink>.
+
</sect2>
<sect2 id="web-apps">
@@ -6775,8 +6815,13 @@
</row>
</tbody>
</tgroup>
+
</table>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.php.mk">
+ bsd.php.mk</ulink>.
+
</sect2>
<sect2>
@@ -6825,6 +6870,10 @@
</example>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.pear.mk">
+ bsd.pear.mk</ulink>.
+
</sect2>
</sect1>
@@ -6949,8 +6998,9 @@
</tgroup>
</table>
- <para>A complete list of available variables can be found in
- <filename>/usr/ports/Mk/bsd.python.mk</filename>.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.python.mk">
+ bsd.python.mk</ulink>.
</sect1>
@@ -7057,14 +7107,21 @@
</tgroup>
</table>
- <para>A complete list of available variables can be found in
- <filename>/usr/ports/Mk/bsd.tcl.mk</filename>.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.tcl.mk">
+ bsd.tcl.mk</ulink>.
+
</sect1>
<sect1 id="using-emacs">
<title>Using Emacs</title>
<para>This section is yet to be written.</para>
+
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.emacs.mk">
+ bsd.emacs.mk</ulink>.
+
</sect1>
<sect1 id="using-ruby">
@@ -7188,8 +7245,9 @@
</tgroup>
</table>
- <para>A complete list of available variables can be found in
- <filename>/usr/ports/Mk/bsd.ruby.mk</filename>.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.ruby.mk">
+ bsd.ruby.mk</ulink>.
</sect1>
@@ -7289,6 +7347,10 @@
.include <bsd.port.post.mk></programlisting>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.sdl.mk">
+ bsd.sdl.mk</ulink>.
+
</sect1>
<sect1 id="using-wx">
@@ -7298,6 +7360,10 @@
<application>wxWidgets</application> libraries in the ports tree and
its integration with the ports system.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.wx.mk">
+ bsd.wx.mk</ulink>.
+
<sect2 id="wx-introduction">
<title>Introduction</title>
@@ -7924,6 +7990,10 @@
<application>Lua</application> libraries in the ports tree and its
integration with the ports system.</para>
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.lua.mk">
+ bsd.lua.mk</ulink>.
+
<sect2 id="lua-introduction">
<title>Introduction</title>
@@ -8554,6 +8624,11 @@
the syntax will be:</para>
<programlisting>USE_XFCE= mcsmanager configenv</programlisting>
+
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.xfce.mk">
+ bsd.xfce.mk</ulink>.
+
</sect1>
<sect1 id="using-mozilla">
@@ -8634,8 +8709,11 @@
</tbody>
</tgroup>
</table>
- <para>A complete list of available variables can be found in
- <filename>/usr/ports/Mk/bsd.gecko.mk</filename>.</para>
+
+ <para>More details are available in
+ <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.gecko.mk">
+ bsd.gecko.mk</ulink>.
+
</sect1>
More information about the freebsd-ports
mailing list