On Thursday, January 30, 2014 5:46:18 PM UTC-5, Edward K. Ream wrote:
Note the date: several days ago. This is an ENB (Engineering Notebook)
post: feel free to ignore. Otoh, unlike most of the recent status reports,
I would appreciate any comments you may have.
> I think @auto should *always* add section reference comments. They can't
> happen "by accident" (when importing someone *else's* external file, so why
> not allow them when the Leo user is the one to change the external file?
> These *plain* section reference comments are indistinguishable from any
> other comments., so should be *completely* unobjectionable. This is *not*
> a case of making an "innocent" change to a file; it is a case of making an
> ordinary change to a file. It will be acceptable if and only if changes
> are acceptable in general.
>
I've been going round and around with this. This is a surprisingly tricky
question. Here are some thoughts, all inter-related.
1. The at-file-to-at-auto command allows section references in the @file
node, but it writes *no* identifying information. This seems a bit extreme
, but see below. Given a section references << x >> in the @file node, I
can see no reason why not to write a plain comment # x in the external file.
2. Otoh, I have been convinced, by Terry & Kent et. al., that @auto must
*never* change *existing* external files in any way. I take that as a
given, but again, things are not quite as simple as they seem.
3. In a collaborative environment a Leo user, (Len) may well have
*permission* to change an external files. I *don't* mean permission to add
Leo-centric comments, I simply mean permission to change the code.
Presumably, such permission includes permission to add comments, *provided*
the comments conform to the coding standards in effect for a project.
So here is a possible "loophole" (grey area) that depends on coding
standards and other "political" factors: is it possible to conceive of
Leo-centric comments that would be acceptable to the members of a
collaborative team? Before anyone objects, remember that I am *still* fully
aware of point 2 above!
The easy way is to say, no: point 2 will have no exceptions. End of
story. This will *always* be a real possibility. Otoh, as a thought
experiment, suppose some work groups will allow *very light* comments. For
section references: they would be *single* comments of the form: # << x
>> In other words, no closing comment would be allowed.
This instantly eliminates the possibility of nested section references: a
section *definition* would (necessarily) start at the comment line and
continue until the next node created by the *importer* (class or def node,
for Python). However, this would give me pretty much all I ever use these
days. A typical @auto node would start with something like this::
#!/usr/bin/env python
# -*- coding: utf-8 -*-
<< docstring >>
<< imports >>
<< data >>
.. the rest of the nodes, as created by the importer...
I could live with this!
**Warning**: there is a lot of hand-waving going on here: at present, the
importers create a single "declarations" node for everything before the
first class or def node. The "innocent" change illustrated above would
take a lot of work in *all* the importers (baseScannerClass code).
4. Point 3 illustrates what I have been thinking about lately, but really,
it seems dubious (not to mention difficult to do, in practice). Instead,
it might be easier to do in practice to have the importer code (the default
action of @auto parsing) parse the "declarations" node into constituents
automatically. This is what I intend to do first (if I ever get around to
it.) The advantage of this approach is that it avoids *all* questions about
what kind of comments may be acceptable. Len will write code as always
(without section references) and let others (and himself) deal with
whatever the importers give them.
5. Important: the reason these questions arise at all is that the new @auto
scheme can only attach organizer nodes to nodes that the @auto importers
have *already* created. Indeed, except for comment lines, the new @auto
scheme never changes or moves nodes: it *only* moves nodes to nodes that do
*not* contain @others! In other words, the new @auto scheme provides *no*
way (again, except for moving comments) to change any body text.
6. There is one more complication. Leo's html importer allows the user to
specify which html elements create outline nodes. At present, this applies
only to html/xml elements: @data import_html_tags and @data
import_xml_tags. However, we can imagine that certain kinds of <div>
elements creating outline nodes. In some situation, Len might have
permission to change the class of div elements, even though the actual
reason for doing so would be to create a more useful Leo outline. Again,
this is a grey area, but in this case the format of allowed comments plays
no part.
===== Summary
Although support for section references and definitions seems tempting, it
seems best to avoid lobbying for supposedly "innocent" Leonine comments.
That being so, the only obvious possible improvement would be to have the
importers divide "declarations" node into components. Not all importers
need support such "sophisticated" declarations. Initially, only the Python
importer might do so.
People with permission to change code might be able to influence the tree
created by @auto importers, say by changing or enhancing div types in html.
Such changes to code might be more acceptable in a work group than adding
Leonine comments. Or not.
All this is background at the moment. I wanted to write it down so I could
stop thinking about it and move on to more practical considerations.
All comments welcome.
Edward
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/groups/opt_out.
