Convert README to README.md

Let's move vaguely into the twenty-first century by converting our old
plain text README file to Markdown.  While we're updating the formatting,
make some small polish changes to the content.

Signed-off-by: David Gibson <david@gibson.dropbear.id.au>

2 files changed, 120 insertions, 106 deletions

diff --git a/README b/README
deleted file mode 100644
index a48312a..0000000
--- a/README
+++ /dev/null
@@ -1,106 +0,0 @@
-The source tree contains the Device Tree Compiler (dtc) toolchain for
-working with device tree source and binary files and also libfdt, a
-utility library for reading and manipulating the binary format.
-
-DTC and LIBFDT are maintained by:
-
-David Gibson <david@gibson.dropbear.id.au>
-Jon Loeliger <loeliger@gmail.com>
-
-
-Python library
---------------
-
-A Python library is also available. To build this you will need to install
-swig and Python development files. On Debian distributions:
-
-   sudo apt-get install swig python3-dev
-
-The library provides an Fdt class which you can use like this:
-
-$ PYTHONPATH=../pylibfdt python3
->>> import libfdt
->>> fdt = libfdt.Fdt(open('test_tree1.dtb', mode='rb').read())
->>> node = fdt.path_offset('/subnode@1')
->>> print(node)
-124
->>> prop_offset = fdt.first_property_offset(node)
->>> prop = fdt.get_property_by_offset(prop_offset)
->>> print('%s=%s' % (prop.name, prop.as_str()))
-compatible=subnode1
->>> node2 = fdt.path_offset('/')
->>> print(fdt.getprop(node2, 'compatible').as_str())
-test_tree1
-
-You will find tests in tests/pylibfdt_tests.py showing how to use each
-method. Help is available using the Python help command, e.g.:
-
-    $ cd pylibfdt
-    $ python3 -c "import libfdt; help(libfdt)"
-
-If you add new features, please check code coverage:
-
-    $ sudo apt-get install python3-coverage
-    $ cd tests
-    # It's just 'coverage' on most other distributions
-    $ python3-coverage run pylibfdt_tests.py
-    $ python3-coverage html
-    # Open 'htmlcov/index.html' in your browser
-
-
-The library can be installed with pip from a local source tree:
-
-    pip install . [--user|--prefix=/path/to/install_dir]
-
-Or directly from a remote git repo:
-
-    pip install git+git://git.kernel.org/pub/scm/utils/dtc/dtc.git@main
-
-The install depends on libfdt shared library being installed on the host system
-first. Generally, using --user or --prefix is not necessary and pip will use the
-default location for the Python installation which varies if the user is root or
-not.
-
-You can also install everything via make if you like, but pip is recommended.
-
-To install both libfdt and pylibfdt you can use:
-
-    make install [PREFIX=/path/to/install_dir]
-
-To disable building the python library, even if swig and Python are available,
-use:
-
-    make NO_PYTHON=1
-
-
-More work remains to support all of libfdt, including access to numeric
-values.
-
-
-Adding a new function to libfdt.h
----------------------------------
-
-The shared library uses libfdt/version.lds to list the exported functions, so
-add your new function there. Check that your function works with pylibfdt. If
-it cannot be supported, put the declaration in libfdt.h behind #ifndef SWIG so
-that swig ignores it.
-
-
-Tests
------
-
-Test files are kept in the tests/ directory. Use 'make check' to build and run
-all tests.
-
-If you want to adjust a test file, be aware that tree_tree1.dts is compiled
-and checked against a binary tree from assembler macros in trees.S. So
-if you change that file you must change tree.S also.
-
-
-Mailing list
-------------
-The following list is for discussion about dtc and libfdt implementation
-mailto:devicetree-compiler@vger.kernel.org
-
-Core device tree bindings are discussed on the devicetree-spec list:
-mailto:devicetree-spec@vger.kernel.org
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..30212bc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,120 @@
+# Device Tree Compiler and libfdt
+
+The source tree contains the Device Tree Compiler (dtc) toolchain for
+working with device tree source and binary files and also libfdt, a
+utility library for reading and manipulating the binary format.
+
+dtc and libfdt are maintained by:
+
+* [David Gibson `<david@gibson.dropbear.id.au>`](mailto:david@gibson.dropbear.id.au)
+* [Jon Loeliger `<loeliger@gmail.com>`](mailto:loeliger@gmail.com)
+
+## Python library
+
+A Python library wrapping libfdt is also available. To build this you
+will need to install `swig` and Python development files. On Debian
+distributions:
+
+```
+$ sudo apt-get install swig python3-dev
+```
+
+The library provides an `Fdt` class which you can use like this:
+
+```
+$ PYTHONPATH=../pylibfdt python3
+>>> import libfdt
+>>> fdt = libfdt.Fdt(open('test_tree1.dtb', mode='rb').read())
+>>> node = fdt.path_offset('/subnode@1')
+>>> print(node)
+124
+>>> prop_offset = fdt.first_property_offset(node)
+>>> prop = fdt.get_property_by_offset(prop_offset)
+>>> print('%s=%s' % (prop.name, prop.as_str()))
+compatible=subnode1
+>>> node2 = fdt.path_offset('/')
+>>> print(fdt.getprop(node2, 'compatible').as_str())
+test_tree1
+```
+
+You will find tests in `tests/pylibfdt_tests.py` showing how to use each
+method. Help is available using the Python help command, e.g.:
+
+```
+$ cd pylibfdt
+$ python3 -c "import libfdt; help(libfdt)"
+```
+
+If you add new features, please check code coverage:
+
+```
+$ sudo apt-get install python3-coverage
+$ cd tests
+# It's just 'coverage' on most other distributions
+$ python3-coverage run pylibfdt_tests.py
+$ python3-coverage html
+# Open 'htmlcov/index.html' in your browser
+```
+
+The library can be installed with pip from a local source tree:
+
+```
+$ pip install . [--user|--prefix=/path/to/install_dir]
+```
+
+Or directly from a remote git repo:
+
+```
+$ pip install git+git://git.kernel.org/pub/scm/utils/dtc/dtc.git@main
+```
+
+The install depends on libfdt shared library being installed on the
+host system first. Generally, using `--user` or `--prefix` is not
+necessary and pip will use the default location for the Python
+installation which varies if the user is root or not.
+
+You can also install everything via make if you like, but pip is
+recommended.
+
+To install both libfdt and pylibfdt you can use:
+
+```
+$ make install [PREFIX=/path/to/install_dir]
+```
+
+To disable building the python library, even if swig and Python are available,
+use:
+
+```
+$ make NO_PYTHON=1
+```
+
+More work remains to support all of libfdt, including access to numeric
+values.
+
+
+## Adding a new function to libfdt.h
+
+The shared library uses `libfdt/version.lds` to list the exported
+functions, so add your new function there. Check that your function
+works with pylibfdt. If it cannot be supported, put the declaration in
+`libfdt.h` behind `#ifndef SWIG` so that swig ignores it.
+
+
+## Tests
+
+Test files are kept in the `tests/` directory. Use `make check` to build and run
+all tests.
+
+If you want to adjust a test file, be aware that `tree_tree1.dts` is compiled
+and checked against a binary tree from assembler macros in `trees.S`. So
+if you change that file you must change `tree.S` also.
+
+
+## Mailing lists
+
+* The [devicetree-compiler](mailto:devicetree-compiler@vger.kernel.org)
+  list is for discussion about dtc and libfdt implementation.
+* Core device tree bindings are discussed on the
+  [devicetree-spec](mailto:devicetree-spec@vger.kernel.org) list.
+