From d09470310aca7f6a5ac9c7b3106c3829d99dc356 Mon Sep 17 00:00:00 2001
From: Paul Sheer <psheer@obsidian.co.za>
Date: Thu, 10 Dec 1998 22:14:10 +0000
Subject: [PATCH] doc udates

---
 doc/mc.sgml     |   3 +-
 doc/mcedit.1.in | 104 ++++++++++++++++++++++++++++++------------------
 2 files changed, 68 insertions(+), 39 deletions(-)

diff --git a/doc/mc.sgml b/doc/mc.sgml
index 494a57d3c..76298f1c8 100644
--- a/doc/mc.sgml
+++ b/doc/mc.sgml
@@ -2323,7 +2323,8 @@ menusel, menuhot, menuhotsel, gauge; the dialog colors
 are: dnormal, dfocus, dhotnormal, dhotfocus;  Help colors
 are: helpnormal, helpitalic, helpbold, helplink,
 helpslink;  Viewer color is: viewunderline; Special highlighting mode: 
-executable, directory, link, device, special.
+executable, directory, link, device, special; Editor colors
+are: editnormal, editbold, editmarked.
 
 The dialog boxes use the following colors: <em/dnormal/ is
 used for the normal text, <em/dfocus/ is the color used for the
diff --git a/doc/mcedit.1.in b/doc/mcedit.1.in
index 3654fe98a..5a802a69b 100644
--- a/doc/mcedit.1.in
+++ b/doc/mcedit.1.in
@@ -165,14 +165,17 @@ that keywords and contexts (like C comments, string constants, etc) are
 highlighted in different colours. The following section explains the
 format of the file \fB~/.cedit/syntax\fP.
 
-The file \fB~/.cedit/syntax\fP (\fB~/.cedit/mcsyntax\fP for mcedit) is
-rescanned on opening of a any new editor file. The file contains
-rules for highlighting, each of which is given on a seperate line,
-and define which keywords will be highlighted to what colour. The
-file is also divided into sections, each beginning with a line with
-the \fBfile\fP command, followed by a regular expression. The
-regular expression dictates the file name that that set of rules
-applies to.
+The file \fB~/.cedit/syntax\fP is rescanned on opening of a any new
+editor file. The file contains rules for highlighting, each of which is
+given on a seperate line, and define which keywords will be highlighted
+to what colour. The file is also divided into sections, each beginning
+with a line with the \fBfile\fP command, followed by a regular
+expression. The regular expression dictates the file name that that set
+of rules applies to. Following this is a description to be printed on the
+left of the editor window explaining the file type to the user. A third
+optional argument is a regular expression to match the first line of
+text of the file. If either the file name matches, or the first line of text,
+then those rules will be loaded.
 
 A section ends with the start of a new section. Each section is divided
 into contexts, and each context contains rules. A context is a scope
@@ -185,38 +188,38 @@ highlighted within a C comment.
 A trivial C programming section might look like this:
 .PP
 .nf
-file .\\*\\\\.c
+file .\\*\\\\.c C\\sProgram\\sFile (#include|/\\\\\\*)
 
 wholechars abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_
 
 # default colors
 context default
-  keyword  whole  if       yellow
-  keyword  whole  else     yellow
-  keyword  whole  for      yellow
-  keyword  whole  while    yellow
-  keyword  whole  do       yellow
-  keyword  whole  switch   yellow
-  keyword  whole  case     yellow
-  keyword  whole  static   yellow
-  keyword  whole  extern   yellow
-  keyword         {        yellow
-  keyword         }        yellow
-  keyword         '*'      green
+  keyword  whole  if       24
+  keyword  whole  else     24
+  keyword  whole  for      24
+  keyword  whole  while    24
+  keyword  whole  do       24
+  keyword  whole  switch   24
+  keyword  whole  case     24
+  keyword  whole  static   24
+  keyword  whole  extern   24
+  keyword         {        14
+  keyword         }        14
+  keyword         '*'      6 
 
 # C comments
-context /\\* \\*/ brown
+context /\\* \\*/ 22
 
 # C preprocessor directives
-context linestart # \\n red
-  keyword  \\\\\\n  yellow
+context linestart # \\n 18
+  keyword  \\\\\\n  24
 
 # C string constants
-context " " green
-  keyword  %d    brightgreen
-  keyword  %s    brightgreen
-  keyword  %c    brightgreen
-  keyword  \\\\"   brightgreen
+context " " 6
+  keyword  %d    24
+  keyword  %s    24
+  keyword  %c    24
+  keyword  \\\\"   24
 .fi
 .PP
 Each context starts with a line of the form:
@@ -261,20 +264,20 @@ seperator, it may not be used explicitedly. Also, \\* must be used to
 specify a *. The * itself is a wildcard that matches any length of
 characters. For example,
 .nf
-  keyword         '*'      green
+  keyword         '*'      6 
 .fi
 colours all C single character constants green. You could also have
 used
 .nf
-  keyword         "*"      green
+  keyword         "*"      6 
 .fi
 to colour string constants, except that the matched string may not cross
 newlines. \fIThe wildcard may be used within context delimiters as
-well\fP, but you cannot have a wildcard as the last or first character.
+well\fP, but you \fBcannot have a wildcard as the last or first character\fP.
 
 Important to note is the line
 .nf
-  keyword  \\\\\\n  yellow
+  keyword  \\\\\\n  24
 .fi
 This line defines a keyword containing the \\ and newline characters.
 Because keywords have a higher precedence than context delimiters, this
@@ -282,17 +285,42 @@ keyword prevents the context from ending at the end of a line if the
 line ends in a \\ thus allowing C preprocessor directive to continue
 across multiple lines.
 
-Comment may be included on a line of there own and begin with
+The colours themselves are numbered 0 to 26 and are explained below in
+\fBFURTHER BEHAVIOURAL OPTIONS\fP. You can also use \fBany\fP of the named
+colors specified in \fB/usr/lib/X11/rgb.txt\fP, though only one word
+versions of them. It is better to stick to the numerical colors
+to limit use of the color palette.
+
+Comments may be included on a line of there own and begin with
 a #.
 
 Because of the simplicity of the implementation, there are a few
-intricacies that will not be coped with correctly, but these are a minor
+intricacies that will not be coped with correctly but these are a minor
 irritation. On the whole, a broad spectrum of quite complicated
 situations are handled with these simple rules. It is a good idea to
 take a look at the syntax file to see some of the nifty tricks you can
 do with a little imagination. If you can't get by with the rules I have
-coded, and you think you have rule that would be useful, please email
-me with your request.
+coded, and you think you have a rule that would be useful, please email
+me with your request. However, do not ask for regular expression
+support, because this is flatly impossible.
+
+A useful hint is to work with as much as possible with the things
+you \fIcan\fP do rather than try to do things that this
+implimentation can't cope with. Also remember that the aim of
+syntax highlighting is to make programming less prone to error,
+\fInot\fP to make code look pretty.
+.PP
+.SH COLORS
+The default colors may be changed by appending to the
+\fBMC_COLOR_TABLE\fP environment variable. Foreground and
+background colors pairs may be specified for example with:
+.PP
+.nf
+MC_COLOR_TABLE="$MC_COLOR_TABLE:\
+editnormal=lightgray,black:\
+editbold=yellow,black:\
+editmarked=black,cyan"
+.fi
 .PP
 .SH OPTIONS
 Most options can now be set from the editors options dialog
@@ -454,7 +482,7 @@ in /pub/Linux/apps/editors/X or at argeas.argos.hol.gr in
 cooledit(1), mc(1), gpm(1), terminfo(1), scanf(3).
 .PP
 .SH AUTHORS
-Paul Sheer (psheer@icon.co.za) is the developer of
+Paul Sheer (psheer@obsidian.co.za) is the developer of
 the Midnight Commander's internal editor.
 .PP
 .SH BUGS