From 8135b67dc91654578012570ae741f145056d2749 Mon Sep 17 00:00:00 2001 From: Ben Albrecht Date: Sat, 13 Feb 2016 11:46:23 -0800 Subject: [PATCH 1/3] Mention man page in compiling.rst, formatting, & Sphinx 1.3.5 compat. --- doc/release/compiling.rst | 39 +++++++++++++----------- doc/release/technotes/dsi.rst | 7 +++-- doc/release/technotes/subquery.rst | 11 ++++--- doc/sphinx/source/language/evolution.rst | 3 +- doc/sphinx/source/usingchapel/index.rst | 2 +- 5 files changed, 36 insertions(+), 26 deletions(-) diff --git a/doc/release/compiling.rst b/doc/release/compiling.rst index b29effea5f4f..13800b88a630 100644 --- a/doc/release/compiling.rst +++ b/doc/release/compiling.rst @@ -33,7 +33,8 @@ variables are listed by the ``--help-env`` option. The flags' current settings are listed by ``--help-settings``. More detailed information about the compiler and its command-line -flags is also available on its man page, which you can read using: +flags is also available on its :any:`man page `, which can be viewed from +the command-line using: .. code-block:: sh @@ -46,33 +47,37 @@ Most Useful Flags We note some of the most useful flags here: - -o specify the filename of the generated +===================== ====================================================== +Flags Description +--------------------- ------------------------------------------------------ +``-o `` specify the filename of the generated executable, otherwise ./a.out is used by default - --no-checks turns off runtime semantic checks like bounds +``--no-checks`` turns off runtime semantic checks like bounds checking and nil class instance dereferencing - -O turns on optimization of the generated C code - --fast turns on ``--no-checks``, ``-O``, and enables +``-O`` turns on optimization of the generated C code +``--fast`` turns on ``--no-checks``, ``-O``, and enables many other optimizations - --savec saves the generated C code in the specified +``--savec `` saves the generated C code in the specified directory - -g support debugging of the generated C code - --ccflags specify flags that should be used when invoking +``-g`` support debugging of the generated C code +``--ccflags `` specify flags that should be used when invoking the back-end C compiler - --ldflags specify flags that should be used when invoking +``--ldflags `` specify flags that should be used when invoking the back-end linker - -s set a config variable with the given expression +``-s `` set a config variable with the given expression as its default value (config params must be set to values that are known at compile time) - --print-passes print the compiler passes as they execute - --print-commands print the system commands that the compiler +``--print-passes`` print the compiler passes as they execute +``--print-commands`` print the system commands that the compiler executes - --print-code-size prints some code size statistics about the +``--print-code-size`` prints some code size statistics about the number of lexical tokens per line, as well as the number of code, comment, and blank lines - --version print the Chapel compiler version number - --help print a brief overview of the command-line +``--version`` print the Chapel compiler version number +``--help`` print a brief overview of the command-line options - --help-env lists the environment variables for each +``--help-env`` lists the environment variables for each command-line flag - --help-settings lists the current setting of each command-line +``--help-settings`` lists the current setting of each command-line flag +===================== ====================================================== diff --git a/doc/release/technotes/dsi.rst b/doc/release/technotes/dsi.rst index aa81a60fbed8..fed7ba49f45c 100644 --- a/doc/release/technotes/dsi.rst +++ b/doc/release/technotes/dsi.rst @@ -767,6 +767,7 @@ class that chooses to support privatization. Returns `true` to indicate that privatization is supported. NOTE: do not specify the return type (due to a bug in the compiler). + .. code-block:: chapel class Global ... { @@ -775,9 +776,9 @@ class that chooses to support privatization. ... } - The field ``pid`` should be provided as shown. - It should not be accessed by the DSI implementation except - in conjunction with ``chpl_getPrivatizedCopy()`` as discussed later. +The field ``pid`` should be provided as shown. +It should not be accessed by the DSI implementation except +in conjunction with ``chpl_getPrivatizedCopy()`` as discussed later. .. method:: proc Global.dsiGetPrivatizeData() diff --git a/doc/release/technotes/subquery.rst b/doc/release/technotes/subquery.rst index ac9c10287824..c1e69762730d 100644 --- a/doc/release/technotes/subquery.rst +++ b/doc/release/technotes/subquery.rst @@ -19,7 +19,8 @@ Functions Supported on All Array Types hasSingleLocalSubdomain ----------------------- -.. code-block:: chapel +.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ +.. code-block:: text proc [].hasSingleLocalSubdomain() : bool; @@ -43,7 +44,8 @@ function named 'dsiHasSingleLocalSubdomain'. localSubdomain -------------- -.. code-block:: chapel +.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ +.. code-block:: text proc [].localSubdomain() : domain; @@ -74,7 +76,7 @@ If the locale's index set can be represented by a single domain, then the result of ``localSubdomain`` is yielded. Currently, this is a serial iterator. - + To support this iterator on a custom distributed array type, write an iterator named 'dsiLocalSubdomains'. @@ -87,7 +89,8 @@ Calling them on a non-distributed array will result in a compiler error. targetLocales ------------- -.. code-block:: chapel +.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ +.. code-block:: text proc [].targetLocales() : [] locale; diff --git a/doc/sphinx/source/language/evolution.rst b/doc/sphinx/source/language/evolution.rst index 464e29fc0e8f..f06322c7cb97 100644 --- a/doc/sphinx/source/language/evolution.rst +++ b/doc/sphinx/source/language/evolution.rst @@ -306,7 +306,8 @@ Emacs users working on updating existing code can use the following recipe to update old-style domain literals to the new syntax: -.. code-block:: chapel +.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ +.. code-block:: text M-x query-replace-regexp: \([=|,] *\)\[\(.*?\)\]\([;|)]\) with: \1{\2}\3 diff --git a/doc/sphinx/source/usingchapel/index.rst b/doc/sphinx/source/usingchapel/index.rst index d6a649dfc61e..37acd03bad6a 100644 --- a/doc/sphinx/source/usingchapel/index.rst +++ b/doc/sphinx/source/usingchapel/index.rst @@ -13,10 +13,10 @@ Contents: chplenv building compiling + Chapel Man Page executing multilocale launcher tasks debugging bugs - Man Page From f77655a96c2420ad91dd3551a6bbcc0422dc572c Mon Sep 17 00:00:00 2001 From: Ben Albrecht Date: Fri, 19 Feb 2016 17:21:27 -0800 Subject: [PATCH 2/3] Restored peace in the land of pygments highlighting --- doc/release/technotes/subquery.rst | 18 +++++++++--------- doc/sphinx/source/language/evolution.rst | 1 - 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/doc/release/technotes/subquery.rst b/doc/release/technotes/subquery.rst index c1e69762730d..db27e1eb5afa 100644 --- a/doc/release/technotes/subquery.rst +++ b/doc/release/technotes/subquery.rst @@ -19,10 +19,10 @@ Functions Supported on All Array Types hasSingleLocalSubdomain ----------------------- -.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ -.. code-block:: text +.. code-block:: chapel - proc [].hasSingleLocalSubdomain() : bool; + // A is an array + proc A.hasSingleLocalSubdomain() : bool; This is a param function which returns a boolean. If true, then the index set owned by a locale can be represented by a single domain. @@ -44,10 +44,10 @@ function named 'dsiHasSingleLocalSubdomain'. localSubdomain -------------- -.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ -.. code-block:: text +.. code-block:: chapel - proc [].localSubdomain() : domain; + // A is an array + proc A.localSubdomain() : domain; This function only operates on arrays whose 'hasSingleLocalSubdomain()' result is true. Otherwise, a compiler error is thrown. @@ -89,10 +89,10 @@ Calling them on a non-distributed array will result in a compiler error. targetLocales ------------- -.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ -.. code-block:: text +.. code-block:: chapel - proc [].targetLocales() : [] locale; + // A is an array + proc A.targetLocales() : [] locale; This function returns an array of locales that the distribution uses as the locale grid. diff --git a/doc/sphinx/source/language/evolution.rst b/doc/sphinx/source/language/evolution.rst index f06322c7cb97..138182e54b5d 100644 --- a/doc/sphinx/source/language/evolution.rst +++ b/doc/sphinx/source/language/evolution.rst @@ -306,7 +306,6 @@ Emacs users working on updating existing code can use the following recipe to update old-style domain literals to the new syntax: -.. SyntaxError in Pygments, throws warning in Sphinx 1.3.5+ .. code-block:: text M-x query-replace-regexp: \([=|,] *\)\[\(.*?\)\]\([;|)]\) From 9149b398f0c3e0c01f8b0c8ff5287b0161a1626c Mon Sep 17 00:00:00 2001 From: Ben Albrecht Date: Fri, 19 Feb 2016 17:36:41 -0800 Subject: [PATCH 3/3] array-type more clear --- doc/release/technotes/subquery.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/doc/release/technotes/subquery.rst b/doc/release/technotes/subquery.rst index db27e1eb5afa..d7725056b1c4 100644 --- a/doc/release/technotes/subquery.rst +++ b/doc/release/technotes/subquery.rst @@ -21,8 +21,7 @@ hasSingleLocalSubdomain .. code-block:: chapel - // A is an array - proc A.hasSingleLocalSubdomain() : bool; + proc array.hasSingleLocalSubdomain() : bool; This is a param function which returns a boolean. If true, then the index set owned by a locale can be represented by a single domain. @@ -46,8 +45,7 @@ localSubdomain .. code-block:: chapel - // A is an array - proc A.localSubdomain() : domain; + proc array.localSubdomain() : domain; This function only operates on arrays whose 'hasSingleLocalSubdomain()' result is true. Otherwise, a compiler error is thrown. @@ -67,7 +65,7 @@ localSubdomains .. code-block:: chapel - iter [].localSubdomains() : domain; + iter array.localSubdomains() : domain; This iterator yields the subdomain(s) that represent the index set owned by the current locale. @@ -91,8 +89,7 @@ targetLocales .. code-block:: chapel - // A is an array - proc A.targetLocales() : [] locale; + proc array.targetLocales() : [] locale; This function returns an array of locales that the distribution uses as the locale grid.