Re: [PATCHv2] Add details about svn-fe's dumpfile parsing

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 16, 2012, 20:06 UTC
Message-ID: <7vipgztpaf.fsf@alter.siamese.dyndns.org>
In-Reply-To: <4F8AF306.8070804@pileofstuff.org>

Andrew Sayers <andrew-git@pileofstuff.org> writes:

Show 18 quoted lines

> 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 <andrew-git@pileofstuff.org>
> ---

OK, so is this ready for 'master' already?

Show 18 quoted lines

>  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.