view doc/README @ 5378:8a2915f57dfc

convert: add a mode where mercurial_sink skips empty revisions.

The getchanges function of some converter_source classes can return
some false positives.  I.e. they sometimes claim that a file "foo"
was changed in some revision, even though its contents are still the
same.

convert_svn is particularly bad, but I think this can also happen with
convert_cvs and, at least in theory, with mercurial_source.

For regular conversions this is not really a problem - as long as
getfile returns the right contents, we'll get a converted revision
with the right contents.  But when we use --filemap, this could lead
to superfluous revisions being converted.

Instead of fixing every converter_source, I decided to change
mercurial_sink to work around this problem.

When --filemap is used, we're interested only in revisions that touch
some specific files.  If a revision doesn't change any of these files,
then we're not interested in it (at least for revisions with a single
parent; merges are special).

For mercurial_sink, we abuse this property and rollback a commit if
the manifest text hasn't changed.  This avoids duplicating the logic
from localrepo.filecommit to detect unchanged files.

Mercurial's documentation is currently kept in ASCIIDOC format, which
is a simple plain text format that's easy to read and edit. It's also
convertible to a variety of other formats including standard UNIX man
page format and HTML.

To do this, you'll need to install ASCIIDOC:

 http://www.methods.co.nz/asciidoc/

To generate the man page:

 asciidoc -d manpage -b docbook hg.1.txt
 xmlto man hg.1.xml

To display:

 groff -mandoc -Tascii hg.1 | more

To create the html page (without stylesheets):

 asciidoc -b html4 hg.1.txt

(older asciidoc may want html instead of html4 above)