README: Convert to proper reStructuredText

Signed-off-by: Ulrich Müller <ulm@gentoo.org>

1 files changed, 51 insertions, 38 deletions

diff --git a/README b/README
index a434dda..d89bc6e 100644
--- a/README
+++ b/README
@@ -10,11 +10,13 @@ Prerequisite packages to install
 Create the author map
 =====================
 
-Extract userinfo.xml from LDAP on dev.gentoo.org:
-$ perl_ldap -U
+Extract userinfo.xml from LDAP on dev.gentoo.org::
 
-Create authormap.txt from userinfo.xml:
-$ ./make-authormap.sh >authormap.txt
+  $ perl_ldap -U
+
+Create authormap.txt from userinfo.xml::
+
+  $ ./make-authormap.sh >authormap.txt
 
 
 Fetch and unpack the CVS repository
@@ -26,9 +28,10 @@ https://projects.gentoo.org/vcs-history/gentoo-x86.tar.gz
 
 Run cvs-fast-export
 ===================
+::
 
-$ cd var/cvsroot/gentoo-x86
-$ find . | cvs-fast-export -A /path/to/authormap.txt -l /path/to/gentoo-x86-export.log -p >/path/to/gentoo-x86-export.out
+  $ cd var/cvsroot/gentoo-x86
+  $ find . | cvs-fast-export -A /path/to/authormap.txt -l /path/to/gentoo-x86-export.log -p >/path/to/gentoo-x86-export.out
 
 This will run for some time (8 hours on i7-8700), mostly as a single
 thread, and produce a 21 GiB output file.
@@ -36,8 +39,8 @@ thread, and produce a 21 GiB output file.
 The CVS repository contains a package app-backup/Attic, which confuses
 cvs-fast-export: "Files in CVS Attic and RCS directories are treated
 as though the 'Attic/' or 'RCS/' portion of the path were absent."
-This can be seen in the output file (note that the "Attic" path
-component is missing):
+This can be seen in the output file (note that the ``Attic`` path
+component is missing)::
 
   ----------------------------------------------------------------------
   commit refs/heads/master
@@ -72,22 +75,24 @@ This is fixed by an additional sed filter in the following step.
 
 Import into Git
 ===============
+::
 
-$ mkdir gentoo-x86-git
-$ cd gentoo-x86-git
-$ git init
-$ LC_ALL=C sed '/^Initial commit of Attic$/,/^M [0-7]\{6\} .* app-backup\/Manifest/{s:^\(M [0-7]\{6\} .* app-backup/\)\(.*\):\1Attic/\2:}' \
-../../var/cvsroot/gentoo-x86-export.txt | git fast-import
+  $ mkdir gentoo-x86-git
+  $ cd gentoo-x86-git
+  $ git init
+  $ LC_ALL=C sed '/^Initial commit of Attic$/,/^M [0-7]\{6\} .* app-backup\/Manifest/{s:^\(M [0-7]\{6\} .* app-backup/\)\(.*\):\1Attic/\2:}' \
+  ../../var/cvsroot/gentoo-x86-export.txt | git fast-import
 
 
 Differences to the old conversion
 =================================
 
 - cvs-fast-export(1) says:
-  "A set of file operations is coalesced into a changeset if either
-  (a) they all share the same commitid, or (b) all have no commitid
-  but identical change comments, authors, and modification dates
-  within the window defined by the time-fuzz parameter."
+
+    "A set of file operations is coalesced into a changeset if either
+    (a) they all share the same commitid, or (b) all have no commitid
+    but identical change comments, authors, and modification dates
+    within the window defined by the time-fuzz parameter."
 
   For our case this means that for commits after 2006-03-04T10:23:03Z
   (commit 531f1a00a131) the commitid has been used to group them
@@ -97,7 +102,7 @@ Differences to the old conversion
 
   This results in a total of 1688447 commits in the master branch,
   while the old conversion has only 788893 commits. Most of the
-  difference can be explained by the fact that "repoman commit"
+  difference can be explained by the fact that ``repoman commit``
   actually did two CVS commits, the second one for the Manifest to
   catch up with the updated $Header$ keywords. Since this reflects
   the actual workflow, no attempts have been made to squash these
@@ -122,14 +127,15 @@ Differences to the old conversion
   Also metadata/.cvsignore was renamed to metadata/.gitignore
   (cvs-fast-export does this automatically).
 
-- Output of "diff -qr --exclude=.git" between tips of old and new repo:
+- Output of ``diff -qr --exclude=.git`` between tips of old and new
+  repo::
 
-  Only in gentoo-x86-git: .gitignore
-  Only in gentoo-x86-git: app-backup
-  Files historical/header.txt and gentoo-x86-git/header.txt differ
-  Only in historical/metadata: .cvsignore
-  Only in gentoo-x86-git/metadata: .gitignore
-  Files historical/sci-libs/qfits/Manifest and gentoo-x86-git/sci-libs/qfits/Manifest differ
+    Only in gentoo-x86-git: .gitignore
+    Only in gentoo-x86-git: app-backup
+    Files historical/header.txt and gentoo-x86-git/header.txt differ
+    Only in historical/metadata: .cvsignore
+    Only in gentoo-x86-git/metadata: .gitignore
+    Files historical/sci-libs/qfits/Manifest and gentoo-x86-git/sci-libs/qfits/Manifest differ
 
 
 Notes
@@ -146,10 +152,10 @@ $-keywords.
 For the tip of the trunk, expanded keywords appear to be correct,
 as can be verified with Manifest checksums. This is not always true
 earlier in history. For example, the CVS repository was located in
-/home/cvsroot and moved to /var/cvsroot later ($Header$ lines suggest
-that this move happened in early 2004). Also it is known that some
-files were moved in the raw repository. Expanded keywords from before
-such a move won't match.
+/home/cvsroot and moved to /var/cvsroot later (``$Header$`` lines
+suggest that this move happened in early 2004). Also it is known that
+some files were moved in the raw repository. Expanded keywords from
+before such a move won't match.
 
 
 Branch points
@@ -159,7 +165,7 @@ cvs-fast-export-1.57 gets confused about branch points, if a file
 doesn't have any commits on the trunk that are newer than those on the
 branch.
 
-This triggers some warnings during conversion:
+This triggers some warnings during conversion::
 
   cvs-fast-export: warning - non-vendor ./app-admin/analog/files/analog.cfg,v branch RELEASE-1_4 has no parent
   [and many more of the same type]
@@ -169,14 +175,21 @@ This triggers some warnings during conversion:
   cvs-fast-export:        branch(85563): 2005-11-30T09:38:30Z  app-accessibility/SphinxTrain/files/digest-SphinxTrain-0.9.1-r1 1.1
 
 It also results in commits from the branch showing up in the converted
-Git master branch. The problem has been reported upstream:
-https://gitlab.com/esr/cvs-fast-export/-/issues/57
+Git master branch. The problem has been `reported upstream`__.
 
 For the time being, this is worked around by adding an extra commit to
-the trunk (and removing it from the converted repository later):
+the trunk (and removing it from the converted repository later)::
+
+  $ export CVSROOT=/var/cvsroot
+  $ cvs checkout gentoo-x86
+  $ cd gentoo-x86
+  $ for file in $(find . -type d -name CVS -prune -o -type f -print); do echo >>${file}; done
+  $ cvs commit -m "extra commit in trunk"
+
+__ https://gitlab.com/esr/cvs-fast-export/-/issues/57
+
 
-$ export CVSROOT=/var/cvsroot
-$ cvs checkout gentoo-x86
-$ cd gentoo-x86
-$ for file in $(find . -type d -name CVS -prune -o -type f -print); do echo >>${file}; done
-$ cvs commit -m "extra commit in trunk"
+.. Local Variables:
+.. mode: rst
+.. indent-tabs-mode: nil
+.. End: