Erik Huelsmann wrote:
>
> Here's the patch. It extends some doc strings. I have no idea what
> more to put in the log message. Do you have anything to add?
That's all the log message needs to say.
> Index: subversion/include/svn_subst.h
> ===================================================================
> --- subversion/include/svn_subst.h (revision 17513)
> +++ subversion/include/svn_subst.h (working copy)
> @@ -259,10 +259,13 @@
>
>
> /**
> - * Convenience routine: a variant of svn_subst_translate_stream3()
> - * which operates on files. In addition, it will create/detranslate a special
> - * file if @a special is @c TRUE.
> + * Translates the file at path @a *src into a file at path @a *dst. The
"src" rather than "*src": we regard the pointer as meaning "the string"
(whereas "*src" implies a single character). Same for "dst" and in the next
doc string.
Minor syle point: we generally use the infinitive (subject-less) form of the
verb: "Translate the file" rather than "[This function] Translates the file".
(In English, the infinitive form is identical to the imperative (command) form,
if that makes it easier.)
> + * parameters @a *eol_str, @a repair, @a *keywords and @a expand are
> + * defined the same as in svn_subst_translate_stream3().
> *
> + * In addition, it will create a special file from normal form or
> + * translate one to normal form if @a special is @c TRUE.
> + *
> * Copy the contents of file-path @a src to file-path @a dst atomically,
> * either creating @a dst (or overwriting @a dst if it exists), possibly
> * performing line ending and keyword translations.
> @@ -355,8 +358,9 @@
> svn_boolean_t expand,
> apr_pool_t *pool);
>
> -/** Convenience routine (wrapper around svn_subst_copy_and_translate3)
> - * which detranslates the given @a src into @a dst.
> +/**
> + * Translates a file @a *src in working copy form to a file @a *dst in
> + * normal form form.
Repetition of "form". You might as well make this sentence and the one in the
doc string above use the same words to describe "src" and "dst": either "the
file at path @a src"/"a file at path @a dst" or "the file @a src"/"a file @a dst".
[...]
> Index: subversion/include/svn_wc.h
> ===================================================================
> --- subversion/include/svn_wc.h (revision 17513)
> +++ subversion/include/svn_wc.h (working copy)
> @@ -64,10 +64,22 @@
> * @{
> */
>
> - /** Translate from Normal Format; excludes SVN_WC_TRANSLATE_TO_NF */
> + /** Translate from Normal Form.
> + *
> + * The working copy text bases and repository files are stored
> + * in normal form if they have any svn: properties set which
> + * require translation.
At first I interpreted that sentence as a brief definition of Normal Form,
rather than just a statement about it, and that set me thinking about it.
Interpreted as a definition, it seems to imply that:
1a) If a given file doesn't require translation then it doesn't have a
normal form, and so these functions don't apply to it and shouldn't be used.
1b) All Normal Forms share the common feature of LF EOLs. It's not quite
clear whether they will all have at least one contracted keyword; that depends
whether this definition applies to files that have e.g. "svn:keywords=Id" but
no "$Id" present in them. They certainly won't necessarily have all of their
keywords contracted, only the ones that are mentioned in "svn:keywords".
I was thinking of another possible definition:
2) Normal Form of any file is the form in which the file is stored in the
repository (and WC text base).
This implies that:
2a) The Normal Form (of a given file) does not necessarily have LF line
endings or contracted keywords.
2b) Every file has a Normal Form, but there is no feature that is common to
all Normal Forms.
Do you think we could successfully use definition (2)? I think it would be
easier to define and understand, if we can.
But it really doesn't matter right here. The point was just to have some hint
in the doc string about what this term "Normal Form" refers to, and you've
put enough of a hint there.
> + *
> + * Either this flag or @c SVN_WC_TRANSLATE_FROM_NF should be specified,
> + * but not both.
> + */
> #define SVN_WC_TRANSLATE_FROM_NF 0x00000000
>
> - /** Translate to Normal Format; excludes SVN_WC_TRANSLATE_FROM_NF */
> + /** Translate to Normal Form.
> + *
> + * Either this flag or @c SVN_WC_TRANSLATE_FROM_NF should be specified,
> + * but not both.
> + */
> #define SVN_WC_TRANSLATE_TO_NF 0x00000001
>
> /** Force repair of eol styles, making sure the output file consistently
> @@ -3165,14 +3177,20 @@
>
> /* EOL conversion and keyword expansion. */
>
> -/** Set @a *xlated_path to a path to translated copy of @src
> +/** Set @a *xlated_path to a path to a translated copy of @src
"@src" -> "@a src"
> * or to @a src itself if no translation is necessary.
> * That is, if @a versioned_file's properties indicate newline conversion or
> * keyword expansion, point @a *xlated_path to a copy of @a src
> * whose newlines and keywords are converted using the translation
> * as requested by @a flags.
> *
> - * Caller can explicitly request a new file to be returned by setting the
> + * When translating to the normal form, inconsistent eol styles will be
(I suppose consistently writing either "EOL" or "eol" would mean lots of
changes outside the scope of this patch ... forget I mentioned it.)
> + * repaired when appropriate for the given setting. When translating
> + * from normal form, no EOL repair is performed (consistency is assumed).
> + * These behaviours can be overridden by specifying either
> + * @c SVN_WC_TRANSLATE_NO_EOL_REPAIR or @c SVN_WC_TRANSLATE_FORCE_EOL_REPAIR.
No: SVN_WC_TRANSLATE_NO_EOL_REPAIR doesn't exist.
[...]
These are just simple fixes so if you want to just revise it and commit it
that's fine with me.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Nov 26 01:06:17 2005