Ticket #5977: 0003-Update-documentation-of-the-package-db-flags.patch

File 0003-Update-documentation-of-the-package-db-flags.patch, 10.7 KB (added by pcapriotti, 3 years ago)
  • docs/users_guide/flags.xml

    From 2468136b1b578c14483ff06208c95cc0791aaff0 Mon Sep 17 00:00:00 2001
    From: Paolo Capriotti <[email protected]>
    Date: Fri, 4 May 2012 15:56:36 +0100
    Subject: [PATCH 3/3] Update documentation of the package db flags.
    
    ---
     docs/users_guide/flags.xml    |   32 +++++++++++--
     docs/users_guide/packages.xml |  106 +++++++++++++++++++++++++++++++----------
     docs/users_guide/runghc.xml   |    2 +-
     3 files changed, 109 insertions(+), 31 deletions(-)
    
    diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
    index 1d091d7..ac44c02 100644
    a b  
    594594            <entry>-</entry>
    595595          </row>
    596596          <row>
    597             <entry><option>-package-conf</option> <replaceable>file</replaceable></entry>
    598             <entry>Load more packages from <replaceable>file</replaceable></entry>
     597            <entry><option>-package-db</option> <replaceable>file</replaceable></entry>
     598            <entry>Add <replaceable>file</replaceable> to the package db stack.</entry>
    599599            <entry>static</entry>
    600600            <entry>-</entry>
    601601          </row>
    602602          <row>
    603             <entry><option>-no-user-package-conf</option></entry>
    604             <entry>Don't load the user's package config file.</entry>
     603            <entry><option>-clear-package-db</option></entry>
     604            <entry>Use an empty initial package db stack.</entry>
     605            <entry>static</entry>
     606            <entry>-</entry>
     607          </row>
     608          <row>
     609            <entry><option>-no-global-package-db</option></entry>
     610            <entry>Don't add the global db to the initial package db stack.</entry>
     611            <entry>static</entry>
     612            <entry>-</entry>
     613          </row>
     614          <row>
     615            <entry><option>-global-package-db</option></entry>
     616            <entry>Add the global package db to the stack.</entry>
     617            <entry>static</entry>
     618            <entry>-</entry>
     619          </row>
     620          <row>
     621            <entry><option>-no-user-package-db</option></entry>
     622            <entry>Don't add the user's package db to the initial package db stack.</entry>
     623            <entry>static</entry>
     624            <entry>-</entry>
     625          </row>
     626          <row>
     627            <entry><option>-user-package-db</option></entry>
     628            <entry>Add the user's package db to the stack.</entry>
    605629            <entry>static</entry>
    606630            <entry>-</entry>
    607631          </row>
  • docs/users_guide/packages.xml

    diff --git a/docs/users_guide/packages.xml b/docs/users_guide/packages.xml
    index 4a3e45f..8df8cb9 100644
    a b _ZCMain_main_closure 
    408408      see GHC's package table by running GHC with the <option>-v</option>
    409409      flag.</para>
    410410
    411     <para>Package databases may overlap: for example, packages in the
    412       user database will override (<emphasis>shadow</emphasis>) those
    413       of the same name and version in the global database.</para>
     411    <para>Package databases mayb overlap, and they are arranged in a stack
     412      structure. Packages closer to the top of the stack will override
     413      (<emphasis>shadow</emphasis>) those below them. By default, the stack
     414      contains just the global and the user's package databases, in that
     415      order.</para>
    414416
    415     <para>You can control the loading of package databases using the following
    416       GHC options:</para>
     417    <para>You can control GHC's package database stack using the following
     418      options:</para>
    417419
    418420    <variablelist>
    419421      <varlistentry>
    420422        <term>
    421           <option>-package-conf <replaceable>file</replaceable></option>
    422           <indexterm><primary><option>-package-conf</option></primary></indexterm>
     423          <option>-package-db <replaceable>file</replaceable></option>
     424          <indexterm><primary><option>-package-db</option></primary></indexterm>
    423425        </term>
    424426        <listitem>
    425           <para>Read in the package configuration file
    426             <replaceable>file</replaceable> in addition to the system
    427             default file and the user's local file.  Packages in additional
    428             files read this way will override those in the global and user
    429             databases.</para>
     427          <para>Add the package database <replaceable>file</replaceable> on top
     428            of the current stack. Packages in additional databases read this
     429            way will override those in the initial stack and those in
     430            previously specified databases.</para>
    430431        </listitem>
    431432      </varlistentry>
    432433
    433434      <varlistentry>
    434         <term><option>-no-user-package-conf</option>
    435           <indexterm><primary><option>-no-user-package-conf</option></primary>
     435        <term><option>-no-global-package-db</option>
     436          <indexterm><primary><option>-no-global-package-db</option></primary>
    436437          </indexterm>
    437438        </term>
    438439        <listitem>
    439           <para>Prevent loading of the user's local package database.</para>
     440          <para>Prevent loading of the global package database in the initial stack.</para>
     441        </listitem>
     442      </varlistentry>
     443
     444      <varlistentry>
     445        <term><option>-no-user-package-db</option>
     446          <indexterm><primary><option>-no-user-package-db</option></primary>
     447          </indexterm>
     448        </term>
     449        <listitem>
     450          <para>Prevent loading of the user's local package database in the initial stack.</para>
     451        </listitem>
     452      </varlistentry>
     453
     454      <varlistentry>
     455        <term><option>-clear-package-db</option>
     456          <indexterm><primary><option>-clear-package-db</option></primary>
     457          </indexterm>
     458        </term>
     459        <listitem>
     460          <para>Start with an empty initial package database stack. This option
     461            is equivalent to the combination of
     462            <literal>-no-global-package-db</literal> and
     463            <literal>-no-user-package-db.</literal></para>
     464        </listitem>
     465      </varlistentry>
     466
     467      <varlistentry>
     468        <term><option>-global-package-db</option>
     469          <indexterm><primary><option>-global-package-db</option></primary>
     470          </indexterm>
     471        </term>
     472        <listitem>
     473          <para>Add the global package database on top of the current stack.
     474            This option can be used after
     475            <literal>-no-global-package-db</literal> to specify the position in
     476            the stack where the global package database should be
     477            loaded.</para>
     478        </listitem>
     479      </varlistentry>
     480
     481      <varlistentry>
     482        <term><option>-user-package-db</option>
     483          <indexterm><primary><option>-user-package-db</option></primary>
     484          </indexterm>
     485        </term>
     486        <listitem>
     487          <para>Add the user's package database on top of the current stack.
     488            This option can be used after
     489            <literal>-no-user-package-db</literal> to specify the position in
     490            the stack where the user's package database should be
     491            loaded.</para>
    440492        </listitem>
    441493      </varlistentry>
    442494    </variablelist>
    _ZCMain_main_closure 
    456508        packages.</para>
    457509
    458510      <para>If <literal>GHC_PACKAGE_PATH</literal> ends in a separator, then
    459         the default user and system package databases are appended, in that
    460         order. e.g. to augment the usual set of packages with a database of
    461         your own, you could say (on Unix):
    462 <screen>
    463 $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
     511        the initial package database stack (by default, the user and global
     512        package databases, in that order) is appended. For example, to augment
     513        the usual set of packages with a database of your own, you could say
     514        (on Unix):
     515
     516        <screen> $ export GHC_PACKAGE_PATH=$HOME/.my-ghc-packages.conf:</screen>
     517
    464518        (use <literal>;</literal> instead of <literal>:</literal> on
    465519        Windows).</para>
    466520
    haskell98-1.0.1.0 
    601655      <literal>ghc-pkg</literal> knows about can be modified using the
    602656      <literal>GHC_PACKAGE_PATH</literal> environment variable (see <xref
    603657        linkend="ghc-package-path" />, and using
    604         <literal>--package-conf</literal> options on the
     658        <literal>--package-db</literal> options on the
    605659        <literal>ghc-pkg</literal> command line.</para>
    606660
    607661    <para>When asked to modify a database, <literal>ghc-pkg</literal> modifies
    608662      the global database by default.  Specifying <option>--user</option>
    609       causes it to act on the user database, or <option>--package-conf</option>
     663      causes it to act on the user database, or <option>--package-db</option>
    610664      can be used to act on another database entirely.  When multiple of these
    611665      options are given, the rightmost one is used as the database to act
    612666      upon.</para>
    haskell98-1.0.1.0 
    614668   <para>Commands that query the package database (list, latest,
    615669     describe, field, dot) operate on the list of databases specified by
    616670     the flags <option>--user</option>, <option>--global</option>, and
    617      <option>--package-conf</option>.  If none of these flags are
     671     <option>--package-db</option>.  If none of these flags are
    618672     given, the default is <option>--global</option>
    619673     <option>--user</option>.</para>
    620674
    ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf 
    888942          </indexterm>
    889943        </term>
    890944        <term>
    891           <option>-package-conf</option> <replaceable>file</replaceable>
    892           <indexterm><primary><option>-package-conf</option></primary>
     945          <option>-package-db</option> <replaceable>file</replaceable>
     946          <indexterm><primary><option>-package-db</option></primary>
    893947          </indexterm>
    894948        </term>
    895949        <listitem>
    ghc-pkg dot | tred | dot -Tpdf >pkgs.pdf 
    898952            also be the database modified by a <literal>register</literal>,
    899953            <literal>unregister</literal>, <literal>expose</literal> or
    900954            <literal>hide</literal> command, unless it is overridden by a later
    901             <option>--package-conf</option>, <option>--user</option> or
     955            <option>--package-db</option>, <option>--user</option> or
    902956            <option>--global</option> option.</para>
    903957        </listitem>
    904958      </varlistentry>
  • docs/users_guide/runghc.xml

    diff --git a/docs/users_guide/runghc.xml b/docs/users_guide/runghc.xml
    index 0681f00..7d61f83 100644
    a b runghc [runghc flags] [GHC flags] module [program args] 
    3232    with a dash then you need to prefix it with
    3333    <literal>--ghc-arg=</literal> or runghc will think that it is the
    3434    program to run, e.g.
    35     <literal>runghc -package-conf --ghc-arg=foo.conf Main.hs</literal>.
     35    <literal>runghc -package-db --ghc-arg=foo.conf Main.hs</literal>.
    3636    </para>
    3737
    3838  </sect1>