[darcs-users] docs duplication

[Trent W. Buck]

Simon Michael <simon at joyful.com> writes:

> The manual's "Patch relationships" section is duplicated in Prim.lhs
> and Commute.lhs. They diverge around Commute.lhs line 404.

I have noticed this duplication.  I believe what happened was that there
was one copy, and then bits of it got (for some reason) copy-and-pasted
into various subsidiary modules of Darcs.Patch (or Darcs.Repository?).

I haven't taken any steps to deal with it.

> I believe the manual build process is using Prim and ignoring Commute,
> or maybe just ignoring the duplicated section.

>From memory some of the .lhs files simply aren't included in the user
manual (top file being src/darcs.tex).

> I'm inclined to remove the duplicated section from Commute. But I
> don't want to do anything hasty here, since docs is a
> multi-dimensional issue. What do you think is best ?

I think that two copies of the same explanatory text is super bad,
because (as we've seen) people edit one and forget about the other.

The problem I had was 1) working out which text was "newer" and
"correcter"; and 2) which file(s) the documentation end up in.

I also suspect at lot of that documentation should turn into haddock
comments instead of end user documentation.