Implement DCW collections and allow full continent, country, and state names in -R -E

doc/rst/source/coast.rst

@@ -111,19 +111,22 @@ Optional Arguments
 
 .. _-E:
 
-**-E**\ *code1,code2,...*\ [**+l**\|\ **L**][**+c**\|\ **C**][**+g**\ *fill*][**+p**\ *pen*][**+z**]
+**-E**\ *code1,code2,...*\ [**+l**\|\ **L**\|\ **n**][**+c**\|\ **C**][**+g**\ *fill*][**+p**\ *pen*][**+z**]
     Select painting, clipping or dumping country polygons from the Digital Chart of the World.
     This is another dataset independent of GSHHG and hence the **-A** and **-D** options do not apply.
-    Append one or more comma-separated countries using the
-    `2-character ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_.
+    Append one or more comma-separated countries using either the
+    `2-character ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_
+    (e.g., NO for Norway) or the full country name (e.g., Norway).
     To select a state of a country (if available), append .state, e.g, US.TX for Texas.  To specify a
-    whole continent, prepend = to any of the continent codes AF (Africa),
-    AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania),
-    NA (North America), or SA (South America).  Append **+l** to
+    whole continent, prepend = to any of the continent codes AF (Africa), AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania),
+    NA (North America), or SA (South America), or spell out the full names.  To specify a collection or named region,
+    give either the code or the full name. Append **+l** to
     just list the countries and their codes [no data extraction or plotting takes place].
     Use **+L** to see states/territories for Argentina, Australia, Brazil, Canada, China, India, Russia and the US.
-    Finally, you can append **+l**\|\ **+L** to **-E**\ =\ *continent* or **-E**\ *code* to only list
+    You can append **+l**\|\ **+L** to **-E**\ =\ *continent* or **-E**\ *code* to only list
     countries in that continent or country; repeat if more than one continent or country is requested.
+    Finally, use **+n** to list the named collections or regions, and use **-E**\ *code* to only list
+    collections that contains the listed codes.  All names are case-insensitive.
     To set up clip paths based on your selection, append **+c** or **+C** for inside or outside (area between selection
     and the map boundary) clipping, respectively.  To plot instead,
     append **+p**\ *pen* to draw polygon outlines [no outline] and
@@ -271,6 +274,27 @@ Optional Arguments
 
 .. module_common_ends
 
+Notes
+-----
+
+The **-E** option can be expanded to take the user's own custom collections
+and named regions.  Users can create a dcw.conf file and place it in their
+GMT user directory (typically ~/.gmt).  The format of the file is the same
+as the dcw-collections.txt file distributed with DCW::
+
+    # Arbitrary comments and blank lines anywhere
+
+    # The France-Italian union (2042-45) of gallery example 34.
+    tag: FRIT Franco-Italian Union
+    list: FR,IT
+    # Stay away from those dangerous eels!
+    tag: SARG Sargasso Sea
+    region: 70W/40W/20N/35N
+
+Each *tag:* record must be immediately followed by either a *list:* or *region:* record.
+All tags should be at least 3 characters long. Either the *tag* or the *name* (if available)
+can be used to make selections in **-R** or **-E**.
+
 Examples
 --------
 

doc/rst/source/explain_-R.rst_

@@ -36,13 +36,16 @@ The **-R** option defines the map region or data domain of interest. It may be s
    the nature of the calling module, this mechanism will also set grid spacing and possibly the grid registration (see
    :ref:`cookbook/options:Grid registration: The **-r** option`\ ).
 
-#. **-R**\ *code1,code2,...*\ [**+e**\ \|\ **r**\ \|\ **R**\ *incs*]. This indirectly supplies the region by consulting
-   the DCW (Digital Chart of the World) database and derives the bounding regions for one or more countries given by
-   the codes. Simply append one or more comma-separated countries using the two-character
-   `ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_.
-   To select a state within a country (if available), append .state, e.g, US.TX for Texas. To specify a whole continent,
-   prepend **=** to any of the continent codes **AF** (Africa), **AN** (Antarctica), **AS** (Asia), **EU** (Europe),
-   **OC** (Oceania), **NA** (North America), or **SA** (South America). The following modifiers can be appended:
+#. **-R**\ *code1,code2,...*\ [**+e**\ \|\ **r**\ \|\ **R**\ *incs*]. This indirectly supplies the region by
+   consulting the DCW (Digital Chart of the World) database and derives the bounding regions for one or more
+   countries given by the codes. Simply append one or more comma-separated countries using either the two-character
+   `ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)>`_ (e.g., NO) or the full
+   country name (e.g., Norway). To select a state within a country (if available), append .state (e.g, US.TX),
+   or the full state name (e.g., Texas). To specify a whole continent, prepend **=** to any of the continent codes
+   **AF** (Africa), **AN** (Antarctica), **AS** (Asia), **EU** (Europe), **OC** (Oceania), **NA** (North America),
+   or **SA** (South America), or spell out the full continent name. Finally, append any collection abbreviations
+   or full names for the extent of the collection or named region. All names are case-insensitive.
+   The following modifiers can be appended:
 
    - **+r** to adjust the region boundaries to be multiples of the steps indicated by *inc*, *xinc*/*yinc*, or
      *winc*/*einc*/*sinc*/*ninc* [default is no adjustment]. For example, **-R**\ *FR*\ **+r**\ 1 will select the

doc/rst/source/explain_-Rgeo.rst_

@@ -18,11 +18,14 @@
 
     #. **-R**\ *code1,code2,...*\ [**+e**\ \|\ **r**\ \|\ **R**\ *incs*]. This indirectly supplies the region by
        consulting the DCW (Digital Chart of the World) database and derives the bounding regions for one or more
-       countries given by the codes. Simply append one or more comma-separated countries using the two-character
-       `ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)>`_. To select a state within a
-       country (if available), append .state, e.g, US.TX for Texas. To specify a whole continent, prepend **=** to any
-       of the continent codes **AF** (Africa), **AN** (Antarctica), **AS** (Asia), **EU** (Europe), **OC** (Oceania),
-       **NA** (North America), or **SA** (South America). The following modifiers can be appended:
+       countries given by the codes. Simply append one or more comma-separated countries using either the two-character
+       `ISO 3166-1 alpha-2 convention <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)>`_ (e.g., NO) or the full
+       country name (e.g., Norway). To select a state within a country (if available), append .state (e.g, US.TX),
+       or the full state name (e.g., Texas). To specify a whole continent, prepend **=** to any of the continent codes
+       **AF** (Africa), **AN** (Antarctica), **AS** (Asia), **EU** (Europe), **OC** (Oceania), **NA** (North America),
+       or **SA** (South America), or spell out the full continent name. Finally, append any collection abbreviations
+       or full names for the extent of the collection or named region. All names are case-insensitive.
+       The following modifiers can be appended:
 
         - **+r** to adjust the region boundaries to be multiples of the steps indicated by *inc*, *xinc*/*yinc*, or
           *winc*/*einc*/*sinc*/*ninc* [default is no adjustment]. For example, **-R**\ *FR*\ **+r**\ 1 will select the