Commits

larry committed 161638a

More cleanup for the notes.

Comments (0)

Files changed (1)

CLINIC.BUFFER.NOTES.TXT

 Notes on experimenting with Clinic with buffers.
 
+Larry Hastings
+larry@hastings.org
+2014-01-11
+
 ------------------------------------------------------------------------------
 
 This prototype isn't ready for check-in.  The "file" destination is a little
 
 ------------------------------------------------------------------------------
 
-There are three new "directives" for you to use.  Directives are like pragmas,
-they're special preprocessor-time live commands you can use in "clinic" clocks.
+There are three new "directives" for your use.  Directives are like Argument
+Clinic's pragmas--they're special preprocessor-time live commands you can use
+in "clinic" clocks.
+
 In this example:
     /*[clinic input]
     module os
     class foo
-    ...
+    [clinic start generated code]*/
 
 "module" and "class" are directives.
 
 ------------------------------------------------------------------------------
 
 The first new directive is "output":
+
     output <field> <destination>
+
 This lets you configure where Clinic writes a particular field.
 A "field" is a subsection of Clinic's output--more on those in
-a paragraph or two.  And "destination" is a place where you can
+a paragraph or two.  A "destination" is a place where you can
 send text.
 
 There are four built-in destinations:
+
     block
         Appends this field into the "output" area of the current block.
 
     buffer
-        Appends this field to the "buffer", a text buffer that you can
-        dump into the current file using another new directive.
+        Appends this field to the "buffer", a text buffer you can dump
+        into the current file using the "dump" directive (see below).
 
     side
         Appends this file to the "side file", a file that will be created
 ------------------------------------------------------------------------------
 
 The second new directive is "destination":
+
     destination <name> <command> [...]
 
 This performs an operation on the buffer with name "name".
 
 There are two defined commands: "new" and "clear".
 
-The "new" command looks like this:
+The "new" command works like this:
+
     destination <name> new <type>
+
 This creates a new destination with name "<name>" and type "<type>".
+
+
 There are four destination types:
-    "suppress" - throws the text away.
-    "block" - writes the text to the block.
-    "buffer" - a simple text buffer, like the "buffer" destination above.
-    "file" - a text file.  The file destination takes an extra argument,
+
+    suppress
+        Throws the text away.
+
+    block
+        Writes the text to the current block.  This is what Clinic
+        originally did.
+
+    buffer
+        A simple text buffer, like the "buffer" destination above.
+
+    file
+        A text file.  The file destination takes an extra argument,
         a template to use for building the filename, like so:
+
             destination <name> new <type> <file_template>
+
         The template can use three strings internally that will be replaced
         by bits of the filename:
-            {filename} - the full filename
-            {basename} - everything up to but not including the last '.'
-            {extension} - the last '.' and everything after it
-        (If there are no periods in the filename, {basename} and {filename}
+
+            {filename}
+                The full filename.
+            {basename}
+                Everything up to but not including the last '.'.
+            {extension}
+                The last '.' and everything after it.
+
+        If there are no periods in the filename, {basename} and {filename}
         are the same, and {extension} is empty.  "{basename}{extension}"
-        is always exactly the same as "{filename}".")
+        is always exactly the same as "{filename}"."
 
-The "clear" command looks like this:
+
+The "clear" command works like this:
+
     destination <name> clear
+
 It removes all the accumulated text up to this point in the destination.
+(I don't know what you'd need this for, but I thought maybe it'd be
+useful while someone's experimenting.)
 
 ------------------------------------------------------------------------------
 
 The third new directive is "dump":
+
     dump <name>
-This dumps out the current contents of the buffer by that name into the output
-section of the current clinic block.  This also empties the buffer.
+
+<name> should be the name of a "buffer" destination.  This dumps out the current
+contents of that buffer into the output of the current clinic block.  This also
+empties the buffer.
 
 If a buffer is not empty at the end of processing a file, Clinic will complain,
 and append a
 
 ------------------------------------------------------------------------------
 
-There have been a number of proposals on how to arrange the output.
-Here are the three I'm aware of, along with recipes on how you could
-produce it with this prototype.
+I'm aware of three proposals on how to change Clinic's output.  Here they are,
+along with recipes on how you could produce that output with this prototype.
 
 -----
 
 First, some people want to write everything to a separate file, which
-would presumably then be #included into the main file.  To try that,
-add this to the top of your file:
+would then be #included into the main file.  To do that, add this to
+the top of your file:
+
     /*[clinic input]
     output everything side
     output docstring_prototype suppress
     output impl_definition block
     [clinic start generated code]*/
 
-Then add
+Then add:
+
     #include "<basename>.side<extension>"
+
 somewhere near the top of the file.  For example, if you tried this
 with "posixmodule.c", you'd add
+
     #include "posixmodule.side.c"
+
 somewhere near the top of the file.
 
-Note that this is unlikely to happen, as Guido hates separate output
+
+This approach is unlikely to happen, as Guido hates separate output
 files like this.
 
 -----
 
     static PyMethodDef posix_methods[] = {
 
+
 This approach won't work on every file, because some files files have
 methoddef structures in the middle of the file, and I believe some files
 reuse parser functions.
 -----
 
 Third, here's my alternate take on buffering up all the output.
+It's the same as the "Second" approach above, except the clinic
+blob is altered as follows:
 
     /*[clinic input]
     output everything buffer
     output impl_definition block
     [clinic start generated code]*/
 
+
 This should work for every file.
+
+-----
+
+Personally I don't care if any or none of the above are selected.
+I just want the Python core dev community to be happy, and to enjoy
+working with Argument Clinic.  It's my hope we can find some mutually
+equitable resolution to this debate.