README

regex-markup - Introduction
===========================

regex-markup performs regular expression-based text markup according to
used-defined rules. This can be used to color syslog files as well as the
output of programs such as ping, traceroute, gcc etc. The hierarchal
rules-format is simple to understand, yet very powerful. Regex-markup is
written entirely in C, and uses POSIX regular expressions to do much of its
work.

For example, these rules can be used to color all lines containing `kernel:
' green, and in those lines the word `panic' red:

   style green { pre "\E[32m" post "\E[39m" }
   style red { pre "\E[31m" post "\E[39m" }

   /kernel: (.*)/ {
     green
     /panic/ig { red }
   }

Example rules for ping, traceroute, and syslogs are included.

regex-markup is written by Oskar Liljeblad, and is free software licensed
under terms of the GNU General Public License.

Copyright and License
=====================

regex-markup is copyright (C) 2001-2005 Oskar Liljeblad.

This program 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 2 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, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA  02111-1307  USA

The source code of this project may contain files from other projects, and
files generated by other projects, including:

 * GNU Autoconf (http://www.gnu.org/software/autoconf/)
 * GNU Automake (http://sources.redhat.com/automake/)
 * GNU gettext (http://www.gnu.org/software/gettext/)
 * Gnulib (http://www.gnu.org/software/gnulib/)
 * Flex (http://www.gnu.org/software/flex/)
 * GNU Bison (http://www.gnu.org/software/bison/)
 * Autoconf Macro Archive (http://ac-archive.sourceforge.net/)

Such files are licensed under the terms of the GNU General Public License
or a license compatible with the GNU GPL (as listed on
http://www.gnu.org/licenses/license-list.html). See each file for copyright
details.

The Swedish translations in the po directory may contain translations from
other projects, including:

 * GNU C Library (http://www.gnu.org/software/libc/libc.html)
 * GNU Core Utilities (http://www.gnu.org/software/coreutils/)

See the specific message file (PO file) for copyright of those messages.

Requirements
============

The following programs are useful (but not required) when building
regex-markup:

 * Bison (or Yacc)

   For generating src/script.c if it hasn't been generated already.

The following programs are required to build regex-markup:

 * gcc 2.95 or later.

   regex-markup uses some features specific to gcc 2.95 (such as macros
   with variable number of arguments).

The following programs are required for proper operation of regex-markup:

 * GNU libc6 2.0 or later

   regex-markup uses GNU-specific extensions to the C library.

Installation

Compile regex-markup by running configure and then make. This should
produce executables in the src directory, which can be used right away.

If you want to install the regex-markup on your system, run make install.
This will copy the executables and the man pages into the appropriate
directories (usually /usr/local/bin and /usr/local/share/man/man1,
respecively).

For further details regarding configure and make, see the INSTALL document.

Common problems
===============

Q: Remark prints this error when started

   remark: Cannot allocate memory

A: Try recompiling regex-markup without the -O2 option, like this:

   CFLAGS=-g ./configure ; make clean ; make

Please write me if that doesn't help.

Usage
=====

regex-markup consists of two programs, remark and cacheline. The main
program, remark, reads lines of text from standard in, highlights them
according to certain rules defined by the user, and writes the highlighted
line to standard out. It only takes one argument - a file containing the
highlighing rules. The format of these files are described in the manual
page of remark.

Examples:

   ping www.yahoo.com | remark ../examples/rules/ping
   traceroute www.kernel.org | remark ../examples/rules/traceroute

The remark program supports the usual long option `--help' which displays
usage and option information. A manual page which can be viewed with

   man ./remark.1

is provided. (A manual page for cacheline, cacheline.1, is also provided.)

The cacheline program is used by the logwatcher example program to delay
newlines in output. See the cacheline manpage for more details.

Format of rule files
====================

See the provided manual page, remark.1.

Homepage
========

The latest version of regex-markup can be downloaded from

   http://www.nongnu.org/regex-markup/

Feedback
========

The author of regex-markup and this document, Oskar Liljeblad, can be
reached via email:

   oskar@osk.mine.nu (mailto:oskar@osk.mine.nu)

Please send bug reports, suggestions, ideas or comments in general to me.

Known bugs
==========

None at the moment.

Possible things to do
=====================

Please see the TODO document.

-