Date: Sun, 12 Jan 2014 20:30:37 +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: r43482 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201401122030.s0CKUbxB099083@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Jan 12 20:30:37 2014 New Revision: 43482 URL: http://svnweb.freebsd.org/changeset/doc/43482 Log: Whitespace-only cleanup, translators please ignore. Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Jan 12 20:13:18 2014 (r43481) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Sun Jan 12 20:30:37 2014 (r43482) @@ -168,9 +168,10 @@ COMMENT= Cat chasing a mouse all over th <para>See if you can figure it out. Do not worry about the contents of the <literal>$FreeBSD$</literal> - line, it will be filled in automatically by <application>Subversion</application> when the port - is imported to our main ports tree. You can find a more - detailed example in the + line, it will be filled in automatically by + <application>Subversion</application> when the port is + imported to our main ports tree. You can find a more detailed + example in the <link linkend="porting-samplem">sample Makefile</link> section.</para> </sect1> @@ -422,8 +423,8 @@ PLIST_DIRS= lib/X11/oneko</programlistin <para>Thorough automated testing can be done with <package role="port">ports-mgmt/tinderbox</package> or - <package role="port">ports-mgmt/poudriere</package> from the Ports - Collection. These applications maintain + <package role="port">ports-mgmt/poudriere</package> from the + Ports Collection. These applications maintain <literal>jails</literal> where all of the steps shown above can be tested without affecting the state of the host system.</para> @@ -451,14 +452,17 @@ PLIST_DIRS= lib/X11/oneko</programlistin the <link linkend="porting-dads">DOs and DON'Ts</link> section.</para> - <para>Once happy with your port, the only thing - remaining is to put it in the main &os; ports tree and make - everybody else happy about it too. We do not need the + <para>Once happy with your port, the only thing remaining is to + put it in the main &os; ports tree and make everybody else + happy about it too. We do not need the <filename>work</filename> directory or the - <filename>pkgname.tgz</filename> package, so delete them now.</para> - <para>Next, build the &man.shar.1; file. Assuming the port is called <literal>oneko</literal>, - <command>cd</command> to the directory above where the - <literal>oneko</literal> directory is located, and then type: + <filename>pkgname.tgz</filename> package, so delete them + now.</para> + + <para>Next, build the &man.shar.1; file. Assuming the port is + called <literal>oneko</literal>, <command>cd</command> to the + directory above where the <literal>oneko</literal> directory + is located, and then type: <command>shar `find oneko` > oneko.shar</command></para> <para>Include <filename>oneko.shar</filename> in a bug @@ -467,23 +471,24 @@ PLIST_DIRS= lib/X11/oneko</programlistin xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug Reports and General Commentary</link> for more information about &man.send-pr.1;.</para> - <para>Classify the bug report - as Category <literal>ports</literal> and Class - <literal>change-request</literal>. Do <emphasis>not</emphasis> mark the report - <literal>confidential</literal>! Add a short - description of the program to the - Description field of the PR (perhaps a - short version of the <varname>COMMENT</varname>), and add - the <filename>.shar</filename> file to the Fix field.</para> + + <para>Classify the bug report as Category + <literal>ports</literal> and Class + <literal>change-request</literal>. Do + <emphasis>not</emphasis> mark the report + <literal>confidential</literal>! Add a short description of + the program to the Description field of the PR (perhaps a + short version of the <varname>COMMENT</varname>), and add the + <filename>.shar</filename> file to the Fix field.</para> <note> - <para>Giving a good - description in the synopsis of the problem report makes the work of port committers a lot easier. We + <para>Giving a good description in the synopsis of the problem + report makes the work of port committers a lot easier. We prefer something like <quote>New port: <category>/<portname> <short description of the port></quote> for new ports. Using this - scheme makes it easier and faster to begin the work of committing - the new port.</para> + scheme makes it easier and faster to begin the work of + committing the new port.</para> </note> <para>One more time, <emphasis>do not include the original @@ -492,15 +497,15 @@ PLIST_DIRS= lib/X11/oneko</programlistin <command>make package</command></emphasis>; and, do use &man.shar.1; for new ports, not &man.diff.1;.</para> - <para>After submitting the port, please be patient. The time needed - to include a new port in &os; can vary from a few days to a - a few months. The list - of pending port <acronym>PR</acronym>s can be viewed at <link + <para>After submitting the port, please be patient. The time + needed to include a new port in &os; can vary from a few days + to a a few months. The list of pending port + <acronym>PR</acronym>s can be viewed at <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"></link>.</para>; - <para>After looking at the new port, we will reply - if necessary, and put it in the tree. Your name will also - be added to the list of <link + <para>After looking at the new port, we will reply if necessary, + and put it in the tree. Your name will also be added to the + list of <link xlink:href="&url.articles.contributors;/contrib-additional.html">Additional &os; Contributors</link> and other files.</para> </sect1> @@ -786,10 +791,11 @@ PLIST_DIRS= lib/X11/oneko</programlistin <filename>patch-ab</filename> etc, always mention the path and file name in patch names.</para> - <para>Do not put RCS strings in patches. <application>Subversion</application> will mangle them - when we put the files into the ports tree, and when we check - them out again, they will come out different and the patch - will fail. RCS strings are surrounded by dollar + <para>Do not put RCS strings in patches. + <application>Subversion</application> will mangle them when we + put the files into the ports tree, and when we check them out + again, they will come out different and the patch will fail. + RCS strings are surrounded by dollar (<literal>$</literal>) signs, and typically start with <literal>$Id</literal> or <literal>$RCS</literal>.</para> @@ -817,9 +823,10 @@ PLIST_DIRS= lib/X11/oneko</programlistin take a working piece of functionality from one project to fix similar areas in another, please be careful: the resulting line patch may be full of non-functional changes. It not only - increases the size of the <application>Subversion</application> repository but makes it hard to - find out what exactly caused the problem and what you changed - at all.</para> + increases the size of the + <application>Subversion</application> repository but makes it + hard to find out what exactly caused the problem and what you + changed at all.</para> <para>If you had to delete a file, then you can do it in the <buildtarget>post-extract</buildtarget> target rather than as @@ -4295,8 +4302,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <row> <entry><varname>WITH_OPENSSL_PORT</varname></entry> <entry>Installs the version of OpenSSL from - <package role="port">security/openssl</package>, even - if the base is up to date.</entry> + <package role="port">security/openssl</package>, + even if the base is up to date.</entry> </row> </tbody> </tgroup> @@ -5624,12 +5631,13 @@ IGNORE= may not be redistributed because <para>This is achieved by passing <varname>-jX</varname> flag to &man.make.1; running on vendor code. This is the default - build behavior of ports. Unfortunately, not all ports handle - parallel building well and it may be required to explicitly - disable this feature by adding the - <literal>MAKE_JOBS_UNSAFE=yes</literal> variable. It is used - when a port is known to be broken with + build behavior of ports. Unfortunately, not all ports + handle parallel building well and it may be required to + explicitly disable this feature by adding the + <literal>MAKE_JOBS_UNSAFE=yes</literal> variable. It is + used when a port is known to be broken with <varname>-jX</varname>.</para> + </sect2> <sect2 xml:id="using-make"> @@ -7575,10 +7583,11 @@ USE_QT4= moc_build qmake_build rcc_build If you ever think that your port needs more sophisticated Java support, please first have a look at the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk - <application>Subversion</application> log</link> as it usually takes some time to document - the latest features. Then, if you think the support you are - lacking would be beneficial to many other Java ports, feel - free to discuss it on the &a.java;.</para> + <application>Subversion</application> log</link> as it + usually takes some time to document the latest features. + Then, if you think the support you are lacking would be + beneficial to many other Java ports, feel free to discuss it + on the &a.java;.</para> <para>Although there is a <literal>java</literal> category for PRs, it refers to the JDK porting effort from the &os; Java @@ -8227,8 +8236,8 @@ _DOCSDIR= . <para>The <varname>USE_SDL</varname> variable is used to autoconfigure the dependencies for ports which use an SDL - based library like <package role="port">devel/sdl12</package> and - <package role="port">graphics/sdl_image</package>.</para> + based library like <package role="port">devel/sdl12</package> + and <package role="port">graphics/sdl_image</package>.</para> <para>The following SDL libraries for version 1.2 are recognized at the moment:</para> @@ -8239,19 +8248,23 @@ _DOCSDIR= . </listitem> <listitem> - <para>console: <package role="port">devel/sdl_console</package></para> + <para>console: <package + role="port">devel/sdl_console</package></para> </listitem> <listitem> - <para>gfx: <package role="port">graphics/sdl_gfx</package></para> + <para>gfx: <package + role="port">graphics/sdl_gfx</package></para> </listitem> <listitem> - <para>image: <package role="port">graphics/sdl_image</package></para> + <para>image: <package + role="port">graphics/sdl_image</package></para> </listitem> <listitem> - <para>mixer: <package role="port">audio/sdl_mixer</package></para> + <para>mixer: <package + role="port">audio/sdl_mixer</package></para> </listitem> <listitem> @@ -8263,16 +8276,18 @@ _DOCSDIR= . </listitem> <listitem> - <para>pango: - <package role="port">x11-toolkits/sdl_pango</package></para> + <para>pango: <package + role="port">x11-toolkits/sdl_pango</package></para> </listitem> <listitem> - <para>sound: <package role="port">audio/sdl_sound</package></para> + <para>sound: <package + role="port">audio/sdl_sound</package></para> </listitem> <listitem> - <para>ttf: <package role="port">graphics/sdl_ttf</package></para> + <para>ttf: <package + role="port">graphics/sdl_ttf</package></para> </listitem> </itemizedlist> @@ -8285,23 +8300,28 @@ _DOCSDIR= . </listitem> <listitem> - <para>gfx: <package role="port">graphics/sdl2_gfx</package></para> + <para>gfx: <package + role="port">graphics/sdl2_gfx</package></para> </listitem> <listitem> - <para>image: <package role="port">graphics/sdl2_image</package></para> + <para>image: <package + role="port">graphics/sdl2_image</package></para> </listitem> <listitem> - <para>mixer: <package role="port">audio/sdl2_mixer</package></para> + <para>mixer: <package + role="port">audio/sdl2_mixer</package></para> </listitem> <listitem> - <para>net: <package role="port">net/sdl2_net</package></para> + <para>net: <package + role="port">net/sdl2_net</package></para> </listitem> <listitem> - <para>ttf: <package role="port">graphics/sdl2_ttf</package></para> + <para>ttf: <package + role="port">graphics/sdl2_ttf</package></para> </listitem> </itemizedlist> @@ -8459,17 +8479,20 @@ USE_SDL+= mixer <tbody> <row> <entry><literal>2.4</literal></entry> - <entry><package role="port">x11-toolkits/wxgtk24</package></entry> + <entry><package + role="port">x11-toolkits/wxgtk24</package></entry> </row> <row> <entry><literal>2.6</literal></entry> - <entry><package role="port">x11-toolkits/wxgtk26</package></entry> + <entry><package + role="port">x11-toolkits/wxgtk26</package></entry> </row> <row> <entry><literal>2.8</literal></entry> - <entry><package role="port">x11-toolkits/wxgtk28</package></entry> + <entry><package + role="port">x11-toolkits/wxgtk28</package></entry> </row> </tbody> </tgroup> @@ -9037,12 +9060,14 @@ PLIST_SUB+= VERSION="${VER_STR}" <tbody> <row> <entry><literal>4.0</literal></entry> - <entry><package role="port">lang/lua4</package></entry> + <entry><package + role="port">lang/lua4</package></entry> </row> <row> <entry><literal>5.0</literal></entry> - <entry><package role="port">lang/lua50</package></entry> + <entry><package + role="port">lang/lua50</package></entry> </row> <row> @@ -9506,16 +9531,16 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR <para>After 2013-10-08 (<revnumber>254273</revnumber>), &os; 10-CURRENT and newer versions have a native <command>iconv</command> in the operating system. On earlier - versions, <package role="port">converters/libiconv</package> was used as a - dependency.</para> + versions, <package role="port">converters/libiconv</package> + was used as a dependency.</para> <para>For software that needs <command>iconv</command>, define <literal>USES=iconv</literal>. &os; versions before 10-CURRENT on 2013-08-13 (<revnumber>254273</revnumber>) do not have a native <command>iconv</command>. On these earlier versions, a dependency on - <package role="port">converters/libiconv</package> will be added - automatically.</para> + <package role="port">converters/libiconv</package> will be + added automatically.</para> <para>When a port defines <literal>USES=iconv</literal>, these variables will be available:</para> @@ -9655,41 +9680,48 @@ post-patch: <itemizedlist> <listitem> - <para>libexo: <package role="port">x11/libexo</package></para> + <para>libexo: <package + role="port">x11/libexo</package></para> </listitem> <listitem> - <para>libgui: - <package role="port">x11-toolkits/libxfce4gui</package></para> + <para>libgui: <package + role="port">x11-toolkits/libxfce4gui</package></para> </listitem> <listitem> - <para>libutil: <package role="port">x11/libxfce4util</package></para> + <para>libutil: <package + role="port">x11/libxfce4util</package></para> </listitem> <listitem> - <para>libmcs: <package role="port">x11/libxfce4mcs</package></para> + <para>libmcs: <package + role="port">x11/libxfce4mcs</package></para> </listitem> <listitem> - <para>mcsmanager: - <package role="port">sysutils/xfce4-mcs-manager</package></para> + <para>mcsmanager: <package + role="port">sysutils/xfce4-mcs-manager</package></para> </listitem> <listitem> - <para>panel: <package role="port">x11-wm/xfce4-panel</package></para> + <para>panel: <package + role="port">x11-wm/xfce4-panel</package></para> </listitem> <listitem> - <para>thunar: <package role="port">x11-fm/thunar</package></para> + <para>thunar: <package + role="port">x11-fm/thunar</package></para> </listitem> <listitem> - <para>wm: <package role="port">x11-wm/xfce4-wm</package></para> + <para>wm: <package + role="port">x11-wm/xfce4-wm</package></para> </listitem> <listitem> - <para>xfdev: <package role="port">dev/xfce4-dev-tools</package></para> + <para>xfdev: <package + role="port">dev/xfce4-dev-tools</package></para> </listitem> </itemizedlist> @@ -9826,10 +9858,10 @@ post-patch: <row> <entry><varname>USE_MYSQL</varname></entry> - <entry>If the variable is set to <literal>yes</literal>, add - a dependency on the - <package role="port">databases/mysql55-client</package> port. An - associated variable, + <entry>If the variable is set to <literal>yes</literal>, + add a dependency on the <package + role="port">databases/mysql55-client</package> port. + An associated variable, <varname>WANT_MYSQL_VER</varname>, may be set to values such as 323, 40, 41, 50, 51, 52, 55, or 60.</entry> @@ -9838,14 +9870,15 @@ post-patch: <row> <entry><varname>USE_PGSQL</varname></entry> <entry>If set to <literal>yes</literal>, add dependency - on <package role="port">databases/postgresql90-client</package> + on <package + role="port">databases/postgresql90-client</package> port. An associated variable, <varname>WANT_PGSQL_VER</varname>, may be set to values such as 83, 84, 90, 91 or 92. You can declare a minimum or maximum value; - <varname>WANT_PGSQL_VER</varname>= - <literal> 90+</literal> will cause the - port to depend on a minimum version of 9.0.</entry> + <varname>WANT_PGSQL_VER</varname>= <literal> + 90+</literal> will cause the port to depend on a + minimum version of 9.0.</entry> </row> <row> @@ -10967,7 +11000,8 @@ as .putsy.conf and edit it.</programlist how to keep up-to-date in <xref linkend="keeping-up"/>.</para> <sect1 xml:id="svn-diff"> - <title>Using <application>Subversion</application> to Make Patches</title> + <title>Using <application>Subversion</application> to Make + Patches</title> <para>When possible, please submit a &man.svn.1; diff. They are easier to handle than diffs between @@ -10992,9 +11026,9 @@ as .putsy.conf and edit it.</programlist <callout arearefs="svn-FreeBSD-org"> <para><link xlink:href="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</link>; - is a public <application>Subversion</application> server. Select the - closest mirror and verify the mirror server certificate - from the list of <link + is a public <application>Subversion</application> server. + Select the closest mirror and verify the mirror server + certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion mirror sites</link>.</para> </callout> @@ -11017,15 +11051,16 @@ as .putsy.conf and edit it.</programlist <calloutlist> <callout arearefs="svn-update"> <para>This will try to merge the differences between your - patch and current repository version; watch the output carefully. The - letter in front of each file name indicates what was done - with it. See <xref linkend="table-svn-up"/> for a - complete list.</para> + patch and current repository version; watch the output + carefully. The letter in front of each file name + indicates what was done with it. See + <xref linkend="table-svn-up"/> for a complete list.</para> </callout> </calloutlist> <table pgwide="1" frame="none" xml:id="table-svn-up"> - <title><application>Subversion</application> Update File Prefixes</title> + <title><application>Subversion</application> Update File + Prefixes</title> <tgroup cols="2"> <tbody> @@ -11058,12 +11093,12 @@ as .putsy.conf and edit it.</programlist <para>If <literal>C</literal> is displayed as a result of <command>svn update</command>, it means something changed in - the <application>Subversion</application> repository and &man.svn.1; was not able to merge the - local changes with those from the repository. It is always a - good idea to inspect the changes anyway, since &man.svn.1; - does not know anything about how a port should be, so it might - (and probably will) merge things that do not make - sense.</para> + the <application>Subversion</application> repository and + &man.svn.1; was not able to merge the local changes with those + from the repository. It is always a good idea to inspect the + changes anyway, since &man.svn.1; does not know anything about + how a port should be, so it might (and probably will) merge + things that do not make sense.</para> <para>The last step is to make a unified &man.diff.1; of the changes:</para> @@ -11242,10 +11277,11 @@ as .putsy.conf and edit it.</programlist xlink:href="http://www.freebsd.org/security/#how">&os; Security Information</link> page.</para> - <para>The VuXML database is an <acronym>XML</acronym> document. Its source file - <filename>vuln.xml</filename> is kept right inside the port - <package role="port">security/vuxml</package>. Therefore the file's - full pathname will be + <para>The VuXML database is an <acronym>XML</acronym> + document. Its source file <filename>vuln.xml</filename> is + kept right inside the port + <package role="port">security/vuxml</package>. Therefore + the file's full pathname will be <filename>PORTSDIR/security/vuxml/vuln.xml</filename>. Each time you discover a security vulnerability in a port, please add an entry for it to that file. Until you are familiar @@ -11257,20 +11293,20 @@ as .putsy.conf and edit it.</programlist <sect2 xml:id="security-notify-vuxml-intro"> <title>A Short Introduction to VuXML</title> - <para>The full-blown <acronym>XML</acronym> format is complex, and far beyond the - scope of this book. However, to gain basic insight on the - structure of a VuXML entry you need only the notion of tags. - XML tag names are enclosed in angle brackets. Each opening - <tag> must have a matching closing </tag>. Tags - may be nested. If nesting, the inner tags must be closed - before the outer ones. There is a hierarchy of tags, i.e., - more complex rules of nesting them. This is similar to - HTML. The major difference is that XML is - e<emphasis>X</emphasis>tensible, i.e., based on defining - custom tags. Due to its intrinsic structure XML puts - otherwise amorphous data into shape. VuXML is particularly - tailored to mark up descriptions of security - vulnerabilities.</para> + <para>The full-blown <acronym>XML</acronym> format is complex, + and far beyond the scope of this book. However, to gain + basic insight on the structure of a VuXML entry you need + only the notion of tags. XML tag names are enclosed in + angle brackets. Each opening <tag> must have a + matching closing </tag>. Tags may be nested. If + nesting, the inner tags must be closed before the outer + ones. There is a hierarchy of tags, i.e., more complex + rules of nesting them. This is similar to HTML. The major + difference is that XML is e<emphasis>X</emphasis>tensible, + i.e., based on defining custom tags. Due to its intrinsic + structure XML puts otherwise amorphous data into shape. + VuXML is particularly tailored to mark up descriptions of + security vulnerabilities.</para> <para>Now consider a realistic VuXML entry:</para> @@ -11640,8 +11676,8 @@ Reference: <http://www.freebsd.org/po <sect1 xml:id="dads-intro"> <title>Introduction</title> - <para>Here is a list of common dos and don'ts that are encountered - during the porting process. Check the port + <para>Here is a list of common dos and don'ts that are + encountered during the porting process. Check the port against this list, but also check ports in the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR database</link> that others have submitted. Submit any @@ -11695,7 +11731,8 @@ Reference: <http://www.freebsd.org/po conditional compilation based upon what version of &os; Unix it is running under. The preferred way to tell &os; versions apart are the <literal>__FreeBSD_version</literal> and - <literal>__FreeBSD__</literal> macros defined in <link xlink:href="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>. + <literal>__FreeBSD__</literal> macros defined in <link + xlink:href="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>. If this file is not included add the code,</para> <programlisting>#include <sys/param.h></programlisting>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201401122030.s0CKUbxB099083>