Why I like clones
Edward K. Ream
Leo's clones are here to stay:
1. Unlike any conceivable kind of linking, clones allow me to gather
information together that I can browse *without* jumping around the
outline. The pattern is:
+ A view node (typically not cloned)
+ Notes (typically not cloned)
+ cloned node 1
+ cloned node 2
...
Unlike with bookmarks, selecting a node (or any of its descendants)
does not jump to another place in the outline.
As a variation on this pattern, I typically clone the root @file node
of any plugin that I work on. I then move the cloned node to the top
level of the outline. This allows me not to move the original @file
node, so the inner structure of leoPlugins.leo remains intact.
2. Outlines with clones are isomorphic with directed acyclic graphs
(DAGs).
Unlike with general graphs, each node in a DAGs has a natural set of
descendants. Imo, this property makes DAGs more interesting, in
general, than general graphs.
Edward
Terry Brown
"Edward K. Ream" <edre...@gmail.com> wrote:
> 1. Unlike any conceivable kind of linking, clones allow me to gather
> information together that I can browse *without* jumping around the
> outline.
This use of clones is very cool, *if* you're comfortable learning and
then remembering not to break the rules you need to follow for this to
be safe. I find leoTodo.txt or whatever it's called getting in my face
sometimes for reasons I don't follow when I'm editing Leo's source. I
know this is a cross-file issue. But if I correctly understand the
last-clone-read wins rule... ha, I was going to say, even moving a view
node below the @file node in the same outline where there's only one
derived file involved could cause problems, but perhaps not, given that
the last-clone-read wins rule reads derived files *after* the entire
outline, so view nodes below the @file node would be ok...?
> Unlike with general graphs, each node in a DAGs has a natural set of
> descendants. Imo, this property makes DAGs more interesting, in
> general, than general graphs.
As long as what you're trying to describe fits an descendant structured
model, not everything does.
I think it's ultimately a personal preference for cost / benefit
trade-off, safety and simplicity vs. utility. Clones are better than
anything else for constructing views, but not everyone considers the
increment in value equal to the increment in cost.
This is all really separate from the issue of people trying to use them
to generate content, where getting the rules right is more complicated.
Cheers -Terry
Seth Johnson
> On Wed, 18 Jan 2012 10:47:57 -0800 (PST)
> "Edward K. Ream" <edre...@gmail.com> wrote:
>
>> 1. Unlike any conceivable kind of linking, clones allow me to gather
>> information together that I can browse *without* jumping around the
>> outline.
>
> This use of clones is very cool, *if* you're comfortable learning and
> then remembering not to break the rules you need to follow for this to
> be safe.
Is it correct to say that you'll have no problems if you use the Leo
app and just freely and unthinkingly use clones in one Leo file? No
cross-file clones?
< SNIP >
>> Unlike with general graphs, each node in a DAGs has a natural set of
>> descendants. Imo, this property makes DAGs more interesting, in
>> general, than general graphs.
>
> As long as what you're trying to describe fits an descendant structured
> model, not everything does.
But an outline is a DAG. :-) I have found outlines a very useful
base assumption to work with. This assumption provides a foundation
that makes decisions about how things like clones work much easier
than general graphs do. I think they will help considerably in
modeling distributed and collaborative Leo (and versioning, for that
matter).
> I think it's ultimately a personal preference for cost / benefit
> trade-off, safety and simplicity vs. utility. Clones are better than
> anything else for constructing views, but not everyone considers the
> increment in value equal to the increment in cost.
>
> This is all really separate from the issue of people trying to use them
> to generate content, where getting the rules right is more complicated.
The generating content thing is in tension with the fact Leo is a tool
for working with external files for a particular kind of purpose:
editing code, which is linear and of a nature where things have their
(one) place. You're doing something wrong if you're creating external
code files that are designed to have many places update with the same
actual textual code, which you are aiming at changing in one location
and having multiple places in the external files update textually and
redundantly from that. Code isn't like that: you call a function that
resides in its one right place, and update that single instance of
that function, not replicate the text of that function all over.
I tend to think that you have to choose between having a particular
purpose in relationship to external files, or putting everything
inside the Leo outline (i.e., no more files, just one uniform
distributed format that serves in place of all files). People aren't
thinking about making a uniform kind of format like that (everything
inside the outline), so it's necessary to decide on the function in
relation to external files that Leo is designed for. Trying to take
the function Leo is designed for, and then add all sorts of other
things (templating, general graphs), is just going to make the problem
of keeping external files and the Leo outline in sync more complex,
and possibly create purposes that are at odds with each other or
otherwise impossible.
Seth
Seth Johnson
> On Wed, Jan 18, 2012 at 2:17 PM, Terry Brown <terry_...@yahoo.com> wrote:
>
> The generating content thing is in tension with the fact Leo is a tool
> for working with external files for a particular kind of purpose:
> editing code, which is linear and of a nature where things have their
> (one) place. You're doing something wrong if you're creating external
> code files that are designed to have many places update with the same
> actual textual code, which you are aiming at changing in one location
> and having multiple places in the external files update textually and
> redundantly from that. Code isn't like that: you call a function that
> resides in its one right place, and update that single instance of
> that function, not replicate the text of that function all over.
HTML is not "code" in this sense.
Seth
Terry Brown
Seth Johnson <seth.p....@gmail.com> wrote:
> Is it correct to say that you'll have no problems if you use the Leo
> app and just freely and unthinkingly use clones in one Leo file? No
> cross-file clones?
Can you restate the question? All clones live within a single Leo
file, cross-file clones occur between derived @<file>s within a single
Leo file.
> The generating content thing is in tension with the fact Leo is a tool
> for working with external files for a particular kind of purpose:
> editing code, which is linear and of a nature where things have their
> (one) place. You're doing something wrong if you're creating external
> code files that are designed to have many places update with the same
> actual textual code, which you are aiming at changing in one location
> and having multiple places in the external files update textually and
> redundantly from that. Code isn't like that: you call a function that
> resides in its one right place, and update that single instance of
> that function, not replicate the text of that function all over.
Leo's not intended to be limited to editing code. Personally I'm happy
using whatever code-domain specific solution is appropriate for
handling repetition, `import` in python, `.. include:` in rst, some
templating language for XML or text generation. But it seems like
people keep getting in to trouble trying to use clones to do that sort
of thing. Maybe the problem's not that big, the use-case is not that
common, but unfortunately it leads to "Leo ate my data" threads.
On top of which, given the way template systems like jinja and Genshi
work, I think they'd integrate into Leo in quite powerful ways. I've
actually used Genshi like that for making a website where a Leo node is
the template and its children are data for items which need to be
rendered in the template.
Maybe there's no way to stop people shooting themselves in the foot
with a tool as complex and versatile as Leo - I just think that with
clones they sometimes don't know the gun's loaded until it's too late.
Cheers -Terry
Seth Johnson
> On Wed, 18 Jan 2012 15:14:52 -0500
> Seth Johnson <seth.p....@gmail.com> wrote:
>
>> Is it correct to say that you'll have no problems if you use the Leo
>> app and just freely and unthinkingly use clones in one Leo file? No
>> cross-file clones?
>
> Can you restate the question? All clones live within a single Leo
> file, cross-file clones occur between derived @<file>s within a single
> Leo file.
First, I think you answered the question: no. But I'm still unclear
what a cross-file clone is. Is it a clone that's in the one leo file,
pointing at external file A, while within the @file branch for
external file B?
If that's the case, it strikes me that part of the problem is that --
I think -- the cross-file clone is already being treated like a
templating function -- isn't that what you'd mean by having a clone
for file A inside the @file branch for file B?
I think templating in that pattern is different from cloning in the
sense Edward uses them. One could have a rule that the app enforces,
keeping you from doing that (pasting a clone from one file under the
@file for another), and doing so would make perfect sense. Then the
business of templating can be treated and implemented as something
else, rather than something that just happens (suddenly doing
templating rather than just grouping clones for clarity) when you
create a cross-file clone.
But my point is that the concept of templating is fundamentally at
odds with maintaining a codebase. Therefore, if I'm getting what you
mean by cross-file clones, cross-file clones shouldn't automatically
do templating.
So while people may have gotten excited with the prospects of doing
cloning even across external files, there's a difference in function
that seems to have been implemented without recognizing it.
Seth
> Cheers -Terry
>
> --
> You received this message because you are subscribed to the Google Groups "leo-editor" group.
> To post to this group, send email to leo-e...@googlegroups.com.
> To unsubscribe from this group, send email to leo-editor+...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/leo-editor?hl=en.
>
Seth Johnson
>
> But my point is that the concept of templating is fundamentally at
> odds with maintaining a codebase. Therefore, if I'm getting what you
> mean by cross-file clones, cross-file clones shouldn't automatically
> do templating.
>
> So while people may have gotten excited with the prospects of doing
> cloning even across external files, there's a difference in function
> that seems to have been implemented without recognizing it.
You can group clones without regard for what external files they're
in, willy-nilly, so long as what you're doing is creating views into a
codebase, wherein files are maintained independently, and never making
one a clone within another (which is a different purpose).
True?
Then: make templating something different from clones under @file.
Indeed, it strikes me you don't want any clones under @file. But you
could implement, and handle distinctly, something like an @template
thingie, where you can paste any clones you please, and the purpose of
that is to make an external file built out of those pieces, which can
dynamically change. Plus, you can have a way of specifying the order
of priority processing issues (presently called "clone wars"), maybe a
variety of selectable algorithms, associated with @template branches.
Stabbing in the dark a bit here, because I am not sure I get the
cross-file clone thing, but if I'm right, aren't my inferences
correct?
Seth
Terry Brown
Seth Johnson <seth.p....@gmail.com> wrote:
> First, I think you answered the question: no. But I'm still unclear
> what a cross-file clone is. Is it a clone that's in the one leo file,
> pointing at external file A, while within the @file branch for
> external file B?
I was going to say it's a clone which occurs in two @<file> derived
files in the same Leo outline. But even occurring in only one @<file>
and somewhere else in the outline (but not in an @<file>) can create
confusion when the @<file> is modified externally. I suspect external
modification is the real bugbear here.
> If that's the case, it strikes me that part of the problem is that --
> I think -- the cross-file clone is already being treated like a
> templating function -- isn't that what you'd mean by having a clone
> for file A inside the @file branch for file B?
>
> I think templating in that pattern is different from cloning in the
> sense Edward uses them.
Exactly - Edward uses them for creating views, typically of code
although they could be views of other kinds of data. That's what I
think you're calling a codebase, although I think the term view is
better. But it seems like others are trying to use them to generate
output with repetitive elements, presumably because they're unaware of
more appropriate tools for doing that, and Leo's clones seem to offer a
solution to their problem.
In response to your other post, I think providing templating tools in
Leo would be a completely unrelated to clones. They'd be more like
section references which could refer to content in a much broader range
of places (vs. section references referring to content in the node's
children).
Cheers -Terry
Seth Johnson
> On Wed, 18 Jan 2012 17:00:32 -0500
> Seth Johnson <seth.p....@gmail.com> wrote:
>
>> First, I think you answered the question: no. But I'm still unclear
>> what a cross-file clone is. Is it a clone that's in the one leo file,
>> pointing at external file A, while within the @file branch for
>> external file B?
>
> I was going to say it's a clone which occurs in two @<file> derived
> files in the same Leo outline. But even occurring in only one @<file>
> and somewhere else in the outline (but not in an @<file>) can create
> confusion when the @<file> is modified externally. I suspect external
> modification is the real bugbear here.
Right. But what that means is templating -- producing an external
file made up of pieces of other files that can be changed dynamically.
At present, clones within @file branches are for that purpose.
That's different from maintaining a codebase, where you put functions
into specific files and that's the sort of structure you're building,
if you're using redundant code, you're doing macro expansion that
happens when you compile the code. You're not doing templating.
>> If that's the case, it strikes me that part of the problem is that --
>> I think -- the cross-file clone is already being treated like a
>> templating function -- isn't that what you'd mean by having a clone
>> for file A inside the @file branch for file B?
>>
>> I think templating in that pattern is different from cloning in the
>> sense Edward uses them.
>
> Exactly - Edward uses them for creating views, typically of code
> although they could be views of other kinds of data. That's what I
> think you're calling a codebase, although I think the term view is
> better. But it seems like others are trying to use them to generate
> output with repetitive elements, presumably because they're unaware of
> more appropriate tools for doing that, and Leo's clones seem to offer a
> solution to their problem.
I meant by codebase the collection of external files that you compile.
That doesn't use templating.
Edward doesn't do templating because he's maintaining code and
templating is not a useful function for that purpose. Views are more
useful in that case.
You use views because you're trying to look at the external file's
content in various ways, without changing the structure of the
external file except deliberately. You want to do that for code, and
for other kinds of data.
Templating, on the other hand, is about creating whole new files from
pieces of other files.
> In response to your other post, I think providing templating tools in
> Leo would be a completely unrelated to clones. They'd be more like
> section references which could refer to content in a much broader range
> of places (vs. section references referring to content in the node's
> children).
Okay, you could have it unrelated to clones, but it is also unrelated
to maintaining a codebase with @file branches.
I think templating should be done without using @file -- instead use a
special @template thingie for derived files that are going to be
produced by dynamically updated bits of text via clones or section
references. @file should be for derived files that don't use
dynamically updated bits from elsewhere, but just feed the Leo outline
so Leo can let you reorder their contents within Leo while letting Leo
keep the external file's actual structure in place.
@template would be for letting you arrange things in Leo, even across
files, and have that reflected in a new, hybrid derived file.
@file would not have clones under it within Leo, and would be for
derived files that just feed Leo so you can arrange things in Leo
without changing the structure of the external file unless you
specifically define the structure change. Of course, Leo
automatically produces that structure for certain kinds of codebases.
For code views in Leo, just plain headers with clones under them.
Seth
Seth Johnson
Revise above:
One uses views because one is trying to look at the external file's
content in various ways, without changing the structure of the
external file except deliberately. One wants to do that for code, and
for other kinds of data.
(eom)
Seth Johnson
> irritating minor clarification below
>
> On Wed, Jan 18, 2012 at 6:43 PM, Seth Johnson <seth.p....@gmail.com> wrote:
>> On Wed, Jan 18, 2012 at 5:57 PM, Terry Brown <terry_...@yahoo.com> wrote:
>>>
>>> I was going to say it's a clone which occurs in two @<file> derived
>>> files in the same Leo outline. But even occurring in only one @<file>
>>> and somewhere else in the outline (but not in an @<file>) can create
>>> confusion when the @<file> is modified externally. I suspect external
>>> modification is the real bugbear here.
I think external file modification will be far easier to work out once
templating and code maintenance are treated as separate functions,
that users clearly switch between.
(And this will make easier all the issues of collaboration and
versioning -- and potentially distribution -- that are also related to
the external file modification problem, even after you sort it out
just for the case of one local user, or some protocol among several
users)
(eom)
HansBKK
On Thursday, January 19, 2012 3:14:52 AM UTC+7, Differance wrote:
> Is it correct to say that you'll have no problems if you use the Leo app and just freely and unthinkingly use clones in one Leo file?
> But I'm still unclear what a cross-file clone is. Is it a clone that's in the one leo file, pointing at external file A, while within the @file branch for external file B?
Cross-file cloning to me is simply:
nodes appear in multiple branches that are part of imported @ <files>.
The term "derived" file is confusing to me - would it apply to @ <files> that are
- only generated/exported, or
- only read/imported, or
- only to those that can be updated either within Leo or externally (aka "two-way" files)?
AFAIK only the last two types cause potential problems, my solution being to ensure that each node only appears once in such an @ <file>, all other instances being export-only.
> You can group clones without regard for what external files they're in, willy-nilly, so long as what you're doing is creating views into a codebase, wherein files are maintained independently, and never making one a clone
within another (which is a different purpose). True?
HansBKK
The most significant advances in technology are rarely used by the audience for which they where originally intended, nor solely for their intended use. From a completely different context, but not so long ago:
On Wednesday, October 19, 2011 9:24:45 PM UTC+7, Edward K. Ream wrote:
> Here, I'll summarize, without explanation, what I think Leo is now, or
> soon will be:
> 1. A premier platform for scripting, programming and searching.
> 2. A completely flexible and arbitrarily expandable filing cabinet for all kinds of (text) data, and by reference, any kind of data.
> 3. A generator/creator of (text) data and documents of all kinds: including, but not limited to, programs, web sites, and .pdf, .html and .tex files.
> 4. A rendering engine for rST, html and svg and other graphics sources, as well as pictures, svg files and movies included by reference.
> 5. A platform for studying, manipulating and verifying complex data, especially computer programs.
====================
I hope to continue to use Leo for many of these purposes, and hope to be able to help make it easier for others to do the same, including those that are less able and eager to climb the relatively steep learning curve Leo currently presents.
HansBKK
> But it seems like others are trying to use them to generate output with
repetitive elements, presumably because they're unaware of more appropriate
tools for doing that, and Leo's clones seem to offer a solution to their
problem.
> If that's the case, it strikes me that part of the problem is that -- I
think -- the cross-file clone is already being treated like a templating
function -- isn't that what you'd mean by having a clone for file A inside
the @file branch for file B?
it strikes me you don't want any clones under @file. But you could
implement, and handle distinctly, something like an @template thingie, where
you can paste any clones you please, and the purpose of that is to make an
external file built out of those pieces, which can dynamically change. Plus,
you can have a way of specifying the order of priority processing issues
(presently called "clone wars"), maybe a variety of selectable algorithms,
associated with @template branches.
I'm not clear about just how generally the term "templating" applies to all non-coding use cases.
From my experience with HTML, it would refer to the repetitive "site chrome" elements wrapping around the variable content.
However say I'm using Leo to manage a large amount of content for a given topic domain, like an encyclopedia. A relatively small proportion of the content needs to be output in more than one place, e.g. an article on the Bangladeshi spotted deer should be available both in the "D" and the "B" volumes.
Is that templating? Certainly not related to programming, but IMO it's an appropriate use of cloning - as long as I am careful with my data (and Leo assists me as much as the developers think appropriate).
On Thursday, January 19, 2012 3:50:30 AM UTC+7, Terry wrote:
> Maybe there's no way to stop people shooting themselves in the foot
> with a tool as complex and versatile as Leo - I just think that with
> clones they sometimes don't know the gun's loaded until it's too late.
Seth Johnson
accomplished with "cross-file clones" -- clones within @file branches
-- from the code maintenance function. I recommend doing that by
keeping clones out of @file branches, and adding @template branches
where clones can be put.
Then the user would explicitly choose between 1) feeding Leo from an
external file by use of @file, letting Leo keep the structure of that
external file while letting you create views on it; and 2) creating
new external files out of pieces of other files by use of @template.
This also separates the two use cases explicitly with distinct @
branch types, making it easier to manage eternal files. It might
also, though I'm not sure, mitigate "clone wars" because
@template-created external files are separate from @file-maintained
external files, and @template branches might also let you select from
a number of different priority/reconciliation algorithms.
I'm not saying take away any functions from Leo, just distinguish the
function of templating to produce external files derived from other
external files, from the function of maintaining an external file that
isn't built from other files.
Seth
> --
> You received this message because you are subscribed to the Google Groups
> "leo-editor" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/leo-editor/-/4URS7xiyK60J.
Seth Johnson
> I'm not clear about just how generally the term "templating" applies to all
> non-coding use cases.
>
> From my experience with HTML, it would refer to the repetitive "site chrome"
> elements wrapping around the variable content.
>
> However say I'm using Leo to manage a large amount of content for a given
> topic domain, like an encyclopedia. A relatively small proportion of the
> content needs to be output in more than one place, e.g. an article on the
> Bangladeshi spotted deer should be available both in the "D" and the "B"
> volumes.
>
> Is that templating?
For an encyclopedia where articles are to be placed in more than one
external file (approximately one file per letter of the alphabet), the
model would be to put all articles for all volumes into one big
@file-managed external file, and then make each volume of the
encyclopedia a @template-produced external file.
Seth
> Certainly not related to programming, but IMO it's an
> appropriate use of cloning - as long as I am careful with my data (and Leo
> assists me as much as the developers think appropriate).
>
>
>
>
> On Thursday, January 19, 2012 3:50:30 AM UTC+7, Terry wrote:
>
>> Maybe there's no way to stop people shooting themselves in the foot
>> with a tool as complex and versatile as Leo - I just think that with
>> clones they sometimes don't know the gun's loaded until it's too late.
>
> Very well put. I recognize that it may be some time before Leo helps protect
> relatively inexperienced users from making clone-war mistakes. In the
> meantime I believe some additional clarity in the official docs will at
> least improve the odds they will be forewarned to tread carefully.
>
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "leo-editor" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/leo-editor/-/TJ9kxC7-tmQJ.
Seth Johnson
> On Thu, Jan 19, 2012 at 6:30 AM, HansBKK <han...@gmail.com> wrote:
>> I'm not clear about just how generally the term "templating" applies to all
>> non-coding use cases.
>>
>> From my experience with HTML, it would refer to the repetitive "site chrome"
>> elements wrapping around the variable content.
>>
>> However say I'm using Leo to manage a large amount of content for a given
>> topic domain, like an encyclopedia. A relatively small proportion of the
>> content needs to be output in more than one place, e.g. an article on the
>> Bangladeshi spotted deer should be available both in the "D" and the "B"
>> volumes.
>>
>> Is that templating?
>
>
> For an encyclopedia where articles are to be placed in more than one
> external file (approximately one file per letter of the alphabet), the
> model would be to put all articles for all volumes into one big
> @file-managed external file, and then make each volume of the
> encyclopedia a @template-produced external file.
And there's no reason you couldn't have several @file-managed "article
source" files, if one is too big. The @template-produced encyclopedia
volumes are created from cloned pieces of the @file-managed files.
Seth
Seth Johnson
>
>> Maybe there's no way to stop people shooting themselves in the foot
>> with a tool as complex and versatile as Leo - I just think that with
>> clones they sometimes don't know the gun's loaded until it's too late.
>
> Very well put. I recognize that it may be some time before Leo helps protect
> relatively inexperienced users from making clone-war mistakes. In the
> meantime I believe some additional clarity in the official docs will at
> least improve the odds they will be forewarned to tread carefully.
I suspect the problems derive from mixing functions. Putting clones
in @file branches is actually something fundamentally different. I
suspect this might resolve the clone wars, but it also should make it
possible for the app to not let users make mistakes -- no bullets nor
dangerous weapons, since clones aren't in @file branches, and are only
in @template branches.
Seth
Seth Johnson
. . . or in regular views, grouped under regular headers.
Seth
HansBKK
Edward K. Ream
> Is it correct to say that you'll have no problems if you use the Leo
> app and just freely and unthinkingly use clones in one Leo file? No
> cross-file clones?
Assuming you mean, no clones in @<file> nodes, the answer must be yes:
everything is safe.
Edward
Edward K. Ream
> You can group clones without regard for what external files they're
> in, willy-nilly, so long as what you're doing is creating views into a
> codebase, wherein files are maintained independently, and never making
> one a clone within another (which is a different purpose).
>
> True?
Almost. The pattern in leoPy.leo is safe: all views reside either in
leoProjects.txt, the *first* @<file> node in the outline, or in the
outline itself.
This will be safe, because if you modify any node in an external file,
that modification will "win": the value in the external file will
change the value in leoProjects.txt. Ditto for clones in leoPy.leo
itself, because Leo reads leoPy.leo before any @<file> node.
Edward
Seth Johnson
> On Thursday, January 19, 2012 6:37:49 PM UTC+7, Differance wrote:
>> My point is to distinguish the templating function that's currently
>> accomplished with "cross-file clones" -- clones within @file branches --
>> from the code maintenance function.
>
> I appreciate your attempting to clarify the distinction; my point was that
> the wide range of Leo use cases doesn't fit IMO to only those two categories
> (code maintenance vs templating). I gave another example use case - does
> that fit within the domain of "templating" AFAYC?
Yes. I explained that the encyclopedia's volumes would be templated.
But there certainly can be all sorts of other things Leo is used for.
What you're concerned about is unclear to me.
>> I recommend doing that by keeping clones out of @file branches, and adding
>> @template branches
> where clones can be put. Then the user would explicitly choose between 1)
> feeding Leo from an external file by use of @file, letting Leo keep the
> structure of that external file while letting you create views on it; and 2)
> creating new external files out of pieces of other files by use of
> @template.
>
>
> IMO the various @ <file> directives give several options for doing these and
> many other possibilities already. As long as you're only importing
> ("feeding") within a single branch (including @shadow as well as @file),
> you're free to create as many mashups as you like via @nosent or @asis
> without any danger of clone-war data loss.
My point is that you can distinguish when Leo is being used for
templating from when it isn't.
>> This also separates the two use cases explicitly with distinct @ branch
>> types, making it easier to manage eternal files. It might also, though I'm
>> not sure, mitigate "clone wars" because @template-created external files are
>> separate from @file-maintained external files, and @template branches might
>> also let you select from a number of different priority/reconciliation
>> algorithms.
>
>
> I'm simply questioning whether the idea/discussion of "templating" should
> necessarily be confabulated with reducing inadvertent data-loss due to
> clone-war issues.
So you can't tell me whether what I'm saying does that or not.
> On Thursday, January 19, 2012 6:53:45 PM UTC+7, Differance wrote:
>>> Is that templating?
>
>> For an encyclopedia where articles are to be placed in more than one
>> external file (approximately one file per letter of the alphabet), the
> model would be to put all articles for all volumes into one big
> @file-managed external file, and then make each volume of the
> encyclopedia a @template-produced external file.
>
> My current solution is to keep everything (snippets for later use, full
> articles in-process or ready-to-publish) in Leo itself, but to only have
> published content pushed out to @ <files>. Each article (in my example,
> "Deer" and "Bangladesh") is a separate file, with the "spotted deer" node
> cloned to be included in both, but via @nosent, with all edits to such files
> to be made within Leo only.
>
> To accommodate community editing, I'd have an "Animals" @shadow file, and
> the spotted deer node could be edited by me within Leo or by others in the
> external file, without danger of clone-war damage.
>
> I would of course need to ensure sufficiently frequent "sync'ing" between
> the two to reduce the chances of conflicts needing to be resolved, or
> perhaps move to a more granular node-grouping ("deer" or "Asian mammals").
>
>
>
>> . . . or in regular views, grouped under regular headers.
>
> At least AFAIK, regular views don't involve any clone-war issues at all.
Right. And they aren't templating either.
>> Putting clones in @file branches is actually something fundamentally
>> different.
>
> Sorry, I don't follow - different from what? This is the only area where
> clone wars are an issue (AFAIK)
Different from code maintenance for one file. Putting clones in @file
branches is about putting pieces of other files together to produce a
new hybrid file, or templating.
>> And there's no reason you couldn't have several @file-managed "article
>> source" files, if one is too big. The @template-produced encyclopedia
>> volumes are created from cloned pieces of the @file-managed files.
>
>> no bullets nor dangerous weapons, since clones aren't in @file branches,
>> and are only in @template branches.
>
>
> So far, substitude your "@file" for my "either @file or @shadow", and your
> @template for @nosent and I reckon we're both talking about pretty similar
> things?
Could be. I'm trying to see if the use case can be implemented by the
app in a way that doesn't require users to understand clone war
issues, that makes what's going on more transparent. My proposal is
that that might be accomplished by not mixing templating with @file
branches. It may be that the app would implement that and confusion
about clone wars, and requiring users to adhere to disciplined
practices to avoid shooting themselves in the foot, would go away. It
certainly seems to me to be inviting that to have the sort of thing
Edward values clones for, mixed in with templating in @file branches.
> IMO the idea of "templating" within Leo should be discussed independently of
> the specific issue of reducing clone-war dangers, as it seems even more
> complex to me and the connection between the two issues unclear.
It would be quite clear that @file isn't for templating if the app
prevented clones in @file branches. Even more so if there's a
separate place for templating that is labeled as such, where you can
put clones.
Seth
>> I'm not saying take away any functions from Leo, just distinguish the
>> function of templating to produce external files derived from other external
>> files, from the function of maintaining an external file that
> isn't built from other files.
>
> As a general concept, I would be very much in favor of a more explicit
> "controlling" directive. As I recently pointed out, Ed had at one point
> posited something along the lines of an "@master" possibility, but I believe
> his further consideration eliminates that particular train of thought.
>
> I've been thinking that Leo could check for nodes being cloned under more
> than one importing @ <file> branch (@nosents or @asis being no problem) and
> warning the user, but I believe Ed doesn't want to go there.
>
> to be continued, time to put my babes to bed. . .
>
> --
> You received this message because you are subscribed to the Google Groups
> "leo-editor" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/leo-editor/-/NH0uCaBW2QwJ.
Seth Johnson
Okay, so does enforcing that make clone wars clearer? Can the rules
that apparently users have to internalize and follow based on deep
understanding, rather than the app managing them, be implemented in a
way so the app does manage them and makes that unnecessary? Such as
by putting "cross-file clones" under a separate @template style
branch?
Seth
> Edward
>
> --
> You received this message because you are subscribed to the Google Groups "leo-editor" group.
Seth Johnson
Okay, if you have the druthers, consider my reply to your subsequent
message in relation to this. If views are disallowed within @file
branches, then users would not have to remember a pattern like this,
right? Here, perhaps the views you currently have in the first @file
node would be in a @template node, and either just the separation of
templating from @files might all by itself (miraculously if this were
true) eliminate the need for users to follow a protocol based on deep
understanding, or the @template node might have a feature where the
user has to designate how clone wars would be handled.
Seth
HansBKK
I gave another example use case - does
> that fit within the domain of "templating" AFAYC?
Yes. I explained that the encyclopedia's volumes would be templated.
But there certainly can be all sorts of other things Leo is used for.
What you're concerned about is unclear to me.
> I'm simply questioning whether the idea/discussion of "templating" should
> necessarily be confabulated with reducing inadvertent data-loss due to
> clone-war issues.
So you can't tell me whether what I'm saying does that or not.
Within the domain of
a. only generated/exported
b. only read/imported
c. only to those that can be updated either within Leo or externally (aka "two-way" files)?
I'm understanding your @template idea as fitting within "a". Is that correct?
My second concern is with what I believe to be an unnecessarily strict blanket rule
>> keeping clones out of @file branches
Can that need be made to fit within your @templating scheme?
I'm trying to see if the use case can be implemented by the app in a way that doesn't require users to understand clone war issues, that makes what's going on more transparent.
HansBKK
Almost. The pattern in leoPy.leo is safe: all views reside either in
leoProjects.txt, the *first* @<file> node in the outline, or in the
outline itself.This will be safe, because if you modify any node in an external file,
that modification will "win": the value in the external file will
change the value in leoProjects.txt. Ditto for clones in leoPy.leo
itself, because Leo reads leoPy.leo before any @<file> node.
My understanding was that position would ensure "lowest" priority, the *last* @<file> branch having the highest priority - is that accurate?
If so, is it acceptable to substitute "any but the last" rather than "first", to handle the case where there needs to be more than one importing @<file> branch (keeping to the rule that any given node is only in one of them).
Edward K. Ream
> Could you help me understand the significance of using the *first* @<file>?
>
> My understanding was that position would ensure "lowest" priority, the
> *last* @<file> branch having the highest priority - is that accurate?
Yes.
> If so, is it acceptable to substitute "any but the last" rather than
> "first", to handle the case where there needs to be more than one importing
> @<file> branch (keeping to the rule that any given node is only in one of
> them).
You can do anything that works :-) Keep in mind that what is actually
happening is simple:
1. Leo reads the .leo file first, then all @<file> nodes, in outline order.
2. Given point 1, the last clone that Leo reads "wins".
Edward
mdb
> > "first", to handle the case where there needs to be more than one importing
> > @<file> branch (keeping to the rule that any given node is only in one of
> > them).
>
> You can do anything that works :-) Keep in mind that what is actually
> happening is simple:
>
> 1. Leo reads the .leo file first, then all @<file> nodes, in outline order.
>
> 2. Given point 1, the last clone that Leo reads "wins".
>
> Edward
resolve_clones -- might help everyone.
But this might be end up too complicated and have greater potential to
break the file reading code
Instead, would it be possible to put all re-written nodes by a later
clone in their original form in a special part of the outline tree ?
and then anyone so motivated could write code to resolve as they see
fit or handle/move them by hand.
To make this work, the special nodes would need probably extra
attribute information such as file source, dates, and a link to the
'master' clone (last one read in).
Pardon if this idea has already been vetted and shot down in the clone
wars, or is already is basically in place. I recall seeing 'orphaned'
nodes in leo files I have created and read back in, but I tended to
ignore them (and fortunately they never came back to bite me, as far
as I recall).
Seth Johnson
> On Thursday, January 19, 2012 10:32:48 PM UTC+7, Differance wrote:
>> > I'm simply questioning whether the idea/discussion of "templating"
>> > should necessarily be confabulated with reducing inadvertent data-loss due to
>> > clone-war issues.
>> So you can't tell me whether what I'm saying does that or not.
>
>
> I believe it does, however within the context of reducing the danger of
> clone-war data loss I would argue for a more general formulation of
> "export-only" or "generating" where you use the term templating.
>
> Within the domain of
> a. only generated/exported
> b. only read/imported
> c. only to those that can be updated either within Leo or externally (aka
> "two-way" files)?
>
> I'm understanding your @template idea as fitting within "a". Is that
> correct?
The distinction I'm pointing to is between files that are being
dynamically created from parts of other files (templated), versus
files that are simply being maintained as individual files in
themselves (code being maintained). They could be imported or
exported. They could be two-way. Certainly @file files are two-way,
and would be in my scheme. I think I just assume two-way-ness as part
of the problem, and figure that making templating separate from
maintaining code in self-contained distinct files will make it easier
to do things like coming up with good ways to handle clone wars and,
later, collaboration and versioning, plus make it easier for users to
understand what's going on. They are two distinct functions, it seems
to me.
> My second concern is with what I believe to be an unnecessarily strict
> blanket rule
>
>
>> >> keeping clones out of @file branches
>
>
> When the "master source" file is externally modified, my use case
> specifically requires one (and only one) instance of the cloned nodes to
> remain in an @ <file> branch that allows importing - @shadow in the "b" case
> above, optionally @file when "c" is allowed.
>
> Can that need be made to fit within your @templating scheme?
It's not clear what purpose you're serving by that protocol. Can't
say. I would ask what files you're trying to put together out of
other files, and perhaps you'd have to have separate @file source
files. Maybe that's what you're talking about as a "master source"
file.
>> I'm trying to see if the use case can be implemented by the app in a way
>> that doesn't require users to understand clone war issues, that makes what's
>> going on more transparent.
>
> I'm 100% behind that as a general goal for improvement, with helping further
> that understanding via more clear documentation on the issue as an "in the
> meantime" stop-gap.
Maybe something will come of it . . .
Seth
HansBKK
> My second concern is with what I believe to be an unnecessarily strict blanket rule
>> >> keeping clones out of @file branches
>
> When the "master source" file is externally modified, my use case specifically requires one (and only one) instance of the cloned nodes to remain in an @ <file> branch that allows importing - @shadow in the "b" case above, optionally @file when "c" is allowed.
>
> Can that need be made to fit within your @templating scheme?It's not clear what purpose you're serving by that protocol.
perhaps you'd have to have separate @file source files. Maybe that's what you're talking about as a "master source" file.
I break these down into "snippets", "chunks" "objects" whatever you like, in Leo = nodes, and select/re-order them in another set of branches, along with my own original content. Some of these are into another set of files for which I am the editor/author. If I understand your thinking correctly, these would no longer be in @ <file> branches, but under a new type of @template directive.
My point is the safety-enforcement part of your scheme, in order to accommodate my example, would need to allow the original "master source" @ <file> branches to contain clones - but only one instance for any given node.
Your @template directives would need to allow for external modification (two-way import/export) as well, so my confusion is to how this concept in and of itself would simplify or make safer things regarding clone wars, as the fundamental problem would IMO remain.
Seth Johnson
> On Saturday, January 21, 2012 2:46:21 AM UTC+7, Differance wrote:
>>
>> > My second concern is with what I believe to be an unnecessarily strict
>> > blanket rule
>> >> >> keeping clones out of @file branches
>> >
>> > When the "master source" file is externally modified, my use case
>> > specifically requires one (and only one) instance of the cloned nodes to
>> > remain in an @ <file> branch that allows importing - @shadow in the "b" case
>> > above, optionally @file when "c" is allowed.
>> >
>> > Can that need be made to fit within your @templating scheme?
>>
>> It's not clear what purpose you're serving by that protocol.
>
> To me, the main topic - preventing data loss due to multi-file clones.
:-) I'm developing the original topic -- why Edward likes clones.
>> perhaps you'd have to have separate @file source files. Maybe that's
>> what you're talking about as a "master source" file.
>
> I have text - may be code, may be docs "fed" into Leo from external files
> maintained by others which I don't alter. These are my "master source"
> files, and if I understand your thinking correctly, would want to remain in
> @ <file> (@file or @shadow) branches.
>
> I break these down into "snippets", "chunks" "objects" whatever you like, in
> Leo = nodes, and select/re-order them in another set of branches, along with
> my own original content. Some of these are into another set of files for
> which I am the editor/author. If I understand your thinking correctly, these
> would no longer be in @ <file> branches, but under a new type of @template
> directive.
This part I think I follow, and seems to be right.
> My point is the safety-enforcement part of your scheme, in order to
> accommodate my example, would need to allow the original "master source" @
> <file> branches to contain clones - but only one instance for any given
> node.
This I don't get. I haven't said anything about safety enforcement,
first. If you're talking about clone wars, all I've said is that
clearing up functions (code maintenance/having leo maintain single
unitary files vs. templating) should help make things clearer for
clone wars, not that it would necessarily make things safer.
Why/what are you doing in your use case that calls for adding one
clone to the master source @file branches? You've described the
master source files, and your hybrid things which would be under
@template branches. But I don't see what you're doing that you want
to put clones under @file branches.
> Your @template directives would need to allow for external modification
> (two-way import/export) as well, so my confusion is to how this concept in
> and of itself would simplify or make safer things regarding clone wars, as
> the fundamental problem would IMO remain.
Chiefly it would separate two different functions. But it wouldn't
make things safer in and of itself. Trying to both do code maintenance
and do templating in the same kind of @ branch strikes me as a recipe
for confusion either in development or usage. Separating them should
make it easier to conceptualize how to handle external modification if
only by handling two types of external files distinctly.
But what your example case I don't get, plus what you're speaking of
as "the fundamental problem." If you're talking about data
safety/preventing data loss due to multi-file clones I'm not clear how
your example relates to that.
Seth
HansBKK
> To me, the main topic - preventing data loss due to multi-file clones.:-) I'm developing the original topic -- why Edward likes clones.
This I don't get. I haven't said anything about safety enforcement,
first. If you're talking about clone wars, all I've said is that
clearing up functions (code maintenance/having leo maintain single
unitary files vs. templating) should help make things clearer for
clone wars, not that it would necessarily make things safer.
Ah, sorry, my lizard-brain filtering things a bit too much - yes I was focusing on clone-wars.
Why/what are you doing in your use case that calls for adding one clone to the master source @file branches? You've described the master source files, and your hybrid things which would be under @template branches. But I don't see what you're doing that you want to put clones under @file branches.
I'm not "putting" clones there, but since they are exactly the same nodes as the other instances in my "templating branches" they are nonetheless clones - I certainly don't want them to be disconnected copies.
> Your @template directives would need to allow for external modification (two-way import/export) as well, so my confusion is to how this concept in and of itself would simplify or make safer things regarding clone wars, as the fundamental problem would IMO remain.
Chiefly it would separate two different functions. But it wouldn't make things safer in and of itself. Trying to both do code maintenance and do templating in the same kind of @ branch strikes me as a recipe for confusion either in development or usage. Separating them should make it easier to conceptualize how to handle external modification if only by handling two types of external files distinctly.
But what your example case I don't get, plus what you're speaking of as "the fundamental problem." If you're talking about data safety/preventing data loss due to multi-file clones I'm not clear how your example relates to that.
Yes, that is what I'm talking about - clone wars, data loss due to multi-file cloning. And (my interpretation of) the fundamental cause of that problem is having nodes cloned within multiple @ <file> branches where the possibility exists of that single node's data getting out of sync in multiple external files. My "SOP" solution is to ensure that Leo is only able to import from one of those external files, because my brain isn't able to remember/keep track where it is OK for me to edit and where not.
I now understand that your @template idea was not intended in and of itself to directly address this problem, and therefore the fact that I don't understand how it's supposed to work no longer matters (to me).
Thanks a lot for your patience, and my apologies to the extent I've wasted your time and list bandwidth. . .
Seth Johnson
> On Monday, January 23, 2012 3:25:21 PM UTC+7, Differance wrote:
>>
>> > To me, the main topic - preventing data loss due to multi-file clones.
>>
>> :-) I'm developing the original topic -- why Edward likes clones.
>>
>> This I don't get. I haven't said anything about safety enforcement,
>> first. If you're talking about clone wars, all I've said is that
>> clearing up functions (code maintenance/having leo maintain single
>> unitary files vs. templating) should help make things clearer for
>> clone wars, not that it would necessarily make things safer.
>
>
> Ah, sorry, my lizard-brain filtering things a bit too much - yes I was
> focusing on clone-wars.
>
>>
>> Why/what are you doing in your use case that calls for adding one clone to
>> the master source @file branches? You've described the master source files,
>> and your hybrid things which would be under @template branches. But I don't
>> see what you're doing that you want to put clones under @file branches.
>
> Aha, this may be the cause of some misunderstanding - remember since Leo
> went through the "one node" change, there is not internal distinction
> between any "original" or "master" instance, as far as the software is
> concerned they are all exactly the same node, just appearing under multiple
> parents.
>
> I'm not "putting" clones there, but since they are exactly the same nodes as
> the other instances in my "templating branches" they are nonetheless clones
> - I certainly don't want them to be disconnected copies.
It seems to me that you're emulating what I'm recommending, only I
have a functional definition of the single clone @file -- it's for one
unitary external file, not any hybrid external file. If the
distinction in functions I'm describing were implemented, you'd have
what you're trying to do and it would be an aspect of the app that
users would grasp based on the difference in function.
Some of the difference comes from the fact I was not starting from the
specific problem that a cloned node's data would be in multiple
external files that could be independently modified outside Leo. I
don't know how you do things so you ensure Leo only imports from one
of those external files, but my concept would turn it into a situation
where it naturally follows that the "source" @file file's version of
the node would override any such revisions in the various hybrid files
that use that same node. Users who modify a hybrid @template file are
always subject to being overridden automatically that way, and it
stands to reason that they would. Thus Leo just plays the role of
updating all dependent hybrid @template files to match the definitive
information in the source @file file.
Seth
HansBKK
It seems to me that you're emulating what I'm recommending, only I have a functional definition of the single clone @file -- it's for one unitary external file, not any hybrid external file. If the distinction in functions I'm describing were implemented, you'd have what you're trying to do and it would be an aspect of the app that users would grasp based on the difference in function.
Sorry if the below seems nit-picky, but just I'm trying further our mutual understanding via clarifying terminology.
I'm not sure about your "single" "unitary" qualifiers, since with all my projects, and most source code examples I've seen, one is usually dealing with a whole collection of files, often in a large hierarchy of folders. This is just as true for
And perhaps rather than "hybrid" your "templating" term is equivalent (more commonly here "generated" or "derived")? As opposed to my "master source" idea, which I guess is somewhat like the VCS meaning of an "external branch"?
The term "clone file" doesn't make sense to me, AFAIK it isn't ever safe to clone the actual @ <file> node, only its children.
I don't know how you do things so you ensure Leo only imports from one of those external files
Alternatives or additional safety practices, paraphrasing from Ed, hopefully accurately:
- only use <<sections>>+@others for the "master" @ <file> branch, use @all for the derived ones
- make sure your "master" is the lowest @ <file> in the Leo file
If the above is accurate, I believe it could serve as a starting point for a succinct summary to add to the official docs?
Feedback of course most welcome. . .
Matt Wilkie
> code files that are designed to have many places update with the same
> actual textual code, which you are aiming at changing in one location
> and having multiple places in the external files update textually and
> redundantly from that. Code isn't like that: you call a function that
> resides in its one right place, and update that single instance of
> that function, not replicate the text of that function all over.
The first time I ran into clone problems was when I duplicated a batch
file to two different file system locations. The first is within my
Code tree, which is under revision control, and thus vital. The second
is in a shared Bin directory in PATH, the place where the script is
actually *used*, and thus also vital.
If it were only one computer I could make z:\bin\foo.bat a simple
`@call c:\code\foo\foo.bat %*` and thereby sidestep the duplication
issue. I needed to make the .bat available to more than one computer
and b:\code is only there for me.
So now I have a third script, publish-foo.bat, which copies from code
to bin. This works and is safe, but has friction compared to the
stupendous aha's "edit, alt-f4, edit, alt-f4..." I was looking for.
So it's wrong in that DRY is violated, but I really don't see any
other way of doing it. (I'm not offering this as a complaint, just an
experience to contribute to the context.)
--
-matt
Seth Johnson
@file branch, but (in my concept) other instances would be under
@template nodes, even if they're the same file in terms of content.
Seth
HansBKK
> but I really don't see any other way of doing it.