Update README (and convert to Markdown)

2 files changed, 64 insertions, 37 deletions

diff --git a/README b/README
deleted file mode 100644
index 531025c..0000000
--- a/README
+++ /dev/null
@@ -1,37 +0,0 @@
-rpm-mageia-setup
-$Id: README 22754 2007-02-22 13:03:02Z nanardon $
-
-This package contains configuration and script for the Mageia rpm.
-
-Some file come from .in, this allow to transform path for testing purpose.
-If your file or script contains path, you should make a .in files.
-
-* About macros:
-Only redefine macros in this package if the rpm one does not please to you.
-
-All macros having same body should go into macros.in.
-If the macros body change:
-- add a symbolic value into macros-perarch.in (@foo@)
-- add the value into make_macrosfiles.sh.in
-
-Example:
-%_libdir /use/%_lib => macros.in
-%_lib lib|lib64 => macros-perarch.in
-
-* Testing the monster
-
-o First and easy way:
-$ make test
-
-o Live tests:
-
-$ ./configure --with-rpmconfdir=$fakeroot --with-rpmlibdir=/usr/lib/rpm --with-rpmsysconfdir=/etc
-
-This will configure the package for an installation into fakeroot, using rpm files in /usr/lib/rpm.
-$ make
-$ make install
-
-Now we can say to rpm to use fake config:
-rpm --rcfile $fakeroot/mageia/rpmrc other command...
-
-Happy Hacking
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..84152ca
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+# Mageia RPM Setup
+
+This package contains configuration and scripts related to the use of RPM in Mageia. It is ultimately released and packaged as `rpm-mageia-setup`.
+
+Some files are packaged in .in files. These files allow you to pre-process certainly paths and configure options and inject them into the built scripts.
+
+## About macros
+
+Only redefine macros in this package if the upstream RPM one is not fit for purpose in Mageia. Please only do this as a last resort and try to work with upstream whenever possible.
+
+All macros having same body in all architectures should go into macros.in. If the macros body change depending on architecture, then:
+
+1. add a symbolic value into `macros-perarch.in` (e.g. @FOO@)
+2. add the value into `make_macrosfiles.sh.in`
+
+### Example
+
+`macros.in` contains:
+
+    %_libdir /usr/%_lib
+
+`macros-perarch.in` contains:
+
+    %_lib @LIB@
+
+`make_macrosfiles.sh.in` contains (among other things):
+
+    MINPUT="$1"
+    ARCH="$2"
+
+    LIB=lib
+
+    case $ARCH in
+        …
+        amd64|x86_64)
+        LIB=lib64
+        ;;
+        …
+    esac
+
+    cat "$MINPUT" | sed \
+        -e "s,@LIB@,$LIB,g"
+
+
+## Testing the monster
+
+First and easy way:
+
+    $ make test
+
+Live tests:
+
+    $ ./configure --with-rpmconfdir=$fakeroot --with-rpmlibdir=/usr/lib/rpm --with-rpmsysconfdir=/etc
+
+This will configure the package for an installation into fakeroot, using rpm files in `/usr/lib/rpm`.
+
+    $ make
+    $ make install
+
+Now we can tell rpm to use fake config:
+
+    $ rpm --rcfile $fakeroot/mageia/rpmrc other command...
+
+Happy Hacking!