svn commit: r48496 - head/zh_TW.UTF-8/books/porters-handbook
Kevin Lo <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
Author: kevlo (src,ports committer)
Date: Tue Mar 29 01:37:53 2016
New Revision: 48496
URL: https://svnweb.freebsd.org/changeset/doc/48496
Log:
Push recent translations.
Submitted by: https://reviews.freebsd.org/D5570
Reviewed by: wblock
Differential Revision: https://reviews.freebsd.org/D5570
Added:
head/zh_TW.UTF-8/books/porters-handbook/zh_TW.po (contents, props changed)
Modified:
head/zh_TW.UTF-8/books/porters-handbook/book.xml
Modified: head/zh_TW.UTF-8/books/porters-handbook/book.xml
==============================================================================
--- head/zh_TW.UTF-8/books/porters-handbook/book.xml Mon Mar 28 21:34:21 2016 (r48495)
+++ head/zh_TW.UTF-8/books/porters-handbook/book.xml Tue Mar 29 01:37:53 2016 (r48496)
@@ -1,1225 +1,1513 @@
<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
- "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [
+<!ENTITY values.uses SYSTEM "uses.xml">
+<!ENTITY values.versions SYSTEM "versions.xml">
<!--
The FreeBSD Documentation Project
$FreeBSD$
- Original Revision: 1.954
--->
-<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_tw">
- <info><title>FreeBSD Porter's Handbook</title>
-
+--><!ENTITY % chapters SYSTEM "chapters.ent">
+<!--
+ Creates entities for each chapter in the Porters Handbook. Each entity
+ is named chap.foo, where foo is the value of the id attribute on that
+ chapter, and corresponds to the name of the directory in which that
+ chapter's .xml file is stored.
+
+ Chapters should be listed in the order in which they are referenced.
+
+ $FreeBSD$
+--><!ENTITY chap.porting-why SYSTEM "porting-why/chapter.xml">
+<!ENTITY chap.new-port SYSTEM "new-port/chapter.xml">
+<!ENTITY chap.quick-porting SYSTEM "quick-porting/chapter.xml">
+<!ENTITY chap.slow-porting SYSTEM "slow-porting/chapter.xml">
+<!ENTITY chap.makefiles SYSTEM "makefiles/chapter.xml">
+<!ENTITY chap.special SYSTEM "special/chapter.xml">
+<!ENTITY chap.plist SYSTEM "plist/chapter.xml">
+<!ENTITY chap.pkg-files SYSTEM "pkg-files/chapter.xml">
+<!ENTITY chap.testing SYSTEM "testing/chapter.xml">
+<!ENTITY chap.upgrading SYSTEM "upgrading/chapter.xml">
+<!ENTITY chap.security SYSTEM "security/chapter.xml">
+<!ENTITY chap.porting-dads SYSTEM "porting-dads/chapter.xml">
+<!ENTITY chap.porting-samplem SYSTEM "porting-samplem/chapter.xml">
+<!ENTITY chap.keeping-up SYSTEM "keeping-up/chapter.xml">
+<!ENTITY chap.uses SYSTEM "uses/chapter.xml">
+<!ENTITY chap.versions SYSTEM "versions/chapter.xml">
+]>
+<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW">
+
+ <info>
+ <title>FreeBSD Porter 手冊</title>
<authorgroup>
- <author><orgname>FreeBSD 文件計劃</orgname></author>
+ <author><orgname>The FreeBSD Documentation Project</orgname></author>
</authorgroup>
- <pubdate>April 2000</pubdate>
+ <pubdate>$FreeBSD$</pubdate>
- <copyright>
- <year>2000</year>
- <year>2001</year>
- <year>2002</year>
- <year>2003</year>
- <year>2004</year>
- <year>2005</year>
- <year>2006</year>
- <year>2007</year>
- <year>2008</year>
- <holder role="mailto:[email protected]">FreeBSD 文件計劃</holder>
- </copyright>
+ <copyright><year>2000</year> <year>2001</year> <year>2002</year> <year>2003</year> <year>2004</year> <year>2005</year> <year>2006</year> <year>2007</year> <year>2008</year> <year>2009</year> <year>2010</year> <year>2011</year> <year>2012</year> <year>2013</year> <year>2014</year> <year>2015</year> <year>2016</year> <holder role="mailto:[email protected]">The FreeBSD Documentation Project</holder></copyright>
- &trademarks;
+
+<legalnotice xml:id="legalnotice">
+ <title>版權所有</title>
- &legalnotice;
+ <para xml:lang="en">Redistribution and use in source (XML DocBook) and 'compiled'
+ forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without
+ modification, are permitted provided that the following conditions are
+ met:</para>
+
+ <orderedlist>
+ <listitem>
+ <para xml:lang="en">Redistributions of source code (XML DocBook) must retain the
+ above copyright notice, this list of conditions and the following
+ disclaimer as the first lines of this file unmodified.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Redistributions in compiled form (transformed to other DTDs,
+ converted to PDF, PostScript, RTF and other formats) must
+ reproduce the above copyright notice, this list of conditions and
+ the following disclaimer in the documentation and/or other
+ materials provided with the distribution.</para>
+ </listitem>
+ </orderedlist>
+
+ <important>
+ <para xml:lang="en">THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION
+ PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
+ BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+ THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT,
+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+ TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+ USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+ DAMAGE.</para>
+ </important>
+</legalnotice>
+
+
+ <legalnotice xml:id="trademarks" role="trademarks">
+ <para>FreeBSD 是 FreeBSD 基金會的註冊商標。</para>
+ <para>UNIX 是 The Open Group 在美國和其他國家的註冊商標。</para>
+ <para>Sun, Sun Microsystems, Java, Java Virtual Machine, JDK, JRE, JSP, JVM, Netra, OpenJDK, Solaris, StarOffice, SunOS 和 VirtualBox 是 Sun Microsystems, Inc. 在美國和其他國家的註冊商標。</para>
+ <para xml:lang="en">Many of the designations used by
+ manufacturers and sellers to distinguish their products are claimed
+ as trademarks. Where those designations appear in this document,
+ and the FreeBSD Project was aware of the trademark claim, the
+ designations have been followed by the <quote>™</quote> or the
+ <quote>®</quote> symbol.</para>
+ </legalnotice>
<releaseinfo>$FreeBSD$</releaseinfo>
</info>
- <chapter xml:id="why-port">
- <title>楔子</title>
+
+<!--
+ The FreeBSD Documentation Project
- <para>幾乎每個 FreeBSD 愛用者都是透過 FreeBSD Ports Collection
- 來裝各式應用程式("ports")。如同 FreeBSD 的其他部分一樣，
- 這些 ports 都主要來自許多志工的努力成果，所以在閱讀這份文件時，
- 請務必感恩在心。</para>
-
- <para>在 FreeBSD 上面，每個人都可以提交新的 port，
- 或假如該 port 並沒有人維護的話，可以自願維護 —
- 這點並不需要任何 commit 的權限，就可以來做這件事情。</para>
-
- </chapter>
-
- <chapter xml:id="own-port">
- <title>自行打造 port</title>
-
- <para>那麼，開始對自行製作 port 或更新有一些興趣了嗎？太好囉！</para>
-
- <para>下面將介紹一些建立 port 時該注意的事項。如果是想升級現有的 port
- ，那麼也請參閱 <xref linkend="port-upgrading"/> 說明。</para>
-
- <para>因為這份文件可能講得不是十分詳細，可能需要參考
- <filename>/usr/ports/Mk/bsd.port.mk</filename> 這檔是所有 port 的
- Makefile 檔都會用到的。 就算你不是每天不斷 hacking Makefiles
- ，也都可以藉由它來對整個 port 機制、Makefile 更瞭解，
- 裡面的註釋相當詳細。 此外，若有其他特定 port 的問題，也可以到
- &a.ports; 來獲得答案。</para>
+ $FreeBSD$
+-->
+<chapter version="5.0" xml:id="why-port">
- <note>
- <para>本文內所提及的環境變數
- (<varname><replaceable>VAR</replaceable></varname>)部份，
- 只有一些可以替換(overridden)。大部份的環境變數(非全部)通常都會寫在
- <filename>/usr/ports/Mk/bsd.port.mk</filename> 內，其他的也是差不多。
- 請注意：該檔並非使用一般的 tab 設定值，而是採用 1 個 tab 等於 4 個
- space。 <application>Emacs</application> 與
- <application>Vim</application> 應該都會在載入該檔時順便讀取相關設定值。
- &man.vi.1; 及 &man.ex.1; 這兩個程式也都可以打
- <command>:set tabstop=4</command> 以修改設定值。</para>
- </note>
- </chapter>
+ <title>楔子</title>
- <chapter xml:id="quick-porting">
- <title>打造 Port 快速上手篇</title>
+ <para>幾乎每個 FreeBSD 愛用者都是透過 FreeBSD Ports Collection 來裝各式應用程式("ports")。如同 FreeBSD 的其他部分一樣， 這些 ports 都主要來自許多志工的努力成果，所以在閱讀這份文件時， 請務必感恩在心。</para>
- <para>本節主要介紹如何來快速打造 port，然而，
- 很多時候這些內容並不是很夠用，建議閱讀本文件中更深奧的地方。</para>
+ <para>在 FreeBSD 上面，每個人都可以提交新的 port， 或假如該 port 並沒有人維護的話，可以自願維護 —— 這點並不需要任何 commit 的權限，就可以來做這件事情。</para>
+</chapter>
- <para>首先取得該應用程式的原始程式碼壓縮檔(tarball)，並把它放到
- <varname>DISTDIR</varname>，預設路徑應該是
- <filename>/usr/ports/distfiles</filename>。</para>
- <note>
- <para>下面的例子，是假設並不需要再修改該應用程式的原始碼，就可以在
- FreeBSD 上編譯成功的；假如還需要另外修改才能成功編譯的話，
- 那麼請參考下一章的說明。</para>
- </note>
+
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD$
+-->
- <sect1 xml:id="porting-makefile">
- <title>編寫 <filename>Makefile</filename></title>
+<chapter version="5.0" xml:id="own-port">
- <para>最簡單的 <filename>Makefile</filename> 大概是像這樣：</para>
+ <title>製作新的 Port</title>
- <programlisting># New ports collection makefile for: oneko
-# Date created: 5 December 1994
-# Whom: asami
-#
-# $FreeBSD$
-#
+ <para>開始對製作新的 port 或更新現有 port 有一些興趣了嗎？太好囉！</para>
+
+ <para>下面將介紹一些建立 port 時該注意的事項。如果是想升級現有的 port ，那麼也請參閱 <xref linkend="port-upgrading"/> 說明。</para>
+
+ <para>因為這份文件可能講得不是十分詳細，可能需要參考 <filename>/usr/ports/Mk/bsd.port.mk</filename> 這檔是所有 port 的 <filename>Makefile</filename> 檔都會用到的。就算你不是每天不斷 hacking <filename>Makefile</filename>，也可以也可以從中獲得很多相關知識。 此外，若有其他特定 port 的問題，也可以到 <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports">FreeBSD ports mailing list</link> 來獲得答案。</para>
+
+ <note>
+ <para>本文內所提及的環境變數 (<varname><replaceable>VAR</replaceable></varname>)部份， 只有一些可以替換(overridden)。大部份的環境變數(非全部)通常都會寫在 <filename>/usr/ports/Mk/bsd.port.mk</filename> 內，其他的也是差不多。 請注意：該檔並非使用一般的 tab 設定值，而是採用 1 個 tab 等於 4 個 space。 <application>Emacs</application> 與 <application>Vim</application> 應該都會在載入該檔時順便讀取相關設定值。 <citerefentry><refentrytitle>vi</refentrytitle><manvolnum>1</manvolnum></citerefentry> 及 <citerefentry><refentrytitle>ex</refentrytitle><manvolnum>1</manvolnum></citerefentry> 這兩個程式也都可以打 <command>:set tabstop=4</command> 以修改設定值。</para>
+ </note>
+
+ <para>想要找簡單的開始上手嗎？ 到 <link xlink:href="http://wiki.freebsd.org/WantedPorts">請求協助的 ports 清單</link> 瞧瞧，看看是否有你可以幫上忙的。</para>
+</chapter>
+
+
+
+<!--
+ The FreeBSD Documentation Project
-PORTNAME= oneko
-PORTVERSION= 1.1b
-CATEGORIES= games
-MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
-
-MAINTAINER= [email protected]
-COMMENT= A cat chasing a mouse all over the screen
-
-MAN1= oneko.1
-MANCOMPRESSED= yes
-USE_IMAKE= yes
+ $FreeBSD$
+-->
+<chapter version="5.0" xml:id="quick-porting">
+
+ <title>打造 Port 快速上手篇</title>
+
+ <para>本節主要介紹如何來快速打造 port，然而實際應用時這快速方法可能不足，完整的 <quote>慢速打造 Port</quote> 的步驟在 <xref linkend="slow-porting"/> 詳述。</para>
+
+ <para>首先取得該應用程式的原始程式碼壓縮檔(tarball)，並把它放到 <varname>DISTDIR</varname>，預設路徑應該是 <filename>/usr/ports/distfiles</filename>.</para>
+
+ <note>
+ <para>這些步驟假設軟體可以直接編譯。也就是不需要任何修改就可以直接在 FreeBSD 上執行。如果需要修改，請參見<xref linkend="slow-porting"/>。</para>
+ </note>
+
+ <note>
+ <para xml:lang="en">It is recommended to set the <varname>DEVELOPER</varname>
+ <citerefentry><refentrytitle>make</refentrytitle><manvolnum>1</manvolnum></citerefentry> variable in <filename>/etc/make.conf</filename>
+ before getting into porting.</para>
+
+ <screen xml:lang="en"><prompt>#</prompt> <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen>
+
+ <para xml:lang="en">This setting enables the <quote>developer mode</quote>
+ that displays deprecation warnings and activates some further
+ quality checks on calling <command>make</command>.</para>
+ </note>
+
+ <sect1 xml:id="porting-makefile">
+ <title>編寫 <filename>Makefile</filename></title>
+
+ <para>最簡單的 <filename>Makefile</filename> 大概是像這樣：</para>
+
+ <programlisting># $FreeBSD$
+
+PORTNAME= oneko
+PORTVERSION= 1.1b
+CATEGORIES= games
+MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
+
+MAINTAINER= [email protected]
+COMMENT= Cat chasing a mouse all over the screen
.include <bsd.port.mk></programlisting>
- <para>嗯，大致就是這樣，看看你已經領略多少了呢？
- 看到 <literal>$FreeBSD$</literal> 這一行的話，別想太多
- ，它是 RCS ID 用途，當該 port 正式進入 port tree 時，
- CVS 就會自動轉換為相關字串囉。 有關這點的細節部份，可以參閱 <link linkend="porting-samplem">sample Makefile</link> 章節。</para>
- </sect1>
-
- <sect1 xml:id="porting-desc">
- <title>撰寫該軟體的說明檔</title>
-
- <para>無論是否打算再加工做成 package，有 2 個檔案是任何實體 port (Slave
- port則不一定)都必須要具備的。 這 2 個檔分別是
- <filename>pkg-descr</filename> 檔及 <filename>pkg-plist</filename>
- 檔。 這兩個檔案檔名前面都有 <filename>pkg-</filename>
- 以跟其他檔案做區別。</para>
+ <note>
+ <para xml:lang="en">In some cases, the <filename>Makefile</filename> of an
+ existing port may contain additional lines in the header,
+ such as the name of the port and the date it was created.
+ This additional information has been declared obsolete, and
+ is being phased out.</para>
+ </note>
+
+ <para>嗯，大致就是這樣，看看你已經領略多少了呢？ 看到 <literal>$FreeBSD$</literal> 這一行的話，別想太多 ，當該 port 正式進入 port tree 時， <application>Subversion</application> 就會自動轉換為相關字串囉。 有關這點的細節部份，可以參閱 <link linkend="porting-samplem">sample Makefile</link> 章節。</para>
+ </sect1>
+
+ <sect1 xml:id="porting-desc">
+ <title>撰寫說明檔</title>
- <sect2>
- <title><filename>pkg-descr</filename></title>
+ <para>無論是否打算再加工做成 package，有兩個檔案是任何 port 都必須要具備的。 這兩個檔分別是 <filename>pkg-descr</filename> 及 <filename>pkg-plist</filename> 。 他們檔名前面都有 <filename>pkg-</filename> 以跟其他檔案做區別。</para>
- <para>這是此 port 的詳細說明檔，請用一段或幾段文字來說明該 port
- 的作用，並附上 WWW 網址(若有的話)。</para>
+ <sect2 xml:id="porting-pkg-descr">
+ <title><filename>pkg-descr</filename></title>
- <note>
- <para>請注意，這檔絕非「該軟體的說明手冊」或是「如何編譯、使用該
- port 的說明」。 若是從該軟體的 <filename>README</filename>
- 或 manpage 直接複製過來的話，請注意，因為它們通常都寫得太詳細、
- 格式較特別(比如 manpage 會自動調整空白)，
- 請儘量避免這些冗長贅詞或採用特殊格式。若該軟體有官方版首頁的話，
- 請在此列出來。 每個網址請用 <literal>WWW:</literal> 作為開頭，
- 這樣子相關工具程式就會自動處理完畢。</para>
- </note>
+ <para>這是此 port 的詳細說明檔，請用一段或幾段文字來說明該 port 的作用</para>
- <para>該 port 的 <filename>pkg-descr</filename> 內容，大致如下面例子
- ：</para>
+ <note>
+ <para>請注意，這檔<emphasis>絕非</emphasis>「該軟體的說明手冊」或是「如何編譯、使用該 port 的說明」！ <emphasis>若是從該軟體的 <filename>README</filename> 或 manpage 直接複製過來的話，請注意</emphasis>。他們常常不是正確的 port 描述或是格式並不適合。例如，manpage會對齊空白，這用monospace字型來看會特別糟糕。</para>
+ </note>
+
+ <para xml:lang="en">A well-written <filename>pkg-descr</filename> describes
+ the port completely enough that users would not have to
+ consult the documentation or visit the website to understand
+ what the software does, how it can be useful, or what
+ particularly nice features it has. Mentioning certain
+ requirements like a graphical toolkit, heavy dependencies,
+ runtime environment, or implementation languages help users
+ decide whether this port will work for them.</para>
+
+ <para xml:lang="en">Include a URL to the official WWW homepage. Prepend
+ <emphasis>one</emphasis> of the websites (pick the most
+ common one) with <literal>WWW:</literal> (followed by single
+ space) so that automated tools will work correctly. If the
+ URI is the root of the website or directory, it must be
+ terminated with a slash.</para>
+
+ <note>
+ <para xml:lang="en">If the listed webpage for a port is not available, try
+ to search the Internet first to see if the official site
+ moved, was renamed, or is hosted elsewhere.</para>
+ </note>
- <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
+ <para>這是 <filename>pkg-descr</filename> 內容的例子 ：</para>
+
+ <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
:
(etc.)
WWW: http://www.oneko.org/</programlisting>
- </sect2>
+ </sect2>
- <sect2>
- <title><filename>pkg-plist</filename></title>
+ <sect2 xml:id="porting-pkg-plist">
+ <title><filename>pkg-plist</filename></title>
- <para>這是該 port 所會裝的所有檔案清單，另外因為 package
- 會由這清單所產生，因此也被稱為『packing list
- (打包清單)』。 以 <literal>${PREFIX}</literal> 為基準點，
- 而用相對路徑表示。(<literal>${PREFIX}</literal> 通常是
- <filename>/usr/local</filename> 或 <filename>/usr/X11R6</filename>)
- 但是如果該程式有安裝 man page 的話，則要以類似
- <varname>MAN<replaceable>n</replaceable>=</varname> 的方式寫在
- <filename>Makefile</filename> 內，不能列在
- <filename>pkg-plist</filename> 哦。
- 除了列出檔案以外，也要把該 port 所會建立的目錄也列進去，
- 方式有兩種：一種是寫在 <filename>pkg-plist</filename> 內的方式，
- 比如：<literal>@dirrm</literal>。 至於另外一種方式，則是寫在
- <filename>Makefile</filename> 內，比如：
- <literal>PLIST_FILES=</literal> 之類的方式。</para>
+ <para>這是該 port 所會裝的所有檔案清單，另外因為 package 會由這清單所產生，因此也被稱為『<quote>packing list (打包清單)</quote>』。路徑是相對於安裝的 prefix (通常是 <filename>/usr/local</filename> )。</para>
- <para>該 port 的 <filename>pkg-plist</filename> 內容，
- 大致如下面例子:</para>
+ <para>這是一個簡單的例子：</para>
- <programlisting>bin/oneko
+ <programlisting>bin/oneko
+man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
-lib/X11/oneko/mouse.xpm
-@dirrm lib/X11/oneko</programlisting>
+lib/X11/oneko/mouse.xpm</programlisting>
- <para>關於 packing list 方面，可以參閱 &man.pkg.create.1; 會有詳解
- 。</para>
+ <para>關於 packing list 方面，可以詳閱 <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> manual page 。</para>
- <note>
- <para>建議清單內的檔名，依照字母順序作排序，那麼下次要升級時，
- 會比較清楚、方便來更新這份清單。 </para>
- </note>
+ <note>
+ <para>建議清單內的檔名，依照字母順序作排序，那麼下次要升級時， 會比較清楚、方便來更新這份清單。 </para>
+ </note>
- <note>
- <para>手動生這份清單實在太苦了。尤其若該 port 會裝一大堆檔案的話，
- 請多善用 <link linkend="plist-autoplist">自動產生 packing
- list</link> 會比較省時省力唷。</para>
- </note>
+ <tip>
+ <para>手動產生這份清單實在太苦了。尤其若該 port 會裝一大堆檔案的話， 請多善用 <link linkend="plist-autoplist">自動產生 packing list</link> 會比較省時省力唷。</para>
+ </tip>
+
+ <para>只有在一種情況下可以省略 <filename>pkg-plist</filename> 檔： 若安裝的 port 相當單純，只有裝一些檔案，那麼可以在 <filename>Makefile</filename> 內改用 <varname>PLIST_FILES</varname> 來取代。 比如，可以在上述的 <filename>oneko</filename> port 內不必附上 <filename>pkg-plist</filename> ，而只需在 <filename>Makefile</filename> 內加入下列幾行：</para>
+
+ <programlisting>PLIST_FILES= bin/oneko \
+ man/man1/oneko.1.gz \
+ lib/X11/app-defaults/Oneko \
+ lib/X11/oneko/cat1.xpm \
+ lib/X11/oneko/cat2.xpm \
+ lib/X11/oneko/mouse.xpm</programlisting>
+
+ <note>
+ <para xml:lang="en">Usage of <varname>PLIST_FILES</varname> should not be
+ abused. When looking for the origin of a file, people
+ usually try to <application>grep</application> through the
+ <filename>pkg-plist</filename> files in the ports tree.
+ Listing files in <varname>PLIST_FILES</varname> in the
+ <filename>Makefile</filename> makes that search more
+ difficult.</para>
+ </note>
- <para>只有在一種情況下可以省略不用生 <filename>pkg-plist</filename>
- 檔： 若安裝的 port 相當單純，只有裝一些檔案，
- 以及都在同一目錄下的話，那麼可以在 <filename>Makefile</filename>
- 內改用 <varname>PLIST_FILES</varname> 及
- <varname>PLIST_DIRS</varname> 來取代。
- 比如，可以在上述的 <filename>oneko</filename> port 內不必附上
- <filename>pkg-plist</filename> ，而只需在
- <filename>Makefile</filename> 內加入下列幾行：</para>
-
- <programlisting>PLIST_FILES= bin/oneko \
- lib/X11/app-defaults/Oneko \
- lib/X11/oneko/cat1.xpm \
- lib/X11/oneko/cat2.xpm \
- lib/X11/oneko/mouse.xpm
-PLIST_DIRS= lib/X11/oneko</programlisting>
-
- <para>當然，若該 port 並無安裝自屬的目錄的話，就不必設
- <varname>PLIST_DIRS</varname> 囉。</para>
-
- <para>然而，使用 <varname>PLIST_FILES</varname>、
- <varname>PLIST_DIRS</varname> 是必須付出代價：
- 不能使用 &man.pkg.create.1; 內所說的 command sequences。
- 因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。
- 此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。
- 所以，在考慮是否一定要用 <filename>pkg-plist</filename> 之前，
- 可以先斟酌這個替代方案看看。</para>
-
- <para>後面會介紹到如何運用 <filename>pkg-plist</filename>、
- <varname>PLIST_FILES</varname> 這些技巧以因應 <link linkend="plist">更複雜的狀況</link>。</para>
- </sect2>
- </sect1>
-
- <sect1 xml:id="porting-checksum">
- <title>產生 checksum 用途的 distinfo 檔</title>
-
- <para>只要打『<command>make makesum</command>』就好了，
- 接下來就會自動產生相對應的 <filename>distinfo</filename> 檔了唷
- 。</para>
- </sect1>
+ <tip>
+ <para xml:lang="en">If a port needs to create an empty directory, or creates
+ directories outside of <filename>${PREFIX}</filename> during
+ installation, refer to <xref linkend="plist-dir-cleaning"/>
+ for more information.</para>
+ </tip>
- <sect1 xml:id="porting-testing">
- <title>檢驗 port 是否完整、可行</title>
+ <para>然而，使用這個方法列出 port 的檔案和目錄是必須付出代價： 不能使用 <citerefentry><refentrytitle>pkg-create</refentrytitle><manvolnum>8</manvolnum></citerefentry> 和 <xref linkend="plist-keywords"/> 描述的關鍵字。 因此，這招僅適用於較簡單的 port ，以及簡化該 port 的作法。 此外，這招還有一個好處：可以減少 ports collection 的整體檔案總數。 所以，在考慮是否要用 <filename>pkg-plist</filename> 之前， 可以先斟酌這個替代方案看看。</para>
- <para>接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port
- 為 package。 以下有幾個需要確認的重要地方：</para>
+ <para>後面會介紹到如何運用 <filename>pkg-plist</filename>、 <varname>PLIST_FILES</varname> 這些技巧以因應<link linkend="plist">更複雜的狀況</link>。</para>
+ </sect2>
+ </sect1>
- <itemizedlist>
+ <sect1 xml:id="porting-checksum">
+ <title>產生 checksum 檔</title>
+
+ <para>只要打 <command>make makesum</command> 就好了， 接下來就會自動產生相對應的 <filename>distinfo</filename> 檔了唷 。</para>
+ </sect1>
+
+ <sect1 xml:id="porting-testing">
+ <title>測試 Port</title>
+
+ <para>接下來，必須檢驗是否有符合 port 的遊戲規則，包括打包該 port 為 package。 以下有幾個需要確認的重要地方：</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>若該 port 沒裝的東西，不要列在 <filename>pkg-plist</filename> 內。</para>
+ </listitem>
+
+ <listitem>
+ <para>若該 port 有裝的東西，請務必列在 <filename>pkg-plist</filename> 內。</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">The port can be installed using the
+ <buildtarget xml:lang="en">install</buildtarget> target. This verifies
+ that the install script works correctly.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">The port can be deinstalled properly using the
+ <buildtarget xml:lang="en">deinstall</buildtarget> target. This
+ verifies that the deinstall script works correctly.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">The port does not access network resources after the
+ <buildtarget xml:lang="en">fetch</buildtarget> target. This is important
+ for package builders, such as <package role="port">ports-mgmt/poudriere</package>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Make sure that <command>make package</command> can be
+ run as a normal user (that is, not as
+ <systemitem class="username">root</systemitem>). If that
+ fails, <literal>NEED_ROOT=yes</literal> must be added to
+ the port <filename>Makefile</filename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <procedure>
+ <title>建議的測試順序</title>
+
+ <step>
+ <para><command>make stage</command></para>
+ </step>
+
+ <step>
+ <para><command>make check-orphans</command></para>
+ </step>
+
+ <step>
+ <para><command>make package</command></para>
+ </step>
+
+ <step>
+ <para><command>make install</command></para>
+ </step>
+
+ <step>
+ <para><command>make deinstall</command></para>
+ </step>
+
+ <step>
+ <para><command>pkg add <replaceable>package-filename</replaceable></command></para>
+ </step>
+
+ <step>
+ <para xml:lang="en"><command>make package</command> (as user)</para>
+ </step>
+ </procedure>
+
+ <para>確認在任何階段都沒有任何警告出現。</para>
+
+ <para xml:lang="en">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
+ <literal>jails</literal> where all of the steps shown above
+ can be tested without affecting the state of the host
+ system.</para>
+ </sect1>
+
+ <sect1 xml:id="porting-portlint">
+ <title>以 <command>portlint</command> 來作檢查 Port</title>
+
+ <para>請用 <command>portlint</command> 來檢查該 port 是否有遵循我們的規則。 <package role="port">ports-mgmt/portlint</package> 是 ports collection 的其中一個套件。 它主要可以用來檢驗 <link linkend="porting-samplem">Makefile</link> 內容是否正確以及 <link linkend="porting-pkgname">package</link> 是否有正確命名。</para>
+ </sect1>
+
+ <sect1 xml:id="porting-submitting">
+ <title>提交新的 Port</title>
+
+ <para>提交新的 Port 前，請閱讀 <link linkend="porting-dads">DOs and DON'Ts</link> 章節。</para>
+
+ <para>現在你很高興終於打造出 port 來囉，唯一剩下要做的就是把它正式放到 FreeBSD ports tree 內，才能讓每個人都能分享使用這個 port。 我們不需要 <filename>work</filename> 目錄或是檔名像 <filename>pkgname.tgz</filename> 的 package ，請現在刪除他們。</para>
+
+ <para xml:lang="en">Next, build the <citerefentry><refentrytitle>shar</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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>
+
+ <!-- The link here is wrong, but, I have no idea where
+ to point it now, so commenting the whole paragraph.
+
+ <para>Include <filename>oneko.shar</filename> in a bug
+ report and submit it. See <link
+ xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
+ Reports and General Commentary</link> for more information
+ submitting problem reports.</para> -->
+
+ <para xml:lang="en">To submit <filename>oneko.shar</filename>, use the <link xlink:href="https://bugs.freebsd.org/submit/">bug submit
+ form</link> (category <literal>Ports Tree</literal>).
+ Add a short
+ description of the program to the Description field of the PR
+ (perhaps a short version of <varname>COMMENT</varname>), and
+ do not forget to add <filename>oneko.shar</filename> as an
+ attachment.</para>
+
+ <note>
+ <para xml:lang="en">Giving a good description in the summary of the problem
+ report makes the work of port committers a lot easier. We
+ prefer something like <quote>New port:
+ <replaceable>category</replaceable>/<replaceable>portname</replaceable> <replaceable>short description of
+ the port</replaceable></quote> for new ports. Using this
+ scheme makes it easier and faster to begin the work of
+ committing the new port.</para>
+ </note>
+
+ <para>再次強調一點：<emphasis>不必附上原始 source 的 distfile ，也就是 <filename>work</filename> 目錄。 同時，也不必附上 <command>make package</command> 時產生的 package</emphasis>。新的 port 請使用 <citerefentry><refentrytitle>shar</refentrytitle><manvolnum>1</manvolnum></citerefentry> ，不要用 <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> 。</para>
+
+ <para>送出 port 之後，請耐心等候佳音。 有時候可能需要等個幾天或幾個月時間，才會在 FreeBSD ports tree 上正式出現。 等待中的 port <acronym>PR</acronym> 清單可以在 <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"/> 查閱。</para>
+
+ <para>在看過新的 port 之後，如果需要的話，我們會回覆您，然後會將它提交到 port tree 。 您的大名會被列在 <link xlink:href="@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/contributors/contrib-additional.html">Additional FreeBSD Contributors</link> 列表上，以及其他檔案中。</para>
+ </sect1>
+</chapter>
+
+
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD$
+-->
+<chapter version="5.0" xml:id="slow-porting">
+
+ <title xml:lang="en">Slow Porting</title>
+
+ <para>Ok...事實上並不太可能這麼簡單，port 方面可能需要作些修改才能正常使用。 因此， 本節將一步一步來介紹如何修改上一章的樣本以正常使用。</para>
+
+ <sect1 xml:id="slow-work">
+ <title xml:lang="en">How Things Work</title>
+
+ <para xml:lang="en">First, this is the sequence of events which occurs when the
+ user first types <command>make</command> in the port's
+ directory. Having
+ <filename>bsd.port.mk</filename> in another window while
+ reading this really helps to understand it.</para>
+
+ <para>別太擔心，不是很多人都真的了解 <filename>bsd.port.mk</filename> 在做什麼... <emphasis>:-)</emphasis></para>
+
+ <procedure>
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">fetch</buildtarget> target is run. The
+ <buildtarget xml:lang="en">fetch</buildtarget> target is responsible for
+ making sure that the tarball exists locally in
+ <varname>DISTDIR</varname>. If
+ <buildtarget xml:lang="en">fetch</buildtarget> cannot find the required
+ files in <varname>DISTDIR</varname> it will look up the URL
+ <varname>MASTER_SITES</varname>, which is set in the
+ Makefile, as well as our FTP mirrors where we put distfiles
+ as backup. It will then attempt to fetch the named
+ distribution file with <varname>FETCH</varname>, assuming
+ that the requesting site has direct access to the Internet.
+ If that succeeds, it will save the file in
+ <varname>DISTDIR</varname> for future use and
+ proceed.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">extract</buildtarget> target is run.
+ It looks for the port's distribution file (typically a
+ <command>gzip</command>ped tarball) in
+ <varname>DISTDIR</varname> and unpacks it into a temporary
+ subdirectory specified by <varname>WRKDIR</varname>
+ (defaults to <filename>work</filename>).</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">patch</buildtarget> target is run.
+ First, any patches defined in <varname>PATCHFILES</varname>
+ are applied. Second, if any patch files named
+ <filename>patch-<replaceable>*</replaceable></filename> are
+ found in <varname>PATCHDIR</varname> (defaults to the
+ <filename>files</filename> subdirectory), they are applied
+ at this time in alphabetical order.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">configure</buildtarget> target is run.
+ This can do any one of many different things.</para>
+
+ <orderedlist>
<listitem>
- <para>若該 port 沒裝的東西，不要列在 <filename>pkg-plist</filename>
- 內。</para>
+ <para xml:lang="en">If it exists, <filename>scripts/configure</filename>
+ is run.</para>
</listitem>
<listitem>
- <para>若該 port 有裝的東西，請務必列在
- <filename>pkg-plist</filename> 內。</para>
+ <para xml:lang="en">If <varname>HAS_CONFIGURE</varname> or
+ <varname>GNU_CONFIGURE</varname> is set,
+ <filename>WRKSRC/configure</filename> is run.</para>
</listitem>
+ </orderedlist>
+ </step>
+
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">build</buildtarget> target is run.
+ This is responsible for descending into the port's private
+ working directory (<varname>WRKSRC</varname>) and building
+ it.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">stage</buildtarget> target is run.
+ This puts the final set of built files into a temporary
+ directory (<varname>STAGEDIR</varname>, see
+ <xref linkend="staging"/>). The hierarchy of this directory
+ mirrors that of the system on which the package will be
+ installed.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">package</buildtarget> target is run.
+ This creates a package using the files from the temporary
+ directory created during the
+ <buildtarget xml:lang="en">stage</buildtarget> target and the port's
+ <filename>pkg-plist</filename>.</para>
+ </step>
+
+ <step>
+ <para xml:lang="en">The <buildtarget xml:lang="en">install</buildtarget> target is run.
+ This installs the package created during the
+ <buildtarget xml:lang="en">package</buildtarget> target into the host
+ system.</para>
+ </step>
+ </procedure>
+
+ <para xml:lang="en">The above are the default actions. In addition,
+ define targets
+ <buildtarget xml:lang="en">pre-<replaceable>something</replaceable></buildtarget>
+ or
+ <buildtarget xml:lang="en">post-<replaceable>something</replaceable></buildtarget>,
+ or put scripts with those names, in the
+ <filename>scripts</filename> subdirectory, and they will be
+ run before or after the default actions are done.</para>
+
+ <para xml:lang="en">For example, if there is a
+ <buildtarget xml:lang="en">post-extract</buildtarget> target defined in the
+ <filename>Makefile</filename>, and a file
+ <filename>pre-build</filename> in the
+ <filename>scripts</filename> subdirectory, the
+ <buildtarget xml:lang="en">post-extract</buildtarget> target will be called
+ after the regular extraction actions, and
+ <filename>pre-build</filename> will be executed before
+ the default build rules are done. It is recommended to
+ use <filename>Makefile</filename> targets if the actions are
+ simple enough, because it will be easier for someone to figure
+ out what kind of non-default action the port requires.</para>
+
+ <para xml:lang="en">The default actions are done by the
+ <buildtarget xml:lang="en">do-<replaceable>something</replaceable></buildtarget>
+ targets from <filename>bsd.port.mk</filename>.
+ For example, the commands to extract a port are in the target
+ <buildtarget xml:lang="en">do-extract</buildtarget>. If
+ the default target does not do the job right, redefine the
+ <buildtarget xml:lang="en">do-<replaceable>something</replaceable></buildtarget>
+ target in the <filename>Makefile</filename>.</para>
+
+ <note>
+ <para xml:lang="en">The <quote>main</quote> targets (for example,
+ <buildtarget xml:lang="en">extract</buildtarget>,
+ <buildtarget xml:lang="en">configure</buildtarget>, etc.) do nothing more
+ than make sure all the stages up to that one are completed and
+ call the real targets or scripts, and they are not intended to
+ be changed. To fix the extraction, fix
+ <buildtarget xml:lang="en">do-extract</buildtarget>, but never ever change
+ the way <buildtarget xml:lang="en">extract</buildtarget> operates!
+ Additionally, the target
+ <buildtarget xml:lang="en">post-deinstall</buildtarget> is invalid and is
+ not run by the ports infrastructure.</para>
+ </note>
+
+ <para xml:lang="en">Now that what goes on when the user types <command>make
+ install</command> is better understood, let us go through the
+ recommended steps to create the perfect port.</para>
+ </sect1>
+
+ <sect1 xml:id="slow-sources">
+ <title>取得原始碼</title>
+
+ <para xml:lang="en">Get the original sources (normally) as a compressed tarball
+ (<filename>foo.tar.gz</filename> or
+ <filename><replaceable>foo</replaceable>.tar.bz2</filename>) and
+ copy it into <varname>DISTDIR</varname>. Always use
+ <emphasis>mainstream</emphasis> sources when and where
+ possible.</para>
+
+ <para xml:lang="en">Set the variable
+ <varname>MASTER_SITES</varname> to reflect where the original
+ tarball resides. Shorthand definitions exist
+ for most mainstream sites in <filename>bsd.sites.mk</filename>.
+ Please use these sites—and the associated
+ definitions—if at all possible, to help avoid the problem
+ of having the same information repeated over again many times in
+ the source base. As these sites tend to change over time, this
+ becomes a maintenance nightmare for everyone involved. See
+ <xref linkend="makefile-master_sites"/> for details.</para>
+
+ <para xml:lang="en">If there is no FTP/HTTP site that is well-connected to
+ the net, or can only find sites that have irritatingly
+ non-standard formats, put a copy on a reliable
+ FTP or HTTP server (for example, a home
+ page).</para>
+
+ <para xml:lang="en">If a convenient and reliable place to put
+ the distfile cannot be found, we can <quote>house</quote> it ourselves on
+ <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the
+ least-preferred solution. The distfile must be placed into
+ <filename>~/public_distfiles/</filename> of someone's
+ <systemitem>freefall</systemitem> account. Ask the person who
+ commits the port to do this. This person will also set
+ <varname>MASTER_SITES</varname> to
+ <literal>LOCAL/<replaceable>username</replaceable></literal>
+ where <literal><replaceable>username</replaceable></literal> is
+ their FreeBSD cluster login.</para>
+
+ <para xml:lang="en">If the port's distfile changes all the time without any
+ kind of version update by the author, consider putting the
+ distfile on a home page and listing it as the first
+ <varname>MASTER_SITES</varname>. Try to talk the
+ port author out of doing this; it really does help to establish
+ some kind of source code control. Hosting a specific version will
+ prevent users from getting
+ <errorname>checksum mismatch</errorname> errors, and also reduce
+ the workload of maintainers of our FTP site. Also, if there is
+ only one master site for the port, it is recommended to
+ house a backup on a home page and list it as the second
+ <varname>MASTER_SITES</varname>.</para>
+
+ <para xml:lang="en">If the port requires additional patches that are
+ available on the Internet, fetch them too and put them in
+ <varname>DISTDIR</varname>. Do not worry if they come from a
+ site other than where the main source tarball comes, we have a
+ way to handle these situations (see the description of <link linkend="porting-patchfiles">PATCHFILES</link> below).</para>
+ </sect1>
+
+ <sect1 xml:id="slow-modifying">
+ <title xml:lang="en">Modifying the Port</title>
+
+ <para xml:lang="en">Unpack a copy of the tarball in a private directory and make
+ whatever changes are necessary to get the port to compile
+ properly under the current version of FreeBSD. Keep
+ <emphasis>careful track</emphasis> of steps, as they will be
+ needed to automate the process shortly. Everything, including
+ the deletion, addition, or modification of files has to be
+ doable using an automated script or patch file when the port is
+ finished.</para>
+
+ <para xml:lang="en">If the port requires significant user
+ interaction/customization to compile or install, take
+ a look at one of Larry Wall's classic
+ <application>Configure</application> scripts and perhaps do
+ something similar. The goal of the new ports
+ collection is to make each port as <quote>plug-and-play</quote>
+ as possible for the end-user while using a minimum of disk
+ space.</para>
+
+ <note>
+ <para xml:lang="en">Unless explicitly stated, patch files, scripts, and other
+ files created and contributed to the FreeBSD ports
+ collection are assumed to be covered by the standard BSD
+ copyright conditions.</para>
+ </note>
+ </sect1>
+
+ <sect1 xml:id="slow-patch">
+ <title xml:lang="en">Patching</title>
+
+ <para xml:lang="en">In the preparation of the port, files that have been added
+ or changed can be recorded with <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> for later feeding
+ to <citerefentry><refentrytitle>patch</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Doing this with a typical file involves
+ saving a copy of the original file before making any changes
+ using a <filename>.orig</filename> suffix.</para>
+
+ <screen><prompt>%</prompt> <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
+
+ <para xml:lang="en">After all changes have been made, <command>cd</command> back
+ to the port directory. Use <command>make makepatch</command> to
+ generate updated patch files in the <filename>files</filename>
+ directory.</para>
+
+ <sect2 xml:id="slow-patch-rules">
+ <title xml:lang="en">General Rules for Patching</title>
+
+ <para xml:lang="en">Patch files are stored in <varname>PATCHDIR</varname>,
+ usually <filename>files/</filename>, from where they will be
+ automatically applied. All patches must be relative to
+ <varname>WRKSRC</varname>. Typically
+ <varname>WRKSRC</varname> is a subdirectory of
+ <varname>WRKDIR</varname>, the directory where the distfile is
+ extracted. Use <command>make -V WRKSRC</command> to see the
+ actual path. The patch names are to follow these
+ rules:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para xml:lang="en">Avoid having more than one patch modify the same file.
+ For example, having both
+ <filename>patch-foobar.c</filename> and
+ <filename>patch-foobar.c2</filename> making changes to
+ <filename>${WRKSRC}/foobar.c</filename> makes them fragile
+ and difficult to debug.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">When creating names for patch files, replace each
+ underscore (<literal>_</literal>) with two underscores
+ (<literal>__</literal>) and each slash
+ (<literal>/</literal>) with one underscore
+ (<literal>_</literal>). For example, to patch a file
+ named <filename>src/freeglut_joystick.c</filename>, name
+ the corresponding patch
+ <filename>patch-src_freeglut__joystick.c</filename>. Do
+ not name patches like <filename>patch-aa</filename> or
+ <filename>patch-ab</filename>. Always use the path and
+ file name in patch names. Using <command>make
+ makepatch</command> automatically generates the correct
+ names.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">A patch may modify multiple files if the changes are
+ related and the patch is named appropriately. For
+ example,
+ <filename>patch-add-missing-stdlib.h</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para xml:lang="en">Only use characters <literal>[-+._a-zA-Z0-9]</literal>
+ for naming patches. In particular, <emphasis>do not use
+ <literal>::</literal> as a path separator,</emphasis>
+ use <literal>_</literal> instead.</para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para xml:lang="en">Minimize the amount of non-functional whitespace changes
+ in patches. It is common in the Open Source world for
+ projects to share large amounts of a code base, but obey
+ different style and indenting rules. When taking a working
+ piece of functionality from one project to fix similar areas
+ in another, please be careful: the resulting patch may be full
+ of non-functional changes. It not only increases the size of
+ the ports repository but makes it hard to find out what
+ exactly caused the problem and what was changed at all.</para>
+
+ <para xml:lang="en">If a file must be deleted, do it in the
+ <buildtarget xml:lang="en">post-extract</buildtarget> target rather than as
+ part of the patch.</para>
+
+ </sect2>
+
+ <sect2 xml:id="slow-patch-manual">
+ <title xml:lang="en">Manual Patch Generation</title>
+
+ <note>
+ <para xml:lang="en">Manual patch creation is usually not necessary.
+ Automatic patch generation as described earlier in this
+ section is the preferred method. However, manual patching
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"