Hi, Here's a patch to a couple of missing cross-references to specialtopics.html. While at it, rephrase one sentence and fix a typo (an -> a).
Index: specialtopics.html =================================================================== RCS file: /cvs/www/faq/ports/specialtopics.html,v retrieving revision 1.60 diff -u -p -r1.60 specialtopics.html --- specialtopics.html 12 Apr 2017 20:24:17 -0000 1.60 +++ specialtopics.html 13 Apr 2017 18:00:33 -0000 @@ -48,8 +48,11 @@ You must understand the library naming s <p> When you link a program, the linker ld embeds that information in the created binary. -You can see it with ldd. Later, when you run that program, the dynamic linker -ld.so uses that information to find the right dynamic library: +You can see it with +<a href="http://man.openbsd.org/ldd";>ldd(1)</a>. +Later, when you run that program, the dynamic linker +<a href="http://man.openbsd.org/ld.so";>ld.so(1)</a> uses that information to +find the right dynamic library: <ul><li> A library with the same exact major number is required. @@ -144,11 +147,13 @@ which can be directly included in the po <h3>Avoid DT_SONAME hardcoding</h3> -Some ports use ld(1)'s <tt>-soname</tt> flag to override the library +Some ports use the <tt>-soname</tt> flag with +<a href="http://man.openbsd.org/ld";>ld(1)</a> to override the library specification in the DT_SONAME field. Setting DT_SONAME is not a bug itself but is usually not desirable on -OpenBSD where ld.so(1) is smart and the ports tree takes care of library -versioning. +OpenBSD where +<a href="http://man.openbsd.org/ld.so";>ld.so(1)</a> is smart and the ports tree +takes care of library versioning. Moreover, a wrong soname can result in unusable binaries that depend on this library; either always or after some updates to the port containing the library. To check if the DT_SONAME field is set, run the following command: @@ -174,12 +179,15 @@ However, it is quite possible to use a s You should understand the library lookup rules: <ul><li> -At build time, ld uses <tt>-L</tt> flags to set up paths to look for libraries. +At build time, +<a href="http://man.openbsd.org/ld";>ld(1)</a> uses <tt>-L</tt> flags to set up +paths to look for libraries. It stops looking as soon as it finds a library that matches its requirements. <li> -At run time, ld.so uses the information cached through ldconfig to find the -required library. +At run time, +<a href="http://man.openbsd.org/ld.so";>ld.so(1)</a> uses the information cached +through ldconfig to find the required library. </ul> So, let us assume you have two ports that provide two major versions of a @@ -202,7 +210,8 @@ $ <b>ld -o program program.o -L/usr/loca To solve those libraries at run-time, a link called <tt>/usr/local/lib/libqt.so.1.45</tt> and a link called <tt>/usr/local/lib/libqt.so.2.31</tt> have been provided. -This is enough to satisfy ld.so. +This is enough to satisfy +<a href="http://man.openbsd.org/ld.so";>ld.so(1)</a>. <p> It is an error to link a program using <tt>qt1</tt> with @@ -375,7 +384,8 @@ These often get in the way of OpenBSD sp For that reason, as soon as <tt>CONFIGURE_STYLE</tt> corresponds to autoconf use, <tt>post-patch</tt> will touch various files in a specific order, so that no automake dependencies get triggered later. -The list of dependencies is given in tsort(1) order in a file mentioned in +The list of dependencies is given in +<a href="http://man.openbsd.org/tsort";>tsort(1)</a> order in a file mentioned in <tt>REORDER_DEPENDENCIES</tt> (the default is <tt>${PORTSDIR}/infrastructure/mk/automake.dep</tt>). @@ -473,7 +483,8 @@ the distributed configure script (usuall and use this same version yourself. <p> -Autoconf relies on the standard unix preprocessor m4(1). +Autoconf relies on the standard unix preprocessor +<a href="http://man.openbsd.org/m4";>m4(1)</a>. Normally, autoconf relies on some features on the GNU version of m4, gm4. Fortunately, OpenBSD's m4 has enough features to run autoconf as well, it just needs to be invoked with <tt>-g</tt> to handle autoconf. @@ -795,8 +806,10 @@ In normal usage, you just ask for an enc (e.g., <tt>AUDIO_ENCODING_SLINEAR_LE</tt>). Considering that a soundcard does not have to use the same endianness as your platform, you should be prepared to deal with that. -The easiest way is probably to prepare a full audio buffer, and to use swab(3) -if an endianness change is required. +The easiest way is probably to prepare a full audio buffer, +and to use +<a href="http://man.openbsd.org/swab";>swab(3)</a> if an endianness change is +required. Dealing with external samples usually amounts to: <ol> @@ -1255,17 +1268,19 @@ In case of doubt, report the issue and a <h2 id="RcScripts">rc.d(8) scripts</h2> This section is intended to provide some information on writing and installing -<i>rc.d(8) scripts</i>. +<a href="http://man.openbsd.org/rc.d";>rc.d(8)</a> scripts. <p> -Ports that install a daemon benefit greatly from having rc.d(8) scripts. +Ports that install a daemon benefit greatly from having +<a href="http://man.openbsd.org/rc.d";>rc.d(8)</a> scripts. It allows the user to easily check if the daemon is running, as well as providing an easy and consistent way to start and stop it. <h3>Writing rc.d(8) scripts</h3> -Writing an rc.d(8) script is straightforward and simple due to the clean -and simple design of the +Writing a +<a href="http://man.openbsd.org/rc.d";>rc.d(8)</a> script is straightforward and +simple due to the clean and simple design of the <a href="http://man.openbsd.org/rc.subr";>rc.subr(8)</a> system. Though there are several things to take into account.
