add initial documentation

A README file is more suited to be read by humans, and the name has
evolved as a standard for initial documentation.

Trim COPYING down so that it contains only the software license, and
move the contributing part, which is only remotely related to the
license, into a single sub-section in the README. Also move the DCO
part into a single file to be referenced by the README.

Signed-off-by: Roland Hieber <rohieb@rohieb.name>

3 files changed, 123 insertions, 35 deletions

diff --git a/COPYING b/COPYING
index d7c552d..ff6f1a3 100644
--- a/COPYING
+++ b/COPYING
@@ -4,15 +4,6 @@ doesn't affect the previous statement though.) If the file doesn't specify a
 license explicitly, assume "version 2 only". The "GNU GENERAL PUBLIC LICENSE
 version 2" is appended below.
 
-Changes (aka patches) to microcom must be certified to be compatible with this.
-This is done by a signed-off line. If you can certify for your change that the
-"Developer's Certificate of Origin 1.1" (also appended below) applies, add a
-line reading:
-
-	Signed-off-by: Random J Developer <random@developer.example.org>
-
-with your real name and email address at the end of the patch description
-and send it to oss-tools@pengutronix.de.
 --------------------------------------------------------------------------------
 
                     GNU GENERAL PUBLIC LICENSE
@@ -354,29 +345,3 @@ proprietary programs.  If your program is a subroutine library, you may
 consider it more useful to permit linking proprietary applications with the
 library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.
---------------------------------------------------------------------------------
-Developer's Certificate of Origin 1.1
-
-By making a contribution to this project, I certify that:
-
-(a) The contribution was created in whole or in part by me and I
-    have the right to submit it under the open source license
-    indicated in the file; or
-
-(b) The contribution is based upon previous work that, to the best
-    of my knowledge, is covered under an appropriate open source
-    license and I have the right under that license to submit that
-    work with modifications, whether created in whole or in part
-    by me, under the same open source license (unless I am
-    permitted to submit under a different license), as indicated
-    in the file; or
-
-(c) The contribution was provided directly to me by some other
-    person who certified (a), (b) or (c) and I have not modified
-    it.
-
-(d) I understand and agree that this project and the contribution
-    are public and that a record of the contribution (including all
-    personal information I submit with it, including my sign-off) is
-    maintained indefinitely and may be redistributed consistent with
-    this project or the open source license(s) involved.
diff --git a/DCO b/DCO
new file mode 100644
index 0000000..8201f99
--- /dev/null
+++ b/DCO
@@ -0,0 +1,37 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..872d920
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+microcom
+========
+
+microcom is a minimalistic terminal program for communicating with devices over
+a serial connection (e.g. embedded systems, switches, modems). It features
+connection via RS232 serial interfaces (including setting of transfer rates) as
+well as in "Telnet mode" as specified in [RFC 2217].
+
+[RFC 2217]: https://tools.ietf.org/html/rfc2217
+
+
+Installation
+------------
+
+microcom depends on the [readline] library.
+
+If you just cloned this repository, you also need to install [autoconf],
+[automake], and the [autoconf archive] first. Then change to the project's root
+directy and do:
+
+```
+autoreconf -i
+```
+
+If you extracted minicom from a release tarball, this previous step should not
+be needed.
+
+Now continue with building and installing minicom:
+
+```
+./configure
+make
+sudo make install
+```
+
+By default, minicom is installed into `/usr/local/bin/`. Use `./configure
+--prefix=YOURPATH` to change that, and see `./configure --help` for more
+options related to building and installation.
+
+[readline]: https://tiswww.case.edu/php/chet/readline/rltop.html
+[autoconf]: https://www.gnu.org/software/autoconf/
+[automake]: https://www.gnu.org/software/automake/
+[autoconf archive]: https://www.gnu.org/software/autoconf-archive/
+
+
+Usage
+-----
+
+The typical usage with TTY devices looks like this:
+
+```
+microcom --speed=115200 --port=/dev/ttyS0
+```
+
+To connect to remote serial ports via RFC 2217, use the ``--telnet`` option instead:
+
+```
+microcom --speed=115200 --telnet=somehost:port
+```
+
+For the full list of options, see `microcom --help`.
+
+During the connection, you can get to the microcom menu by pressing `Ctrl-\`.
+Various options are available there, like setting flow  control, RTS and DTR.
+See ``help`` for a full list.
+
+
+License and Contributing
+------------------------
+
+microcom is free software and distributable under the GNU General Public
+License, version 2. See the file `COPYING` in this repository for more
+information.
+
+Changes to microcom must be certified to be compatible with this license. For
+this purpose, we use the Developer's Certificate of Origin 1.1; see the file
+`DCO` in this repository.  If you can certify that the DCO applies for your
+changes, add a line like the following:
+
+```
+Signed-off-by: Random J Developer <random@developer.example.org>
+```
+
+… containing your real name and e-mail address at the end of the patch
+description (Git can do this for you when you use `git commit -s`).
+Then send your patches to <oss-tools@pengutronix.de>.