Re: [PATCHv2] Add details about svn-fe's dumpfile parsing
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:53:36
Andrew Sayers [off-list ref] writes:
The documentation for the SVN dumpfile format says that "property key/value pairs may be interpreted as binary data in any encoding by client tools". Documenting svn-fe's interpretation helps authors of related tools, while explaining limitations helps ordinary users import their SVN repositories. The "INPUT FORMAT" section is aimed at authors of tools that interact with svn-fe, so it particularly addresses assumptions that authors might make after dealing with svn itself. The "BUGS" section is aimed at ordinary users, so it only explains what readers need to know when importing a repository. In particular, users don't need to know that other characters in the range 0x01-0x1F are imported correctly, even though they were all disabled in Subversion 1.2.0. The text in this section is based largely on an example sent by Jonathan Nieder, with minor changes to suit the surrounding style. Signed-off-by: Andrew Sayers <redacted> ---
OK, so is this ready for 'master' already?
quoted hunk
contrib/svn-fe/svn-fe.txt | 13 +++++++++++++ 1 files changed, 13 insertions(+), 0 deletions(-)diff --git a/contrib/svn-fe/svn-fe.txt b/contrib/svn-fe/svn-fe.txt index 1128ab2..3872b9d 100644 --- a/contrib/svn-fe/svn-fe.txt +++ b/contrib/svn-fe/svn-fe.txt@@ -32,6 +32,13 @@ Subversion's repository dump format is documented in full in Files in this format can be generated using the 'svnadmin dump' or 'svk admin dump' command. +Unlike Subversion, 'svn-fe' interprets property key/value pairs as +null-terminated binary strings. This means it will accept content +that Subversion normally wouldn't produce (such as filenames +containing tab characters) or would refuse to parse (such as usernames +containing Latin-1 characters). However, like Subversion it will +handle newlines incorrectly in filenames (see BUGS below). +
Do the first two sentences in the above paragraph claim that it a bug that 'svn-fe' does not mimick what Subversion does? I am not sure what lessons the authors of tools, whose output is meant to feed svn-fe, are expected to learn here. For example, is the purpose of the above paragraph to make tool authors realize that "NUL terminates key and value, so I have to refrain from using a key or a value that contains a NUL byte?" [*1*] Even in that case, it is unclear to me what I (as an author of such a tool that reads data from somewhere and format it to plesae svn-fe) could do with that knowledge. [Footnote] *1* By the way, NULL is a pointer that does not point anywhere. The name of a byte whose value is 0x00 is NUL.