From 42dd557ba7f626a645aef6d62fd617580a9aac43 Mon Sep 17 00:00:00 2001
From: Glen Whitney <glen@studioinfinity.org>
Date: Fri, 12 Feb 2021 08:50:38 -0800
Subject: [PATCH] docs: Document quoted filename features

---
 mkdocs_semiliterate/plugin.py | 68 +++++++++++++++++++++++++++++------
 setup.cfg                     |  2 +-
 2 files changed, 58 insertions(+), 12 deletions(-)

diff --git a/mkdocs_semiliterate/plugin.py b/mkdocs_semiliterate/plugin.py
index 579a9c9..67d9bb8 100644
--- a/mkdocs_semiliterate/plugin.py
+++ b/mkdocs_semiliterate/plugin.py
@@ -112,6 +112,47 @@ is checked for `{! ... !}`.
             raise EOFError(errmsg)
         filename = body_match['fn']
         gitextract = False
+        dq_doc = """ md
+### Double-quoted filenames and Git extraction
+
+Standard Python escape sequences in double-quoted filenames are interpreted
+as usual; for example you can write
+```
+{! ../tests/fixtures/quoted-filename/README.md extract:
+  start: '(.*!.*)'
+  stop: '\s'
+!}
+```
+to include a file whose name (`snippet/Say "Don't"`, in this case) has both
+double and single quotes.
+
+Further, `semiliterate` supports a special escape to extract a file from the
+Git archive of the project (presuming it is under Git version control) and then
+include content from that file. For example, you could write
+```
+{! ../tests/fixtures/git-inclusion/README.md extract:
+  start: '(.*!.*)'
+  stop: '\s'
+!}
+```
+
+to extract content starting after the `### install` line from the
+`mkdocs.yml` file in the Git commit of this repository
+tagged `0.1.0`. This feature is primarily useful if you are documenting the
+development or changes to a project over time, and want to be sure that
+material included in your documentation does _not_ change as the project
+progresses. (This behavior is as opposed to the usual case, in which you want
+your documentation to incorporate the most up-to-date version of extracted
+content.)
+
+The precise behavior for a FILENAME argument in a `{! ... !}` inclusion of the
+form
+
+`"\git SPECIFIER"`
+
+is that the output of `git show SPECIFIER` is written to a temporary file,
+and that file is extracted from.
+"""
         if doublequoted:
             if filename[:5] == r'\git ':
                 gitextract = True
@@ -151,10 +192,23 @@ is checked for `{! ... !}`.
 class SemiliteratePlugin(SimplePlugin):
     r""" md   An extension of the mkdocs-simple-plugin
 
-In addition, block-comment markdown `/** md` ... `**/` is by
-default scanned for in all files with _any_ extension, as it's valid in so many
-disparate languages.
+### Universal block-comment markdown
 
+By default, `semiliterate` scans for block-comment markdown `/** md` ... `**/`
+in all files with _any_ extension, as it's valid in so many disparate languages.
+(As opposed to `simple`, which defaults to searching for such markdown in a
+specific list of file types.)
+    """
+
+    super_sdict = dict(SimplePlugin.config_scheme)
+    super_semi_dflt = super_sdict['semiliterate'].default
+    semi_dflt = [b if 'js' not in b['pattern'] else dict(b, pattern=r'\.')
+                 for b in super_semi_dflt]
+    altered_config_scheme = dict(
+        super_sdict,
+        semiliterate=config_options.Type(list, default=semi_dflt)).items()
+
+    add_param_doc = r""" md
 ### Additional plugin parameters
 
 `semiliterate` adds a couple of new plugin parameters to further tailor its
@@ -170,14 +224,6 @@ default values in parentheses at the beginning of each entry.
 terminate: '^\s*\)'
 !}
     """
-
-    super_sdict = dict(SimplePlugin.config_scheme)
-    super_semi_dflt = super_sdict['semiliterate'].default
-    semi_dflt = [b if 'js' not in b['pattern'] else dict(b, pattern=r'\.')
-                 for b in super_semi_dflt]
-    altered_config_scheme = dict(
-        super_sdict,
-        semiliterate=config_options.Type(list, default=semi_dflt)).items()
     config_scheme = (
         # Note documentation of each new parameter **follows** the parameter.
         *altered_config_scheme,
diff --git a/setup.cfg b/setup.cfg
index 99b4d31..fffab8d 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs-semiliterate
-version = 0.1.1
+version = 0.2.0
 description = Extension of mkdocs-simple-plugin adding easy content inclusion
 long_description = file: README.md
 long_description_content_type = text/markdown