os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Rework of categories explanations: remove confusing colloquialism,

Browse source 
add text to ensure that the first category must be a physical category,
move comments about 'misc' out of the main table and into the commentary
below, finish removing information about COMMENT being a file.

Spurred in part by:	Mike Brown <mike at skew dot org>
This commit is contained in:
Mark Linimon 2004-07-01 05:08:39 +00:00
parent 0c1016c4ad
commit 15a021e144
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=21323
1 changed files with 26 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

@ -1273,15 +1273,15 @@ PORTEPOCH= 1</programlisting>
subdirectories are specified by the variable
<makevar>CATEGORIES</makevar>. It is intended to make life easier
for the user when he is wading through the pile of packages on the
FTP site or the CDROM. Please take a look at the existing <link
linkend="porting-categories">categories</link> and pick the ones
FTP site or the CDROM. Please take a look at the <link
linkend="porting-categories">current list of categories</link> and pick the ones
that are suitable for your port.</para>
<para>This list also determines where in the ports tree the port is
imported. If you put more than one category here, it is assumed
that the port files will be put in the subdirectory with the name in
the first category. See the <link
linkend="porting-categories">categories</link> section for more
the first category. See <link
linkend="choosing-categories">below</link> for more
discussion about how to pick the right categories.</para>
<para>If your port truly belongs to something that is different from
@ -1313,9 +1313,8 @@ PORTEPOCH= 1</programlisting>
<note>
<para>For non-virtual categories, you will find a one-line
description in the <filename>pkg/COMMENT</filename> file in that
subdirectory (e.g.,
<filename>archivers/pkg/COMMENT</filename>).</para>
description in the <makevar>COMMENT</makevar> in that
subdirectory's <filename>Makefile</filename>.</para>
</note>
<informaltable frame="none">
@ -1596,12 +1595,8 @@ PORTEPOCH= 1</programlisting>
<entry><filename>misc</filename></entry>
<entry>Miscellaneous utilities</entry>
<entry>Basically things that
do not belong anywhere else. This is the only category
that should not appear with any other non-virtual category.
If you have <literal>misc</literal> with something else in
your <makevar>CATEGORIES</makevar> line, that means you can
safely delete <literal>misc</literal> and just put the port
in that other subdirectory! If at all possible, try to
do not belong anywhere else.
If at all possible, try to
find a better category for your port than
<literal>misc</literal>, as ports tend to get overlooked
in here.</entry>
@ -1895,7 +1890,7 @@ PORTEPOCH= 1</programlisting>
</informaltable>
</sect2>
<sect2>
<sect2 id="choosing-categories">
<title>Choosing the right category</title>
<para>As many of the categories overlap, you often have to choose
@ -1904,6 +1899,13 @@ PORTEPOCH= 1</programlisting>
priorities, in decreasing order of precedence:</para>
<itemizedlist>
<listitem>
<para>The first category must be a physical category (see
<link linkend="porting-categories">above</link>). This is
necessary to make the packaging work. Virtual categories and
physical categories may be intermixed after that.
</listitem>
<listitem>
<para>Language specific categories always come first. For
example, if your port installs Japanese X11 fonts, then your
@ -1912,7 +1914,7 @@ PORTEPOCH= 1</programlisting>
</listitem>
<listitem>
<para>Specific categories win over less-specific ones. For
<para>Specific categories are listed before less-specific ones. For
instance, an HTML editor should be listed as <filename>www
editors</filename>, not the other way around. Also, you should not
list <filename>net</filename> when the port belongs to
@ -1940,6 +1942,15 @@ PORTEPOCH= 1</programlisting>
</para>
</listitem>
<listitem>
<para><filename>misc</filename>
should not appear with any other non-virtual category.
If you have <literal>misc</literal> with something else in
your <makevar>CATEGORIES</makevar> line, that means you can
safely delete <literal>misc</literal> and just put the port
in that other subdirectory!</para>
</listitem>
<listitem>
<para>If your port truly does not belong anywhere else, put it in
<filename>misc</filename>.</para>