[darcs-users] [patch342] Adding information about cache handling to manual

[Eric Kow]

More documentation, yay!  In many cases, less is more, but sometimes
more is more too.

Adding information about cache handling to manual
-------------------------------------------------
> builes.adolfo at googlemail.com**20100811060603
>  Ignore-this: 787787385b16fb092e1e59f31476aaf4
> ] hunk ./src/best_practices.tex 423

Does this documentation *really* belong in the Best Practices section of
the user manual?

> +\subsection{Per-repository caches and possible conflicts}
> +Each time a repository is get lazily a new entry is include in
> +\_darcs/prefs/sources,

First, this may be factually wrong (isn't it *every* time you darcs
get a repository?)

Second, it's unclear: what entry?  Instead of saying a new entry,
you could say "its location is added as an entry in
_darcs/prefs/sources"

> you can add new entries and they give the same
> +advantages that a global cache does.

Is it factually correct that the entry in _darcs/prefs/sources gives
the same advantages as a global cache?  That does not sound quite
right. What's the *real* reason?

The above is a new sentence (so, ". You can add...")

> Entries in \_darcs/prefs/sources
> +files could become conflictive

Why "conflictive"?  I'm glad that you define it below, but I don't
understand what this has to do with conflicts.

> , darcs has a mechanism which helps us
> +to deal with such bad entries, if a conflictive source is discovered,
> +darcs stops using it for the rest of the session and then notifies to
> +the user to take further action with such an entry.

I can help a little bit with the punctuation here.

* ". Darcs has a mechanism..." (separate sentence)
* "to deal with such bad entries: "

> When you get a
> +message like:\\
> +\begin{verbatim}
> +> I could not reach the following repository:
> +> http://darcs.net/
> +> If you're not using it, you should probably delete
> +> the corresponding entry from _darcs/prefs/sources.
> +\end{verbatim}
> +It means that you have an entry in \_darcs/prefs/sources which looks
> +like ``repo:http://darcs.net'' and that such a source is causing an
> +error in darcs, what is recommended to do and if you are totally sure
> +that you won't need that entry again, delete it from the sources file.

It seems like the help text is self-explanatory.  Do we really need to
restate it in the documentation?  How does the documentation add value
to the help text?  I wish Trent were still active and could think about
these sort of things!

> +\subsubsection{When is a soure considered conflictive ?}
> +Darcs has 3 types of sources: local, http and ssh.  For all the three,
> +when an error occur when trying to fetch a file from one of the
> +sources, darcs verifies if the source is a reachable repository. To
> +verify reachability it uses the error message or checks that the
> +\_darcs/hashed\_inventory file is reachable. If the entry is of the
> +type ``http'' and the error is timeout, that source is consider
> +conflictive immediately, if not, it checks for \_/hashed\_inventory,
> +if it exists, it means that the entry is not conflictive but that the
> +wished file was not in that source.

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
For a faster response, please try +44 (0)1273 64 2905.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20100811/d9354c7f/attachment.pgp>