1 patch for repository http://darcs.net:

Wed Aug 11 01:06:03 COT 2010  builes.adolfo@googlemail.com
  * Adding information about cache handling to manual

Attachments

• adding-information-about-cache-handling-to-manual.dpatch
• unnamed

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

Adding information about cache handling to manual
-------------------------------------------------
> builes.adolfo@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.

1 patch for repository http://darcs.net:

Wed Aug 11 15:02:11 COT 2010  builes.adolfo@googlemail.com
  * Adding information about cache handling to manual

Attachments

• adding-information-about-cache-handling-to-manual.dpatch
• unnamed

>
> Does this documentation *really* belong in the Best Practices section of
> the user manual?
>
I added there because that's where the global cache is mentioned, so I
thought It would fit as a subsection of global cache.

--
Adolfo

On Wed, Aug 11, 2010 at 20:00:45 +0000, Adolfo Builes wrote:
> Wed Aug 11 15:02:11 COT 2010  builes.adolfo@googlemail.com
>   * Adding information about cache handling to manual

Yeah, that looks better.  I've pushed a patch of my own on top
of this if that's OK; it just tightens up the wording a little
bit.  Thanks!

Adding information about cache handling to manual
-------------------------------------------------
> +\subsection{Per-repository caches and possible conflicts}
> +Each time a repository is get, its remote and local location, are
> +added as entries in \_darcs/prefs/sources. An entry in
> +\_darcs/prefs/sources could become totally or temporally unreachable,
> +when that happens, it can cause darcs to hang for a long time trying
> +to reach an unreachable repository. Fortunately darcs has a mechanism
> +which helps us to deal with that problem: if a conflictive entry is
> +discovered, darcs stops using it for the rest of the session and then
> +notifies to the user to take further action. It will display a message
> +like the following.\\
> +\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.

The main change being to remove the idea of conflicts to avoid potentially
confusing users.

eyk> Each time a repository is get, its location is added as an
eyk> entry in \_darcs/prefs/sources.  If one of these repositories were to
eyk> become totally or temporarily unreachable, it can cause darcs to hang
eyk> for a long time trying to reach it.  Fortunately darcs has a mechanism
eyk> which helps us to deal with that problem: if an unreachable entry is
eyk> discovered, darcs stops using it for the rest of the session and then
eyk> notifies to the user to take further action. It will display a message
eyk> like the following.\\


-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
For a faster response, please try +44 (0)1273 64 2905.

This patch bundle (with 1 patches) was just applied to the repository http://darcs.net/.
This message was brought to you by DarcsWatch
http://darcswatch.nomeata.de/repo_http:__darcs.net_.html#bundle-2ce02973d27b0807475c073293b2479861ee1714

This patch bundle (with 1 patches) was just applied to the repository http://darcs.net/reviewed.
This message was brought to you by DarcsWatch
http://darcswatch.nomeata.de/repo_http:__darcs.net_reviewed.html#bundle-2ce02973d27b0807475c073293b2479861ee1714