Cross file clones (was Re: My thoughts which you are free to ignore :-))
Matt Wilkie
> possible, that you make complete external files, rather than clones,
> to be the "units of sharing". That way there is only one copy of the
> data, so if you change that data outside of Leo all clones of (parts
> of) that data will be in synch the next time you open Leo.
>
> EKR
Oh.
I thought one of the major reasons for clones was to be able to
"boiler plate" common content across many files. Examples might
include copyright notices, written by _____, code functions that get
re-used a lot and so on.
Is this an incorrect, or at least inadvisable, use of clones?
--
-matt
Terry Brown
Matt Wilkie <map...@gmail.com> wrote:
> I thought one of the major reasons for clones was to be able to
> "boiler plate" common content across many files. Examples might
> include copyright notices, written by _____, code functions that get
> re-used a lot and so on.
>
> Is this an incorrect, or at least inadvisable, use of clones?
I think it's a use of clones that forces you to deal with rules about
what's safe and what's not safe which are easy to forget or get wrong.
This is the same point Edward hit on recently:
http://groups.google.com/group/leo-editor/msg/12b9531a9b3025bb
Most programming languages have import / include mechanisms for
referencing common code. Ditto document generation systems like LaTeX,
DocBook, and rst. There are numerous templating systems for handling
repetition in HTML and similar outputs. Those are safe, DRY compliant
ways of addressing these needs.
*But* they all require specific knowledge - by appearing to offer a
generic solution to these needs which works for multiple output types
(code, HTML, rst, etc.) Leo's clones are very appealing. However I
don't think (Edward?) that was what they were designed / intended for.
Rather, they're intended to provide views / collections / bookmarks of
currently interesting parts of files. Personally I think UNLs are a
safer way of doing that, but clones do it very nicely, as long as you
don't break the rules.
That's where I think these issues about what clones do is coming from.
Perhaps Leo could offer some kind of generic solution by providing some
sort of templating system which could be applied to any text file
output. But it would still require a distinction between source files
and output, or built, files. Kind of cross-file section references.
Cheers -Terry
HansBKK
> P.S. In your particular situation, I would suggest, if at all possible, that you make complete external files, rather than clones, to be the "units of sharing". That way there is only one copy of the data, so if you change that data outside of Leo all clones of (parts of) that data will be in synch the next time you open Leo.
Oh.
I thought one of the major reasons for clones was to be able to
"boiler plate" common content across many files. Examples might
include copyright notices, written by _____, code functions that get
re-used a lot and so on.Is this an incorrect, or at least inadvisable, use of clones?
I honestly think the lack of a clear statement on this topic in the docs is dangerous for relative newcomers to Leo and threatens its acceptance as a data-safe working environment.
I would **really** like for us to work together here to create a starting point for documenting this issue, so I've compiled a summary from my past notes as a general starting point
Note that all the below statements are based on my limited knowledge and my reading of some rather old threads, those with more knowledge **please** do correct any inaccuracies. Note also these statements should be taken to apply to recent versions of Leo only, and I've ordered them by simplicity/safety/my certainty:
--------------------
It's safe to allow clones to appear in multiple @ <file> branches as long as you make sure that one of the following is true
- you are doing all your editing within Leo
- you make sure that any given clone only appears in one @ <file> that imports (reads) changes made outside Leo
- note my SOP to ensure this is to
- use a designated "master" @thin or @shadow file to bring in any external changes
- all the other clone instances are @nosent or @asis, therefore export only (and treated as read-only outside Leo)
- you take into account the relative priority guidelines outlined by Ed
- @all vs (sections+@others)
- have the (only one) "master location" use sections+@others, the other instances must use @all
- position in the outline
- last @ <file> read (= lower in the outline) wins - you will get "Recovered nodes" showing the conflict/differences
- in-Leo-only clones (not included in an @ <file> ) will always lose to imported changes
--------------------
I'm pretty sure there isn't a safe way to clone the @ <file> node itself to different paths
Including a given clone multiple times within a single @ <file> tree is fine, but it only actually gets written more than once when using <<sections>>, not via multiple @others.
--------------------
References:
https://groups.google.com/d/msg/leo-editor/j7BOnRqCFcI/tyE_SvNwfHMJ
https://groups.google.com/forum/#!topic/leo-editor/Z6KJhGFtCck/discussion
Pretty old, not sure how much still applies probably best to *not* revive these zombies but continue the discussion here, using the above summary as a starting point:
https://groups.google.com/forum/#!topic/leo-editor/-DFuSJwHP2E/discussion
https://groups.google.com/d/msg/leo-editor/wulhmob-Ne4/k_lyAWIQPLQJ
Edward K. Ream
> I honestly think the lack of a clear statement on this topic in the docs is
> dangerous for relative newcomers to Leo and threatens its acceptance as a
> data-safe working environment.
Yes, some more words in the docs would be helpful, but the bottom line
is that we can't assume that people will read documentation. There is
no substitute for being aware of the multiple-update problem. I think
it's fair to assume that programmers are aware of that problem.
Edward
HansBKK
In this other related concurrent thread you also state:
> What we are seeing is the boundary between reasonable and unreasonable uses of cross-file clones. That boundary is not sharp: whether cross-file clones work depend on the overall workflow of the people using them.
I would argue we should at least attempt to spell out for Leo users (programmers or no) what those boundaries are, even if only by giving some examples of ones that should be OK vs those that are clearly not. This would form the basis for more precise understanding growing over time, and perhaps more elegant ways for Leo to guide the user to avoid problems.
IMO a better solution would be some type of mechanism in Leo that allowed the user to specify explicitly which branch of the outline should be considered the canonical one. An idea you floated in one of those historical threads, I think along these lines, was having some sort of "@master" directive, which I suppose would direct Leo's read logic to "save this for last", no matter the position in the outline or use of @all vs section+others.
Another approach might be a warning (or just informational) reminder in the log pane whenever Leo detects a new additional potentially-problematic cross-file clone - IOW one that doesn't follow the safe-SOP rules specified in the docs.
Both of these may be too difficult/complex to implement, just tossing ideas out there ATM. . .
Edward K. Ream
>> > I honestly think the lack of a clear statement on this topic in the docs dangerous for relative newcomers to Leo and threatens its acceptance as a data-safe working environment.
The post "All about clone conflicts" is my response. Imo, the only
thing dangerous about Leo is deliberately ignoring Leo's warnings.
> IMO a better solution would be some type of mechanism in Leo that allowed the user to specify explicitly which branch of the outline should be considered the canonical one.
As I said in "All about clone conflicts", this is never going to
happen. Leo's read code is already too complex. Trying to guess what
the user wants will make it much more complex, and therefore less
reliable and more difficult to explain.
Put it another way, there *already is* a way to specify explicitly
which branch of the outline is the "canonical" branch: it's the last
branch in the outline that contains the clone.
Edward
HansBKK
From Terry's related thread here
>> distinction between source files and output, or built, files.
@shadow/thin = input and output
@nosent/asis = output only
Once could say this method is relatively "explicit"
IMO the other two - location in the outline on the one hand, and read order priority of @all vs <<sections>>/@others on the other - are less so.
The fact that these procedures rely on the user understanding a relatively complex set of rules IMO works against data safety. Solutions based on these can easily become fragile due to human limitations, e.g. memory/brain farts; for myself, it's all too easy to forget *why* I put that branch at the bottom of my outline, and later on move it up higher by mistake.
I completely understand and accept that additional mechanisms for preventing data loss due to cross-file cloning aren't likely to appear anytime soon. However in the meantime I still maintain that this is still an important usability issue which requires addressing in a more visible and permanent location.
I would be happy to put some more work into summarizing the points outlined in these threads into a "next draft", and then another developer could technical-edit it and incorporate it into the official documentation.