More documentation, yay! In many cases, less is more, but sometimes more is more too.
Adding information about cache handling to manual
-------------------------------------------------
> builes.ado...@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.
signature.asc
Description: Digital signature
_______________________________________________ darcs-users mailing list darcs-users@darcs.net http://lists.osuosl.org/mailman/listinfo/darcs-users
