While working on a port recently, I was unable to find documentation on
creating a pkg-readme. I'm not sure if it's not there, or I just didn't
look hard enough. In any case, here's a proposed change to
www/faq/ports/specialtopics.html to add some information about
pkg-readmes. If this is something that's better left undocumented to
prevent exponential growth of readme files for frivolous reasons... well,
then feel free to ignore this patch. I'm happy to add more information to
relevant man pages as well, but not sure where it would make sense.
gabe.
Index: specialtopics.html
===================================================================
RCS file: /var/cvs/www/faq/ports/specialtopics.html,v
retrieving revision 1.29
diff -u -p -u -r1.29 specialtopics.html
--- specialtopics.html 10 Oct 2012 08:50:07 -0000 1.29
+++ specialtopics.html 18 Oct 2013 02:04:58 -0000
@@ -51,6 +51,7 @@ PERFORMANCE OF THIS DOCUMENTATION
<li><a href="#Audio" >3.4 - Audio Applications</a>
<li><a href="#Mandoc" >3.5 - Manual pages</a>
<li><a href="#RcScripts" >3.6 - rc.d(8) scripts</a>
+ <li><a href="#PkgReadmes" >3.7 - Package Readmes</a>
</ul>
<hr>
@@ -1217,6 +1218,30 @@ A
script</a> can also be found in the templates directory of your ports tree.
+<p>
+
+<a name="PkgReadmes"></a>
+<h2>3.7 - Package Readmes</h2>
+This section provides details on installing a package readme.
+
+<h3>Does my package need a readme?</h3>
+A package may require special instructions to run on OpenBSD, or
+additional files may need to be downloaded before the port will work
+properly, or your port may rely on additional packages to support
+additional functionality. If this is the case, and you are unable to
+provide those features via flavors, a readme may be warranted.
+
+<h3>Creating and installing a readme</h3>
+You can create a README file in the pkg directory of your port with
+the relevant information. Once your file is complete, add
+<blockquote><pre>
+@cwd ${LOCALBASE}/share/doc/pkg-readmes
+${FULLPKGNAME}
+</pre></blockquote>
+to your generated PLIST file. This will allow the pkg tools to copy
+your README to /usr/local/share/doc/pkg-readmes/ when your port is
+installed, and notify the user to check there for additional
+information.
<p>
<font color= "#0000e0">
