On 11/17/05, Malcolm Rowe <malcolm-svn-dev@farside.org.uk> wrote:
> 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.
>
[snip]
> 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.
> >
It might be better to call this "Repository Format" as that is more
explicit, and
will be less confusing in the long term as features like compressed text base
are introduced, since at that point the text-bases will no longer be in "Normal
Format".
Josh
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Nov 21 17:48:18 2005