Merge pull request #512 from gradha/pr_documents_gorgeous_pragmas

Documents passC/passL pragmas. Refs #506.

doc/advopt.txt

@@ -48,8 +48,8 @@ Advanced options:
   --cpu:SYMBOL              set the target processor (cross-compilation)
   --debuginfo               enables debug information
   --debugger:on|off         turn Embedded Nimrod Debugger on|off
-  -t, --passc:OPTION        pass an option to the C compiler
-  -l, --passl:OPTION        pass an option to the linker
+  -t, --passC:OPTION        pass an option to the C compiler
+  -l, --passL:OPTION        pass an option to the linker
   --cincludes:DIR           modify the C compiler header search path
   --clibdir:DIR             modify the linker library search path
   --clib:LIBNAME            link an additional C library

doc/nimrodc.txt

@@ -292,6 +292,35 @@ The `link`:idx: pragma can be used to link an additional file with the project:
   {.link: "myfile.o".}
 
 
+PassC pragma
+------------
+The `passC`:idx: pragma can be used to pass additional parameters to the C
+compiler like you would using the commandline switch ``--passC``:
+
+.. code-block:: Nimrod
+  {.passC: "-Wall -Werror".}
+
+Note that you can use ``gorge`` from the `system module <system.html>`_ to
+embed parameters from an external command at compile time:
+
+.. code-block:: Nimrod
+  {.passC: gorge("pkg-config --cflags sdl").}
+
+PassL pragma
+------------
+The `passL`:idx: pragma can be used to pass additional parameters to the linker
+like you would using the commandline switch ``--passL``:
+
+.. code-block:: Nimrod
+  {.passL: "-lSDLmain -lSDL".}
+
+Note that you can use ``gorge`` from the `system module <system.html>`_ to
+embed parameters from an external command at compile time:
+
+.. code-block:: Nimrod
+  {.passL: gorge("pkg-config --libs sdl").}
+
+
 Emit pragma
 -----------
 The `emit`:idx: pragma can be used to directly affect the output of the 

lib/system.nim

@@ -2392,8 +2392,10 @@ proc `[]=`*[T](s: var seq[T], x: TSlice[int], b: openArray[T]) =
     spliceImpl(s, a, L, b)
   
 proc slurp*(filename: string): string {.magic: "Slurp".}
+  ## This is an alias for ``staticRead``.
+
 proc staticRead*(filename: string): string {.magic: "Slurp".}
-  ## compile-time ``readFile`` proc for easy `resource`:idx: embedding:
+  ## Compile-time ``readFile`` proc for easy `resource`:idx: embedding:
   ##
   ## .. code-block:: nimrod
   ##     const myResource = staticRead"mydatafile.bin"
@@ -2402,9 +2404,11 @@ proc staticRead*(filename: string): string {.magic: "Slurp".}
 
 proc gorge*(command: string, input = ""): string {.
   magic: "StaticExec".} = nil
+  ## This is an alias for ``staticExec``.
+
 proc staticExec*(command: string, input = ""): string {.
   magic: "StaticExec".} = nil
-  ## executes an external process at compile-time.
+  ## Executes an external process at compile-time.
   ## if `input` is not an empty string, it will be passed as a standard input
   ## to the executed program.
   ##
@@ -2412,7 +2416,9 @@ proc staticExec*(command: string, input = ""): string {.
   ##     const buildInfo = "Revision " & staticExec("git rev-parse HEAD") & 
   ##                       "\nCompiled on " & staticExec("uname -v")
   ##
-  ## ``gorge`` is an alias for ``staticExec``.
+  ## ``gorge`` is an alias for ``staticExec``. Note that you can use this proc
+  ## inside a pragma like `passC <nimrodc.html#passc-pragma>`_ or `passL
+  ## <nimrodc.html#passl-pragma>`_.
 
 proc `+=`*[T: TOrdinal](x: var T, y: T) {.magic: "Inc", noSideEffect.}
   ## Increments an ordinal