From c313360deb7bcd02d1c32dd6594d83dcff83b33f Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Mon, 11 Nov 2019 15:25:22 +0100 Subject: doc: clarify build instructions * README: A few fixes. Explain how to install color support. * README-hacking: Rename as... * README-hacking.md: this, and convert to Markdown. Improve typography. Improve explanations about update-test. --- README | 52 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 15 deletions(-) (limited to 'README') diff --git a/README b/README index e5a19d8d..70d2f49a 100644 --- a/README +++ b/README @@ -7,20 +7,42 @@ Here are basic installation instructions for a repository checkout: $ git submodule update --init $ ./bootstrap -then proceed with the usual 'configure && make' steps. +then proceed with the usual `configure && make` steps. -Be sure to read README-hacking, which contains all the needed information -about building, modifying and checking Bison. +The file README-hacking.md contains all the needed information about +building, modifying and checking Bison. ## Build from tarball See the file INSTALL for generic compilation and installation instructions. -Bison requires GNU m4 1.4.6 or later. See: +Bison requires GNU m4 1.4.6 or later. See +https://ftp.gnu.org/gnu/m4/m4-1.4.6.tar.gz. - https://ftp.gnu.org/gnu/m4/m4-1.4.6.tar.gz +## Colored diagnostics +As an experimental feature, diagnostics are now colored, controlled by the +`--color` and `--style` options. + +To use them, install the libtextstyle library before configuring Bison. It +is available from https://alpha.gnu.org/gnu/gettext/, for instance +https://alpha.gnu.org/gnu/gettext/libtextstyle-0.8.tar.gz. + +The option --color supports the following arguments: +- always, yes: Enable colors. +- never, no: Disable colors. +- auto, tty (default): Enable colors if the output device is a tty. + +To customize the styles, create a CSS file, say `bison-bw.css`, similar to + + /* bison-bw.css */ + .warning { } + .error { font-weight: 800; text-decoration: underline; } + .note { } + +then invoke bison with `--style=bison-bw.css`, or set the `BISON_STYLE` +environment variable to `bison-bw.css`. ## Relocatability -If you pass '--enable-relocatable' to 'configure', Bison is relocatable. +If you pass `--enable-relocatable` to `configure`, Bison is relocatable. A relocatable program can be moved or copied to a different location on the file system. It can also be used through mount points for network sharing. @@ -42,15 +64,15 @@ details. # Questions See the section FAQ in the documentation (doc/bison.info) for frequently asked questions. The documentation is also available in PDF and HTML, -provided you have a recent version of Texinfo installed: run "make pdf" or -"make html". +provided you have a recent version of Texinfo installed: run `make pdf` or +`make html`. If you have questions about using Bison and the documentation does not answer them, please send mail to . # Bug reports Please send bug reports to . Be sure to include the -version number from 'bison --version', and a complete, self-contained test +version number from `bison --version`, and a complete, self-contained test case in each bug report. # Copyright statements @@ -59,12 +81,6 @@ that the range specifies every single year in that closed interval.