+++ /dev/null
-This package contains Cdecl99: a program and library for parsing and
-constructing C declarations.
-
-== Installation ==
-=== Prerequisites ===
-Cdecl99 uses various features of C99, so a modern C compiler is required.
-There are no mandatory library dependencies beyond those required by standard
-C, but several optional features require external libraries.
-
- * GNU Readline is required for interactive line editing and command history
- in the 'cdecl99' tool.
- * GNU libintl (included with the GNU C Library) is required for
- internationalized program messages. Regardless of whether i18n is enabled,
- the explanations of declarations and types will always be in pseudo-English
- as the program is required to be able to parse its own output.
- * For a multithread-safe 'libcdecl', a suitable threading library is required
- at build time. At the time of writing (2011), POSIX, Solaris, Woe32 and GNU
- Pth threads are supported.
-
-=== Building ===
-See the file INSTALL for generic compilation and installation instructions.
-
-==== Building from Git ====
-Sources checked out from Git do not contain any of the generated files which
-would normally be included in the distribution tarballs. As such, a number
-of additional tools are required. Any version numbers listed represent
-minimum tested versions. Using newer versions of the tools should work,
-but older versions should not be expected to.
-
- * GNU Autoconf version 2.68
- * GNU Automake version 1.11.1
- * GNU Libtool version 2.4
- * GNU Gettext version 0.18.1
- * GNU Bison version 2.4.3
- * flex version 2.5.35
- * perl version 5.12
-
-To generate the build system from Git, run the 'bootstrap' script in the
-top-level directory. This will automatically check out the full Gnulib
-sources, which can be quite large. If you already have a Gnulib git checkout
-on your system, you can save space by running
-
- git submodule update --init --reference /path/to/gnulib/checkout
-
-prior to running the 'bootstrap' script. After the build system is generated,
-configure and build Cdecl99 as normal.
-
-== Contributing ==
-If you think you've found a bug in any part of Cdecl99, please report it by
-email to Nick Bowler <nbowler@draconx.ca>. Patches should be sent to the same
-address.
-
-== Copyright and License ==
-
-Copyright © 2011 Nick Bowler
-
-Cdecl99 is free software: you can redistribute it and/or modify it under the
-terms of the GNU General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any later
-version.
-
-This program is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License along with
-this program. If not, see <http://www.gnu.org/licenses/>.
-
-Additionally, some files in the distribution may be licensed under terms other
-than the GNU General Public License. All such files will contain a clear
-notice of this fact; the alternate license permissions stated in a file apply
-to the contents of that file and that file only. In the absense of any
-license notice, the GNU General Public License, version 3 or later, is to be
-assumed (but please report this absense as you would any other bug).
-
-For example, the following terms apply to this README document:
-_________________________________________________________________________
-
-Permission is granted to copy, distribute and/or modify this README under
-the terms of the Do What The Fuck You Want To Public License, version 2.
-_________________________________________________________________________
--- /dev/null
+Cdecl99 is a tool to help construct or understand complicated C declarations.
+Inspired by the venerable cdecl, which predates C's standardization in 1989,
+cdecl99 implements more or less the same concept but for modern C.
+
+Unlike the original cdecl, cdecl99 supports all relevant C99 keywords, has no
+undue restrictions on identifiers, understands features such as complex types,
+variadic functions and named parameters, and also has the ability to parse
+"plain" type names (which do not declare an identifier).
+
+At this time there is no support for new declaration syntax introduced in C11,
+including atomic types, `_Alignas`, `_Thread_local` or `_Noreturn` specifers.
+
+The package includes both an executable program (cdecl99) and a library
+(libcdecl) which can be used by other programs to provide cdecl-like
+functionality.
+
+# Prerequisites
+
+Cdecl99 is writtin in C, so a working C compiler is required. Certain
+optional features depend on the use of external libraries. In particular,
+
+* the [GNU Readline library][readline-homepage] is needed for
+ interactive line-editing and history functionality, and
+
+* the [GNU libintl library][gettext-homepage] (included with the GNU C
+ library) is needed in order to support localized program messages.
+ However, the core functionality of translating C declarations to/from
+ pseudo-English is not localizable.
+
+[readline-homepage]: https://www.gnu.org/software/readline/
+[gettext-homepage]: https://www.gnu.org/software/gettext/
+
+# Contributing
+
+Please send suggestions, bug reports, patches or any other
+correspondence regarding cdecl99 by electronic mail to
+[Nick Bowler \<nbowler@draconx.ca\>][email].
+
+[email]: mailto:nbowler@draconx.ca
+
+# License
+
+Cdecl99 is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License or (at your option) any later
+version.
+
+{::comment}
+Copyright © 2011, 2019, 2021 Nick Bowler
+{:/comment}