On Thu, Nov 17, 2005 at 11:16:15AM +0100, Erik Huelsmann wrote:
> > > + /** Translate from Normal Format; excludes SVN_WC_TRANSLATE_TO_NF */
> > > +#define SVN_WC_TRANSLATE_FROM_NF 0x00000000
> > > +
> > > + /** Translate to Normal Format; excludes SVN_WC_TRANSLATE_FROM_NF */
> > > +#define SVN_WC_TRANSLATE_TO_NF 0x00000001
> >
> > What is 'Normal Form(at)'?
>
> Well, the essence of my changes are actually to keep that an
> implementation detail. The user of these constants should not have to
> know what it is.
>
Julian got it right across-thread from here - I was asking for an
explanation as to what 'Normal Form' meant, because I couldn't really tell
from the context what it was, or when I'd want to use it. You're right
that the exact implementation details shouldn't be included here.
> > I guess (from later) that it's the format
> > that the text-base is stored in: LF line termination and unexpanded
> > keywords.
>
> Ah! See? This is exactly why it should be a (hidden) implementation
> fact: you have it only partly right. Yes, some files have LF
> termination. Others have CRLF termination as their normal form.
> Keywords are always stored unexpanded. But, the normal form for a
> symlink is entirely different from the actual versioned file (ie not a
> symlink).
>
I'd forgotten about symlinks, thanks (and the fact that it's also used
for the repository, which you mention below). But I probably shouldn't
have tried to include a (partial, as it turned out) technical definition,
since that's only confused the question.
As a user of this API, all I really needed to know is that: the format
of a file stored in the repository or text-base is not the same as one
stored in the working copy, for several reasons (of which line endings and
keywords are two well-known ones). 'Normal Format' refers to the format
of the file in the repository and text-base, and this function translates
between 'Normal Format' and the format seen directly by the user.
Is it Normal Form or Normal Format, by the way? You're using the former,
but the doc-comments use the latter.
And is it a phrase we normally use, or was it made up just for this
function? I only ask because this is the first time I've ever run across
it in the context of Subversion, and I'm wondering whether it's the best
choice of words to describe the concept. (But then I'm a database guy
by trade, so 'Normal Form' already means something completely different
to me :-)).
> > But it'd be good to document it here, since we don't
> > use the phrase elsewhere.
>
> Then maybe the README.txt in libsvn_wc should be expanded, or some
> document in notes/ should be added explaining what the normal form is
> defined as. All a programmer should need to know (IMO) is that we
> have such a thing and that you need to translate a WC file to it
> before sending it to the repository.
>
To be clear: "it" in my sentence meant just an explanation of what
the phrase meant, and why we need to care. A document in notes/ would
probably be helpful too, but my main concern was for consumers of the API.
> > (Hmm, would something even clearer like
> > SVN_WC_TRANSLATE_TEXTBASE_TO_WORKING be better? Probably too long.)
>
> But: it's not only the text base, it's also the contents as stored in
> the repository.
>
(which we should make clear (briefly) when giving an overview of the API.)
> > > + /** Only do translation associated with the svn:special property only */
> > Offhand, I don't know what kind of translation we'd do with respect to the
> > svn:special property at all. Could we have some more information here?
>
> Again, I agree that we may need more information on what libsvn_wc
> does and how, but I'd rather put that in some design document than in
> the docstrings.
>
Ok, fair enough. You might mention the work 'symlink' somewhere,
to give the reader a fighting chance of working out what's going on.
Like Julian, I also had trouble working out that this was actually a
_subtractive_ option: it prevents other stuff from happening. (Is it
really needed as an option? What's the use case?)
Regards,
Malcolm
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Nov 17 23:00:37 2005