Clarify documentation related to article file names, and documentation extension file names. (#874)

* Clarify documentation related to article file names, and documentation
extension file names.

* PR feedback: Rephrase and supplement documentation related to article
file names, and documentation extension file names.

Author: patshaughnessy

Sources/docc/DocCDocumentation.docc/adding-structure-to-your-documentation-pages.md

@@ -141,17 +141,36 @@ default organization and provide a more appropriate structure for your symbols.
 
 ![A screenshot showing the rendered documentation containing three topic groups: Creating a Sloth, Activities, and Schedule.](4_topics_2)
 
-To add an extension file to your documentation catalog for a specific symbol, use a text editor to create a new file named `Extension.md`.
+To add an extension file for a specific symbol, use a text editor to create an
+`.md` file within the documentation catalog. DocC ignores file names of
+documentation extensions; you can choose any file name you would like as long
+as it uses an `.md` extension. (DocC determines the URL path of source
+documentation from the symbol's name, type and parent type among other things.)
+Then open the file and add a level 1 header on the first line. Finally, set the
+level 1 header's title to be a link to the corresponding symbol.
 
-In the `Extension.md` file, replace the `Symbol` placeholder 
-with the symbol path of the symbol you're organizing and rename the file accordingly.
+Here's an example of a level 1 header set to be a symbol link:
 
 ```markdown
 # ``SlothCreator/Sloth``
 ```
 
-> Important: The symbol path for the page title of an extension file needs to start
-with the name of a top-level symbol or the name of the framework.
+> Note: If you're working in Xcode, you can select the documentation catalog in
+> the project navigator and run the "File -> New -> File From Template..." menu
+> command. Then click "Extension File" under the Documentation section. In the
+> new markdown file, replace the "Symbol" placeholder with a link to the
+> corresponding symbol, and rename the file accordingly.
+
+> Important:
+> If DocC can't resolve the symbol link in the level 1 header of the extension
+> file, it will raise a warning about the link and skip the rest of the content
+> of that extension file.
+>
+> DocC resolves symbol links in extension file headers relative to the module.
+> To create an extension file for a nested type or member symbol, start the
+> symbol link with the name of the top-level symbol that contains the nested
+> type or member symbol.  You can optionally prefix the symbol link with the
+> name of the module, but DocC does not require this prefix.
 
 The Extension File template includes a `Topics` section with a single named 
 group, ready for you to fill out. Alternatively, if your documentation catalog 

Sources/docc/DocCDocumentation.docc/adding-supplemental-content-to-a-documentation-catalog.md

@@ -62,7 +62,19 @@ habitat.
 ...
 ```
 
-To add an article to your documentation catalog, use a text editor and create a file with an appropriate title and add a `.md` extension.
+To add an article to your documentation catalog, use a text editor and create a
+file with an appropriate title and add an `.md` extension.
+
+> Important:
+> DocC uses the article's lowercased file name, with consecutive
+> sequences of whitespace and punctuation replaced with a hyphen (`-`), as a
+> path component in the URL for that page.
+>
+> If two or more articles have the same file name, DocC will raise a warning
+> and skip building documentation for all but one of those articles.
+>
+> DocC doesn't display the article file name in content. Instead, it uses the
+> title from the level 1 header in places where the article is referenced.
 
 After the Overview section, additional sections and subsections use a double
 hash (##) for a level 2 header, and a triple hash (###) for a level 3 header.
@@ -89,10 +101,26 @@ Although writing documentation comments in source files has many benefits, in so
 * When your source documentation comments focus on the implementation of your
   code, and aren't appropriate for external documentation
 
-To add an extension file to your documentation catalog, create a file within the documentation catalog, then modify the first line of the file to identify the symbol that the file relates to using a symbol link in a level 1 header. 
-For more information on linking to symbols, see <doc:linking-to-symbols-and-other-content>.
-
-> Important: The symbol path for the page title of an extension file need to start with the name of a top-level symbol or the name of the framework.
+To add an extension file to your documentation catalog, create a file within the
+documentation catalog, then modify the first line of the file to identify the
+symbol that the file relates to using a symbol link in a level 1 header. For
+more information on linking to symbols, see
+<doc:linking-to-symbols-and-other-content>.
+
+DocC ignores file names of documentation extensions; you can choose any file
+name you would like as long as it uses an `.md` extension. DocC determines the
+URL path of source documentation from the symbol's name, type and parent type
+among other things.
+
+> Important: If DocC can't resolve the symbol link in the level 1 header of the
+> extension file, it will raise a warning about the link and skip the rest of
+> the content of that extension file.
+>
+> DocC resolves symbol links in extension file headers relative to the module.
+> To create an extension file for a nested type or member symbol, start the
+> symbol link with the name of the top-level symbol that contains the nested
+> type or member symbol. You can optionally prefix the symbol link with the
+> name of the module, but DocC does not require this prefix.
 
 By default, the extension file's content adds to the symbol's existing source documentation comment. 
 You can leave key information in the documentation comment---where it's available to people reading the source code---and use the extension file for longer documentation, code examples, images, and for organizing you documentation hierarchy.