Date: Fri, 7 Dec 2012 13:00:49 +0000 (UTC) From: Eitan Adler <eadler@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40293 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201212071300.qB7D0nRe098980@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: eadler Date: Fri Dec 7 13:00:49 2012 New Revision: 40293 URL: http://svnweb.freebsd.org/changeset/doc/40293 Log: Update and expand on the pkg-descr explanation in the porter's handbook. Submitted by: danfe Approved by: bcr (mentor) 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 Fri Dec 7 13:00:46 2012 (r40292) +++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Fri Dec 7 13:00:49 2012 (r40293) @@ -181,11 +181,32 @@ USE_IMAKE= yes <filename>README</filename> or manpage</emphasis>; too often they are not a concise description of the port or are in an awkward format (e.g., manpages have justified - spacing). If the ported software has an official WWW - homepage, you should list it here. Prefix - <emphasis>one</emphasis> of the websites with - <literal>WWW:</literal> so that automated tools will work - correctly.</para> + spacing, as it looks particularly bad with monospaced + fonts).</para> + </note> + + <para>Well-written description text should describe the port + completely enough that users would not have to consult its + documentation or visit its website to understand what does it + do, how it can be useful for them, what particularly nice + features (if any) does it have, etc. You might want to + mention certain requirements (e.g. the graphical toolkit), + heavy dependencies, runtime environment, or implementation + languages, to help users to decide if they want to install + this port or not.</para> + + <para>If the ported software has an official WWW homepage, it + should be listed here. 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 should be terminated with a + slash.</para> + + <note> + <para>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> <para>The following example shows how your
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201212071300.qB7D0nRe098980>