Date: Fri, 4 Apr 2014 01:25:03 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44434 - head/en_US.ISO8859-1/books/porters-handbook/makefiles Message-ID: <201404040125.s341P3SN002444@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Fri Apr 4 01:25:03 2014 New Revision: 44434 URL: http://svnweb.freebsd.org/changeset/doc/44434 Log: Recover lost <replaceable> tags. Make descriptions of the components of package names easier to read. Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Thu Apr 3 23:20:15 2014 (r44433) +++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Fri Apr 4 01:25:03 2014 (r44434) @@ -335,25 +335,27 @@ PORTEPOCH= 1</programlisting> <sect2 xml:id="porting-pkgname"> <title>Package Naming Conventions</title> - <para>The following are the conventions you should follow in - naming your packages. This is to have our package directory + <para>These are the conventions to follow when + naming packages. This is to make the package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes!</para> - <para>The package name should look like - <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para> + <para>Package names take the form of + <filename><replaceable>language_region-name-compiled.specifics-version.numbers</replaceable></filename>.</para> <para>The package name is defined as <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. Make sure to set the variables to conform to that format.</para> - <orderedlist> + <variablelist xml:id="porting-pkgname-format"> + <varlistentry xml:id="porting-pkgname-language"> + <term><filename><replaceable>language_region-</replaceable></filename></term> <listitem> <para>&os; strives to support the native language of its users. The <replaceable>language-</replaceable> part - should be a two letter abbreviation of the natural - language defined by ISO-639 if the port is specific to a + is a two letter abbreviation of the natural + language defined by ISO-639 when the port is specific to a certain language. Examples are <literal>ja</literal> for Japanese, <literal>ru</literal> for Russian, <literal>vi</literal> for Vietnamese, @@ -365,25 +367,25 @@ PORTEPOCH= 1</programlisting> Examples are <literal>en_US</literal> for US English and <literal>fr_CH</literal> for Swiss French.</para> - <para>The <replaceable>language-</replaceable> part should - be set in the <varname>PKGNAMEPREFIX</varname> + <para>The <replaceable>language-</replaceable> part is + set in the <varname>PKGNAMEPREFIX</varname> variable.</para> </listitem> + </varlistentry> + <varlistentry xml:id="porting-pkgname-name"> + <term><filename><replaceable>name</replaceable></filename></term> <listitem> <para>The first letter of the <filename>name</filename> part should be lowercase. (The rest of the name may contain - capital letters, so use your own discretion when you are + capital letters, so use your own discretion when converting a software name that has some capital letters in it.) There is a tradition of naming <literal>Perl 5</literal> modules by prepending <literal>p5-</literal> and converting the double-colon - separator to a hyphen; for example, the + separator to a hyphen. For example, the <literal>Data::Dumper</literal> module becomes <literal>p5-Data-Dumper</literal>.</para> - </listitem> - - <listitem> <para>Make sure that the port's name and version are clearly separated and placed into the <varname>PORTNAME</varname> and <varname>PORTVERSION</varname> variables. The only @@ -401,7 +403,10 @@ PORTEPOCH= 1</programlisting> distinguished by the <varname>PKGNAMEPREFIX</varname> and <varname>PKGNAMESUFFIX</varname> values.</para> </listitem> + </varlistentry> + <varlistentry xml:id="porting-pkgname-compiled-specifics"> + <term><filename><replaceable>-compiled.specifics</replaceable></filename></term> <listitem> <para>If the port can be built with different <link linkend="makefile-masterdir">hardcoded @@ -412,13 +417,16 @@ PORTEPOCH= 1</programlisting> Examples are paper size and font units.</para> <para>The <replaceable>-compiled.specifics</replaceable> - part should be set in the <varname>PKGNAMESUFFIX</varname> + part is set in the <varname>PKGNAMESUFFIX</varname> variable.</para> </listitem> + </varlistentry> + <varlistentry xml:id="porting-pkgname-version-numbers"> + <term><filename><replaceable>-version.numbers</replaceable></filename></term> <listitem> - <para>The version string should follow a dash - (<literal>-</literal>) and be a period-separated list of + <para>The version string follows a dash + (<literal>-</literal>) and is a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string @@ -437,18 +445,19 @@ PORTEPOCH= 1</programlisting> at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the - <literal>0.0.yyyy.mm.dd</literal> format, not - <literal>dd.mm.yyyy</literal> or the non-Y2K compliant - <literal>yy.mm.dd</literal> format. It is important to + <literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> format, not + <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal> or the non-Y2K compliant + <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> format. It is important to prefix the version with <literal>0.0.</literal> in case a release with an actual version number is made, which would of course be numerically less than - <literal>yyyy</literal>.</para> + <literal><replaceable>yyyy</replaceable></literal>.</para> </listitem> - </orderedlist> + </varlistentry> + </variablelist> <warning> - <para>Package name should be unique among all of the ports + <para>Package name must be unique among all of the ports tree, check that there is not already a port with the same <varname>PORTNAME</varname> and if there is add one of <link linkend="porting-pkgnameprefix-suffix"><varname>PKGNAMEPREFIX</varname> @@ -595,7 +604,7 @@ PORTEPOCH= 1</programlisting> string to <literal>1.0</literal> (like the <literal>piewm</literal> example above). Otherwise, ask the original author or use the date string - (<literal>0.0.yyyy.mm.dd</literal>) as the version.</para> + (<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) as the version.</para> </sect2> </sect1> @@ -1983,7 +1992,7 @@ DISTFILES= source1.tar.gz:source1 \ <orderedlist> <listitem> - <para>Elements can be postfixed with <literal>:n</literal> + <para>Elements can be postfixed with <literal>:<replaceable>n</replaceable></literal> where <replaceable>n</replaceable> is <literal>[^:,]+</literal>, i.e., <replaceable>n</replaceable> could conceptually be any @@ -2090,7 +2099,7 @@ DISTFILES= source1.tar.gz:source1 \ be terminated with the forward slash <literal>/</literal> character. If any elements belong to any groups, the group postfix - <literal>:n</literal> must come right after the + <literal>:<replaceable>n</replaceable></literal> must come right after the terminator <literal>/</literal>. The <literal>MASTER_SITES:n</literal> mechanism relies on the existence of the terminator @@ -2383,7 +2392,7 @@ PATCHFILES= patch1:test</programlisting> <para>All current ports remain the same. The <literal>MASTER_SITES:n</literal> feature code is only activated if there are elements postfixed with - <literal>:n</literal> like elements according to the + <literal>:<replaceable>n</replaceable></literal> like elements according to the aforementioned syntax rules, especially as shown in item <xref linkend="porting-master-sites-n-group-semantics"/>.</para> @@ -2750,7 +2759,7 @@ ALWAYS_KEEP_DISTFILES= yes <para>This variable specifies executables or files this port depends on during run-time. It is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional> tuples where <replaceable>path</replaceable> is the name of the executable or file, <replaceable>dir</replaceable> is the directory in which to find it in case it is not available, and @@ -2832,7 +2841,7 @@ ALWAYS_KEEP_DISTFILES= yes <para>This variable specifies executables or files this port requires to build. Like <varname>RUN_DEPENDS</varname>, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional> tuples. For example,</para> <programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> @@ -2856,7 +2865,7 @@ ALWAYS_KEEP_DISTFILES= yes <para>This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional> tuples. For example,</para> <programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting> @@ -2877,7 +2886,7 @@ ALWAYS_KEEP_DISTFILES= yes <para>This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional> tuples. For example,</para> <programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> @@ -2907,7 +2916,7 @@ ALWAYS_KEEP_DISTFILES= yes <para>This variable specifies executables or files this port requires to patch. Like the previous, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:<replaceable>target</replaceable></optional> tuples. For example,</para> <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting> @@ -4248,8 +4257,8 @@ PORTVERSION= 1.0</programlisting> files in the port's <buildtarget>*-install</buildtarget> targets. Set ownership directly in <filename>pkg-plist</filename> with the corresponding entries, - such as <literal>@owner owner</literal> and - <literal>@group group</literal>. These operators work until + such as <literal>@owner <replaceable>owner</replaceable></literal> and + <literal>@group <replaceable>group</replaceable></literal>. These operators work until being overridden, or until the end of <filename>pkg-plist</filename>, so do not forget to reset them after they are no longer needed. The default ownership is
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404040125.s341P3SN002444>