From: Nick Bowler Date: Wed, 24 Feb 2021 00:33:16 +0000 (-0500) Subject: Rework the README. X-Git-Tag: v1~11 X-Git-Url: https://git.draconx.ca/gitweb/cdecl99.git/commitdiff_plain/8302d372469527e0df9773357b7a0ad105d34958 Rework the README. This consolidates the text of this README with the text on my website, and gets rid of a bunch of bootstrapping-related suggestions which are not particularly interesting and probably obsolete anyway as none of the tool versions listed have been updated in about a decade. --- diff --git a/Makefile.am b/Makefile.am index 4bdc88c..6d2cc66 100644 --- a/Makefile.am +++ b/Makefile.am @@ -30,7 +30,7 @@ EXTRA_DIST = m4/gnulib-cache.m4 src/types.lst src/validtypes.sed \ src/specs.lst src/namespecs.sed src/ordspecs.sed \ src/errors.lst src/strtab.sed test/typegen.sh \ src/parse.y src/parse.stamp src/scan.l src/scan.stamp \ - COPYING.WTFPL2 + COPYING.WTFPL2 README.md dist_man_MANS = doc/man/cdecl99.1 doc/man/libcdecl.3 diff --git a/README b/README deleted file mode 100644 index ef596eb..0000000 --- a/README +++ /dev/null @@ -1,81 +0,0 @@ -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 . 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 . - -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. -_________________________________________________________________________ diff --git a/README.md b/README.md new file mode 100644 index 0000000..917a44a --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +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 \][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}