Updates to the notes/dump-load-format.txt document

["Eric S. Raymond" <es...@thyrsus.com>]

This is a heads-up that because of my work on reposurgeon I have begun
doing some minor updates to notes/dump-load-format.txt to keep it
current with my understanding of Subversion's dump behavior. I expect
these to continue sporadically over the next month.

As usual, I do not contemplate making any code changes at all.

Should this material move to the design wiki?
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

The American Republic will endure, until politicians realize they can
bribe the people with their own money.
	-- Alexis de Tocqueville

Re: Updates to the notes/dump-load-format.txt document

[Julian Foad <ju...@apache.org>]

Eric S. Raymond wrote:
> This is a heads-up that because of my work on reposurgeon I have begun
> doing some minor updates to notes/dump-load-format.txt [...]

Thank you!  I invite you also to point out anything we might improve in 
the spec or implementation.

I committed some further tweaks in r1869964,
r1869965, r1869966; more comments below.

> Should this material move to the design wiki?

Short answer: I don't think so.

Longer answer:  Our current choice between Confluence and a text file in 
Subversion is far from ideal.  Ideally, factors such as presentation and 
editing would be handled by a wiki-like front end, and storage and 
authorization and change tracking handled by the version control system. 
  Currently that's not the case.  I would love to see moves toward that 
sort of configuration.

Factors relevant to this particular document include: it belongs fairly 
close to the code; it's good that it's version-controlled although 
logically it shouldn't be branched along with the code; its presentation 
could be improved, e.g. with markdown.  Overall, it seems best left 
where it is.  What factors had you in mind when asking?


 From the doc itself:
> === Unresolved questions ===
> 
> 1. In interpreting a Node record which has both a copyfrom source and
> a property section, it is possible that the copy source node itself
> has a property section.  How are they to be combined?

The text and properties of the copy source node are to be used in the 
same way that the contents of a previous node-revision at the same path 
are used when the current node record has no copyfrom source.

That is, specifically:  If a text section is present in the current 
(referencing) node record, it is to be applied as a delta or as a 
replacement (according to its kind) to the property section of the copy 
source.  If a property section is present in the current (referencing) 
node record, it is to be applied as a delta or as a replacement 
(according to its kind) to the property section of the copy source.

About properties versus text:  In general, node properties follow the 
same flow and persistence rules as node text.  We need a term that 
encompasses both text and properties.  I have been using "Content" for 
that in my writings, and that accords with headers like 
"Prop-content-length", "Text-content-length", "Content-length" (= 
Prop-content-length + Text-content-length).  However, in section "The 
kinds of things" the term "Content" is currently defined as what I call 
"text".

Can you see a way to resolving that?  (Have you settled very heavily in 
your own work on "Content" referring only to the "text" content but not 
the properties?)

The section "The kinds of operations" in particular could do with a 
substantial rewrite to clarify all this.  I could perhaps propose 
something, unless you want to.

- Julian