Re: [PATCH] Add warning about known issues to documentation of cvsimport

On Mon, Mar 23, 2009 at 08:53:05PM +0100, Heiko Voigt wrote:

The described issues are compiled from the tests by Michael Haggerty and me.
Because it is not apparent that these can be fixed anytime soon at least warn
unwary users not to rely on the inbuilt cvsimport to much.

I think this change is good in concept.

+[[issues]]
+ISSUES
+------
+Problems related to timestamps:
+
+ * If timestamps of commits in the cvs repository are not stable enough
+   to be used for ordering commits
+ * If any files were ever "cvs import"ed more than once (e.g., import of
+   more than one vendor release)
+ * If the timestamp order of different files cross the revision order
+   within the commit matching time window

Reading this, I kept waiting for the "then" to your "if". I think the
implication is "your import will be incorrect". But it would be nice to
say _how_, even if it's something as simple as "changes may show up in
the wrong commit, the wrong branch, be omitted" or whatever. Just give a
general idea of what can happen.

Also, this renders somewhat poorly in the manpage version. I get:

<quote>
ISSUES
       Problems related to timestamps:


       ·   If timestamps of commits in the cvs repository are not stable
           enough to be used for ordering commits

       ·   If any files were ever "cvs import"ed more than once (e.g., import
           of more than one vendor release)

       ·   If the timestamp order of different files cross the revision order
           within the commit matching time window
       Problems related to branches:


       ·   Branches on which no commits have been made are not imported
</quote>

Note the extra blank line between each heading and its list, and the
lack of a blank line between the end of the first list and the heading
of the second. Your source is very readable, so it really is just
asciidoc being silly, but I wonder if there is a way to work around
that.

-Peff