X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=docs%2Fusers_guide%2Fusing.xml;h=f769d287496cb9b623b5d31db182bd3149c15b8c;hb=3b5940fd32df31b56c1ab6891b0a8f338e796049;hp=439fb58c90b6ba96d19432e3d75b264d2e0c86bd;hpb=a078252410f284229e5f2440e7b8a9b32a6cfd33;p=ghc-hetmet.git

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 439fb58..f769d28 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -46,26 +46,25 @@ ghc [argument...]
 
       <para>Sometimes it is useful to make the connection between a
       source file and the command-line options it requires quite
-      tight. For instance, if a Haskell source file uses GHC
-      extensions, it will always need to be compiled with the
-      <option>-fglasgow-exts</option> option.  Rather than maintaining
+      tight. For instance, if a Haskell source file deliberately
+	uses name shadowing, it should be compiled with  the
+      <option>-fno-warn-name-shadowing</option> option.  Rather than maintaining
       the list of per-file options in a <filename>Makefile</filename>,
       it is possible to do this directly in the source file using the
       <literal>OPTIONS_GHC</literal> pragma <indexterm><primary>OPTIONS_GHC
       pragma</primary></indexterm>:</para>
 
 <programlisting>
-{-# OPTIONS_GHC -fglasgow-exts #-}
+{-# OPTIONS_GHC -fno-warn-name-shadowing #-}
 module X where
 ...
 </programlisting>
       
-      <para><literal>OPTIONS_GHC</literal> pragmas are only looked for at
-      the top of your source files, upto the first
-      (non-literate,non-empty) line not containing
-      <literal>OPTIONS_GHC</literal>. Multiple <literal>OPTIONS_GHC</literal>
-      pragmas are recognised.  Do not put comments before, or on the same line
-	as, the <literal>OPTIONS_GHC</literal> pragma.</para>
+      <para><literal>OPTIONS_GHC</literal> is a <emphasis>file-header pragma</emphasis>
+      (see <xref linkend="pragmas"/>).</para>
+
+      <para>Only <emphasis>dynamic</emphasis> flags can be used in an <literal>OPTIONS_GHC</literal> pragma
+      (see <xref linkend="static-dynamic-flags"/>).</para>
 
       <para>Note that your command shell does not
       get to the source file options, they are just included literally
@@ -919,6 +918,23 @@ ghc -c Foo.hs</screen>
     <variablelist>
 
       <varlistentry>
+	<term><option>-fwarn-unrecognised-pragmas</option>:</term>
+	<listitem>
+	  <indexterm><primary><option>-fwarn-unrecognised-pragmas</option></primary>
+	  </indexterm>
+	  <indexterm><primary>warnings</primary></indexterm>
+	  <indexterm><primary>pragmas</primary></indexterm>
+	  <para>Causes a warning to be emitted when a
+	  pragma that GHC doesn't recognise is used. As well as pragmas
+      that GHC itself uses, GHC also recognises pragmas known to be used
+      by other tools, e.g. <literal>OPTIONS_HUGS</literal> and
+      <literal>DERIVE</literal>.</para>
+
+	  <para>This option is on by default.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
 	<term><option>-fwarn-warnings-deprecations</option>:</term>
 	<listitem>
 	  <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
@@ -1818,7 +1834,7 @@ f "2"    = 2
 
       <variablelist>
 	<varlistentry>
-	  <term><option>-N<replaceable>x</replaceable></option></term>
+	  <term><option>-N<optional><replaceable>x</replaceable></optional></option></term>
 	  <listitem>
 	    <para><indexterm><primary><option>-N<replaceable>x</replaceable></option></primary><secondary>RTS option</secondary></indexterm>
 	      Use <replaceable>x</replaceable> simultaneous threads when
@@ -1830,9 +1846,19 @@ f "2"    = 2
 	      on a dual-core machine we would probably use
 	      <literal>+RTS -N2 -RTS</literal>.</para>
 	    
+            <para>Omitting <replaceable>x</replaceable>,
+              i.e. <literal>+RTS -N -RTS</literal>, lets the runtime
+              choose the value of <replaceable>x</replaceable> itself
+              based on how many processors are in your machine.</para>
+
+            <para>Be careful when using all the processors in your
+              machine: if some of your processors are in use by other
+              programs, this can actually harm performance rather than
+              improve it.</para>
+
             <para>Setting <option>-N</option> also has the effect of
-	      setting <option>-g</option> (the number of OS threads to
-	      use for garbage collection) to the same value.</para>
+              enabling the parallel garbage collector (see
+              <xref linkend="rts-options-gc" />).</para>
 
             <para>There is no means (currently) by which this value
 	      may vary after the program has started.</para>