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
