Changeset 129847 for trunk/doc-new


Ignore:
Timestamp:
Dec 21, 2014, 3:37:47 PM (4 years ago)
Author:
raimue@…
Message:

guide: Copy over some details from portstyle(7)

Clarify contradictions before getting rid of the man page.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc-new/guide/xml/portfiledev.xml

    r126075 r129847  
    55  <title>Portfile Development</title>
    66
    7   <para>This chapter covers a brief introduction to Portfiles, how to create a
    8   local Portfile repository for development, and creating Portfiles.</para>
     7  <para>A port is a distribution of software that can be compiled and
     8  installed using MacPorts. A <filename>Portfile</filename> describes all
     9  the required steps such as where to get the source code from upstream,
     10  which patches have to be applied and which other tools and commands are
     11  required to build the source code.</para>
     12
     13  <para>Each port consists of multiple files in a directory, usually within
     14  a category subdirectory of the root of a ports tree. The MacPorts
     15  Project distributes the main ports tree that is by default
     16  <link linkend="internals.configuration-files.sources-conf">configured</link>
     17  in all installations of MacPorts. This section serves as a reference for
     18  the directory structure of a single port and the layout of the files
     19  within. The only required file in a port is the
     20  <filename>Portfile</filename>.</para>
    921
    1022  <section id="development.introduction">
     
    794806      <title>Port Style</title>
    795807
    796       <para>Portfiles may be thought of as a table of keys and values in two
    797       columns separated by spaces (not tabs), so you should set your editor to
    798       use soft tabs, which are tabs emulated by spaces. By default, the top
    799       line of all Portfiles should use a modeline that defines soft tabs for
    800       the vim and emacs editors as shown.</para>
     808      <para>Portfiles may be thought of as a set of declarations rather than
     809      a piece of code. It is best to format the port file is if it were
     810      a table consisting of keys and values. In fact, the simplest of ports
     811      will only contain a small block of values. Nicely formatted compact
     812      tables will result in more values being visible at the same time.</para>
     813
     814      <para>The two columns should be separated by spaces (not tabs), so you
     815      should set your editor to use soft tabs, which are tabs emulated by
     816      spaces. By default, the top line of all Portfiles should use
     817      a modeline that defines soft tabs for the vim and emacs editors as shown.</para>
    801818
    802819      <programlisting># -*- coding: utf-8; mode: tcl; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:ft=tcl:et:sw=4:ts=4:sts=4</programlisting>
     
    808825      between words.</para>
    809826
    810       <programlisting>set libver "8.5"
    811 
    812 
    813 variant mysql5 { ... }</programlisting>
     827      <programlisting>set libver "8.5"</programlisting>
     828
     829      <para>When items require multiple lines with line continuation, they can
     830      be separated from the previous and next items with a blank line.
     831      Indent the additional lines to the same column that the right side
     832      begins on in the first line.</para>
     833
     834      <programlisting>checksums               rmd160  7bbfce4fecc2a8e1ca081169e70c1a298ab1b75a \
     835                        sha256  2829fcb7393bac85925090b286b1f9c3cd3fbbf8e7f35796ef4131322509aa53</programlisting>
     836     
     837      <para>Should a key item such as a phase or variant require braces, the
     838      opening brace should appear on the same line and the closing brace should
     839      be on its own line. The block formed by the braces is indented for visual
     840      clearance. Braces merely quoting strings, for example the description of
     841      variants, are placed on the same line without line breaks.</para>
     842
     843    <programlisting>variant mysql5 description {Enable support for MySQL 5} {
     844    depends_lib-append        port:mysql5
     845    configure.args-replace    --without-mysql5 --with-mysql5
     846}</programlisting>
    814847
    815848      <para>Frequently multiple items are necessary in the second column. For
Note: See TracChangeset for help on using the changeset viewer.