7. DISPLAY MODES

The display mode also affects tag lookup, and image-dependent operations such as determining the column number of the cursor's location, and moving the cursor vertically.

You can list the supported display modes by giving the ":display" command without any arguments. Typically, the supported modes will include the following:

.--------.----------------------------------------------.
|  MODE  | DESCRIPTION                                  |
|--------|----------------------------------------------|
| normal | Traditional vi, displays plain ASCII         |
| syntax | Like "normal" but does syntax coloring       |
| c      | Like "normal" but prettier for C source code |
| hex    | Interactive hex dump, good for binary files  |
| html   | Simple Web page formatter                    |
| man    | Simple Man page formatter, like "nroff -man" |
^--------^----------------------------------------------^

Elvis 2.0 allows each window to be in a different display mode. You can manually change a window's display mode via the ":display mode" command, where mode is the name of a supported display mode. There is also a ":no" command, which is short for ":display normal".

7.1 Options

The display option is associated with a window. It always contains the name of the window's current display mode. You aren't allowed to change the value of this option directly; you must use the ":display mode" command to change the display mode. This option exists solely so that you can write EX scripts which behave differently, depending on the display mode.

The bufdisplay option is associated with a buffer. It should be set to the name of the usual display mode for that buffer. Typically this option will be set from the elvis.arf initialization file, based on the name of the file like this:

	let e=tolower(dirext(filename))
	if e==".c" || e==".h" || e==".cpp" || e<<4==".jav" || e=="awk"
	then set bufdisplay=syntax
	if e<<4==".htm"
	then set bufdisplay=html
	if e==".man" || e==".1"
	then set bufdisplay=man

The bufdisplay mode also affects the ^Wd visual command. This command toggles the window between the normal mode and the bufdisplay mode. If bufdisplay is also set to "normal", then ^Wd will toggle between the normal and hex display modes.

7.2 Normal mode

Tab

The tab character is displayed as a variable number of spaces -- however many are needed to move to the next tabstop position.

Newline

The newline character (linefeed) marks the end of a line.

Other control characters

Control characters other than tab and newline are displayed as a caret and a printable ASCII character. For example Control-A is displayed as ^A, and NUL is displayed as ^@. The delete character is displayed as ^?.

Non-ASCII characters

The appearance of non-ASCII characters (i.e., characters 128-255) is controlled by the nonascii option. By default, most non-ASCII characters are assumed to be ordinary printable characters.

7.3 Syntax mode

7.3.1 Options

.---------------------.-------------------------------------------.
| OPTION NAMES        | AFFECTED TOKEN TYPE                       |
|---------------------|-------------------------------------------|
| commentfont, cfont  | comments                                  |
| stringfont, sfont   | literal strings and character constants   |
| prepfont, pfont     | preprocessor directives                   |
| keywordfont, kfont  | C or C++ reserved words                   |
| functionfont, ffont | identifier followed by '('                |
| variablefont, vfont | lowercase identifier, not ending in _t    |
| otherfont, ofont    | uppercase identifier, or any ending in _t |
^---------------------^-------------------------------------------^

Any text that doesn't fall into one of the above groups (punctuation, mostly) is displayed in the normal font. There is no option that controls this; it is hard coded.

You can use the :color command to choose a color for each font, if you wish. Not all user interfaces support color, but the "x11" and "termcap" interfaces do.

7.3.2 Language specification

The "elvis.syn" file is a text file. In it, blank lines and lines which start with a '#' are ignored. Other lines begin with the name of an attribute. Each language's description begins with an attribute named "language". The following lines (up to the next "language" line or the end of the file) describe that language.

The attributes names are:

language

This word is followed by a whitespace-delimited list of language names. The names are case-sensitive, so you should probably give all names in lowercase so they're easier for the user to type in. The user can indicate which language to use by appending its name to the name of the "syntax" display mode. For example, ":display syntax c++" causes elvis to highlight the text appropriately for C++.

extension

This word is followed by the filename extensions which are commonly used for this language. If the user doesn't specify which language to load, then elvis scans through "elvis.syn" for an extension line which matches the current file name. The extension lines must come immediately after the language line.

keyword

This word is followed by a list of words which should be shown in the keywordfont font. If omitted, then no words are shown in the keywordfont. Long lists can be split into several keyword lines, if you wish. Elvis doesn't care about the order of the words, but the list will be easier to maintain if you keep it alphabetized.

comment

This word is followed by a one- or two-character sequence which marks the beginning of a comment. The comment is assumed to end at the end of the line. Comments are shown in the commentfont font.

It can also be followed by a pair of one- or two-character sequences which mark the beginning and and of comments which can include newlines. Elvis allows you to specify one single-line comment style, plus one multi-line comment style, for each language.

preprocessor

This word is followed by a single character which, when used at the beginning of a line, marks the start of a preprocessor directive. For C, this is the # character. All preprocessor directives will then be shown in the prepfont font. If omitted, nothing is displayed in the prepfont.

function

This word is followed by a single character which, if it appears after a word, indicates that the word should be displayed in the functionfont font. For most languages, this will be a ( character. If omitted, nothing is displayed in the functionfont.

startword
inword

These can be followed by a list of punctuation characters which may appear at the start of a word, or in the remainder of the word, respectively. Letters and digits are always legal in words; you don't need to list them.

other

This word indicates which types of words should be displayed in the otherfont font. If omitted, nothing is displayed in the otherfont. It can be any combination of the following symbols:

.-------------.-------------------------------------------------.
| SYMBOL      | HOW TO RECOGNIZE "OTHER" WORDS                  |
|-------------|-------------------------------------------------|
| allcaps     | length >= 2 chars, no lowercase characters      |
| initialcaps | 1st character is uppercase, some are lowercase  |
| initialpunct| 1st character is punctuation, from "startword"  |
| mixedcaps   | 1st character is lowercase, some are uppercase  |
| final_t     | length >= 3 chars, ends with "_t"               |
^-------------^-------------------------------------------------^

string

This word is followed by a single character, or a pair of single characters, which are used as the quote characters surrounding string literals. For C, this is the " character. String literals will then be displayed using the stringfont font. If omitted, then strings will not be recognized.

character

This word is followed by a single character, or a pair of single characters, which are used as the quote characters surrounding character literals. For C, this is the ' character. This is shown using the stringfont font, like strings. When parsing, the only difference between the two is that characters can't span lines, but strings can.

ignorecase

This word should be followed by true or false. If true, then elvis won't distinguish between uppercase and lowercase letters when testing whether a word is a keyword. If omitted, elvis assumes it should be false.

7.3.3 Example

language java
extension .java .jav
keyword abstract boolean break byte byvalue case cast catch char
keyword class const continue default do double else extends false
keyword final finally float for future generic goto if implements
keyword import inner instanceof int interface long native new null
keyword operator outer package private protected public rest return
keyword short static super switch synchronized this throw throws
keyword transient true try var void volatile while
comment	//
c-comment true
function (
startword _
inword _
string "
character '
other allcaps initialcaps

There is no preprocessor line, because java doesn't use a preprocessor. The "allcaps" and "initialcaps" symbols are given so that constants and class names will be shown in the otherfont.

7.3a C mode

7.4 Hex mode

One handy feature is the ability to enter characters in hex (either in input mode or as the argument to an r visual command) by typing ^X followed by two hex digits. This feature is always available regardless of the display mode... but this is where is it most useful.

7.5 HTML mode

HTML is a markup language. This means that documents contain a mixture of text and formatting instructions. In HTML there are two types of instructions, called tags and escapes. When the document is processed by a program such as Netscape or elvis (in html mode), the tags are are stripped out, the escapes are converted to a kind of text, and the text is formatted and presented to the user. Ordinarily the user will never see the tags.

Since elvis is primarily an editor, not a viewer, it has two options which allow the tags to become visible: the showmarkups option causes a tag to become visible if the cursor is moved onto it, and the list option makes all tags visible regardless of the cursor position.

There are a lot of good "How To Use HTML" documents on the Net. This is not one of them! I don't intend to do much more than describe the quirks of elvis' implementation of HTML here.

I added HTML support to elvis mostly to support the online help. Consequently, if a feature is hard to implement and the online documentation doesn't use it, then I didn't implement that feature.

7.5.1 Formatting tags

<html> ... </html>

The entire document should be enclosed in these tags. They don't actually do anything to help format the document, but they may help programs recognize that the document is in fact written in HTML.

<head> ... </head>

These should be used to bracket the document's header, if it has one.

<title> ... </title>

These tags are only legal in the document's header. Any text between the <title> and </title> tags will be stored internally as the title of the document. If you print the document, elvis will display the title at the top of each page.

<body> ... </body>

These should be used to bracket the body of the document. They don't actually do anything in elvis, but real Web browsers such as Netscape allow you to specify backgrounds and patterns via BGCOLOR=... and BACKGROUND=... arguments, respectively.

<h1> ... </h1>

These tags bracket the most visible type of section header. Elvis displays <h1> ... </h1> headers in boldface, flush against the left edge of the page. When printing, these headers cause a page break.

<h2> ... </h2>

These bracket the second most visible type of section header. Elvis displays <h2> ... </h2> headers in boldface, indented slightly from the left edge.

<h3> ... </h3>

These bracket the third most visible type of section header. Elvis displays them in boldface, indented fully from the left edge so that it lines up with normal text.

<h4>...</h4>
<h5>...</h5>
<h6>...</h6>

These are very minor section headers. Conventional wisdom says that if you're using this many section headers then you would probably do better to split your document into several smaller documents. Elvis displays these headers in an italic font.

<p>

This tag should be placed at the start of each normal paragraph, with the possible exception of the first paragraph after a section header. It causes a blank line to be generated, and any later text to appear starting on a new line.

<br>

This causes any later text to appear starting on a new line. It differs from <p> in that <br> doesn't output a blank line.

<hr>

This outputs a "horizontal rule" -- a line all the way across the page.

<img alt=...>

Elvis can't display graphics, but if it encounters an <img> tag which has an alternate text form, then it'll display the alternate text. Otherwise elvis will display the entire tag, even if all other tags are hidden.

<blockquote> ... </blockquote>

This is used to mark a large chunk text which is quoted from another source. Elvis will indent the enclosed text.

<pre> ... </pre>

This brackets text which has already been preformatted by the document's author. Elvis will treat tabs and newlines literally. (Outside of <pre> ... </pre>, they would normally be treated like spaces.) This has been used for presenting tables, poetry, and source code examples.

In fact, elvis has an extension that is useful for tables: If you start with <pre graphic> then elvis will convert certain characters into graphic line-drawing characters. When adjacent to a hyphen character, the hyphen, period, caret are converted into appropriate graphic characters. Additionally, the vertical bar character is always converted to a graphic character. The following was done with a plain <pre>...

.--.--.
|--|--|
|  |  |
^--^--^

... and this was done with <pre graphic>...

.--.--.
|--|--|
|  |  |
^--^--^

<table>...</table>

<tr>...</tr>

<th>...</th>

<td>...</td>
These are used for implementing tables in HTML 3.0.
Each table should be enclosed in a <table>...</table> pair.
Within the table, each row should be delimited with a <tr>...</tr> pair.
Within each row, the information for each column should be enclosed in
either a <th>...</th> pair for headers,
or a <td>...</td> pair for data.

Elvis doesn't really support these tags very well.
Only the bare essentials of these commands have been implemented.
They are intended to make tables recognizable as being tables,
but not necessarily make them easy to read.

<dir>...</dir>

<xmp>...</xmp>
These are treated almost exactly like <pre> ... </pre>.
There are supposed to be some differences, but elvis doesn't support those differences.

<dl> ... </dl>
These are used to bracket a list of definitions.
The definitions themselves are marked with the <dt> and <dd>
tags, described below.

<dt>
The text after this tag is used as a term to be defined.
Elvis displays this text in bold face, indented by the same amount as
normal text.
This is only legal in a <dl>...</dl> pair.

<dd>
The text after this tag is used as the definition of a term.
Elvis displays it in the normal font, indented somewhat more than
normal text or the <dt> text.
This is only legal in a <dl>...</dl> pair.

<ol> ... </ol>
These are used to enclose an ordered list.
The official specifications say that lists may be nested inside one another,
but elvis doesn't allow ordered lists to appear inside any other type of list.
If a document uses <ol> ... </ol> inside another list,
then elvis will act as though  <ul> ... </ul> had been used instead.
This means that the list items will be marked with bullets instead of numbers.
Within the list, <li> tags are used to mark the items.

<ul> ... </ul>
These enclose an unordered list.
Each item in the list should be marked with a <li> tag.

<menu> ... </menu>
These enclose an unordered list, like <ul> ... </ul>,
but other Web readers may display <menu> ... </menu> lists
in a more compact manner.

<li>
This is used to mark the start of a new item in a list.

<input type=... size=... value=...>

<textarea cols=...>
Elvis can display a mockup of a form, so you can have some idea of how
the form would look on a real browser.
The forms won't really work in elvis!
Elvis displays forms for the sole purpose of helping you define the form layout.
Buttons are displayed as reverse-video characters,
and text input areas are displayed as underlined spaces.
The <textarea> image is always 3 rows high, regardless of any rows=...
value you supply.

<a> ... </a>
There are two forms of this tag:
<a href=URL>...</a> to mark the source of a hypertext
link, and
<a name=name></a> to mark the destination of a hypertext
link.

Elvis doesn't support non-local URLs.
The URL can only contain a filename and/or the name of a <a name=name></a> tag.

<cite> ... </cite>
These enclose a citation.  Elvis displays the citation in italics.

<dfn> ... </dfn>
These enclose a term that is being defined.  Elvis displays the term
in italics.
Netscape doesn't support this tag, so you should probably avoid it.
Use <em> ... </em> instead.

<em> ... </em>
These enclose text which should be emphasized some way.
Elvis displays the text in (you guessed it) italics.

<kbd> ... </kbd>
These enclose text which the user might want to type into the computer
some day.
Elvis displays this text in boldface.

<strong> ... </strong>
These enclose text which should be emphasized a heck of a lot.
Elvis displays this text in boldface.

<var> ... </var>
These enclose text which indicates where some variable argument is to be
placed.  Elvis displays this text in italics.

<address> ... </address>
These enclose an address.  Elvis displays the address in italics.
Note that this is typically used for e-mail addresses and Web URLs,
not postal addresses.

<b> ... </b>
The enclosed text is displayed in bold.
The <strong> ... </strong> tags are the preferred, if you really
want to emphasize text.

<i> ... </i>
The enclosed text is displayed in italics.
The <em> ... </em> tags are the preferred, if you really
want to emphasize text.

<u> ... </u>
The enclosed text is displayed underlined.
You should avoid using this tag, because underlining is also used to
indicate hypertext links.  The <u> ... </u> text would look like
a hypertext link but wouldn't work like one.

<tt> ... </tt>
The enclosed text is displayed in normal font.
Other HTML readers make the distinction of displaying the text in a
monospaced
normal font, but since elvis always uses monospaced fonts, the distinction is
lost.
These tags are typically used for marking computer commands when they're
mentioned in the body of a paragraph.

Note that most of these tags come in pairs, and the ending tag's name includes a '/' character. Elvis doesn't verify that the pairs match up correctly. Because of this, I strongly suggest that you preview your document using a more powerful HTML viewer such as Netscape before sharing it with the world.

7.5.2 Character escapes

Many of the escapes are automatically derived from the digraph table. If you don't know about digraphs, you should look up the :digraph command, and the discussion on how to use them in input mode.

Elvis supports the following character escapes:

&lt; or &LT;

The < character.

&gt; or &GT;

The > character.

&amp; or &AMP;

The & character.

&quot; or &QUOT;

The " character.

&nbsp; or &NBSP;

A non-breaking space. This is displayed as a space character. It differs from plain old whitespace in that &nbsp; can't be converted into a line break.

&copy; or &COPY;

The copyright symbol. Elvis looks for a digraph which combines the letters C and O. If there is no such digraph, then elvis uses C.

&AELIG;

A digraph combining the letters A and E. If no such digraph has been defined, then elvis will display E.

&aelig;

A digraph combining the letters a and e. If no such digraph has been defined, then elvis will display e.

&ETH;

A digraph combining a hyphen and the letter D.

&eth;

A digraph combining a hyphen and the letter d.

&THORN;

A digraph combining the letters T and P, or just plain P if there is no such digraph.

&thorn;

A digraph combining the letters t and p, or just plain p if there is no such digraph.

&szlig;

A digraph combining the letters s and z, or just plain z if there is no such digraph.

&lettergrave;

A digraph combining the ` and letter.

&letteracute;

A digraph combining the ' and letter.

&lettercirc;

A digraph combining the ^ and letter.

&lettertilde;

A digraph combining the ~ and letter.

&letteruml;

A digraph combining the " and letter.

&letterring;

A digraph combining the * and letter.

&lettercedil;

A digraph combining the , and letter.

&letterslash;

A digraph combining the / and letter.

&#number;

The character whose ordinal value is number. This should be avoided, because you can't be sure which symbol set will be used when somebody else views the document. Some documents use &#160; which is a "hard" space in the ISO Latin-1 character set, but they should really use &nbsp;.

If your document uses a character escape which elvis doesn't support, then elvis will not convert that escape into a single character; instead, it will be displayed literally.

If elvis looks for a digraph containing a punctuation character and a letter, and no such digraph has been defined, then elvis will use the plain ASCII letter.

7.5.3 Using hypertext

The HTML hypertext has been implemented as a variation on the standard vi :tag command. Consequently, all of the wonderful commands that elvis offers for browsing C source code can also be used for browsing HTML documents.

In EX mode, you can use :tag URL to pursue a hypertext reference, and :pop to come back afterward.

In VI mode, you can move the cursor onto the underlined text which denotes a hypertext reference, and hit ^] to pursue the reference, and ^T to come back afterward. Also, when in html mode the Tab key searches forward for the next hypertext reference, and the Enter key performs tag lookup just like the ^] key.

If you're using the "x11" user interface, then you can double-click button 1 to follow a hypertext reference, and double-click button 3 to come back afterward. This also works under Win32, because the Win32 version of the "termcap" interface supports the mouse.

7.6 Man mode

Elvis supports only a tiny subset of the troff commands and -man macros. It is adequate for a surprising number of man pages, though. The most notable failing is the lack of number/string registers.

Commands which start with a "." are only recognized at the start of a line. The remainder of the line is used as arguments to the command. Commands which start with a "\" are recognized anywhere.

.\" comment

Elvis ignores any text on a .\" command line.

.TH name section

This command should appear at the top of the man page. It declares the name of the program to be described, and the section of the manual where it should appear. User programs are usually documented in section 1.

.SH name

The name is displayed as a section header. If name contains whitespace, then it should be enclosed in quotes. Man pages usually have sections named NAME, SYNOPSIS, DESCRIPTION, OPTIONS, FILES, ENVIRONMENT, "SEE ALSO", BUGS, and AUTHOR, in that order. The "elvis.man" file is a typical example.

.SS name

The name is displayed as a subsection header. If name contains whitespace, then it should be enclosed in quotes. Man pages rarely use subsections.

.B text

The text is displayed in boldface.

.I text

The text is displayed in italics.

.SM text

Troff would display the text in a slightly smaller font. Elvis doesn't support multiple font sizes, though, so it simply outputs the text.

.RB text1 text2 ...
.BR text1 text2 ...
.RI text1 text2 ...
.IR text1 text2 ...
.BS text1 text2 ...
.SB text1 text2 ...

These output the argument text, alternating between two fonts. For example, .BR outputs the first argument word in boldface, the second in normal (a.k.a. Roman), the third in boldface again, and so on. The "S" font is supposed to be small, but elvis uses the normal font for that. All whitespace is removed from between the argument words.

.IP label

This starts an indented paragraph. The label, if given, is output before the paragraph, and without indentation. This is typically used for presenting a term (the label) and its definition (the paragraph).

.TP

This starts a hanging paragraph. That's like a .IP indented paragraph, except the label is declared on the line following the command, instead of on the command line itself. The body of the paragraph starts on the second line after the command line.

.P
.LP

Either of these will start a regular paragraph.

.RS
.RE

These start and end a relative indentation, respectively. In other words, .RS increases the indentation of any subsequent text, and .RE reduces indentation.

.br

This causes a line break.

.sp

This causes a line break, and then leaves a blank line.

.nf
.fi

These turn "fill mode" off and on, respectively. When fill mode is turned off, elvis will perform much less formatting. It is similar to the <pre>...</pre> tags in HTML.

\e

This is replaced by the backslash character.

\|
\&

These are deleted. If you ever feel a need to put a period at the start of a line, and don't want it to be treated like a command line, then put \&. in your file. The \& will prevent the period from being interpreted as the start of a command line, but will not show in the output.

\fB
\f1

Switch to boldface.

\fI
\f2

Switch to italics.

\fR
\f0

Switch to the normal font.

\fP

Switch to the default font for this context. That's boldface in headings, and normal the rest of the time. Actually, \fP is supposed to switch to the "previous" font, whatever that was, but elvis doesn't do it that way.

\character

When character is something other than one of the above, output the character. In particular, \\ outputs a single backslash.

Troff source was never designed to be interactively edited, and although I did the best I could, attempting to edit in "man" mode is still a disorienting experience. I suggest you get in the habit of using "normal" mode when making changes, and "man" mode to preview the effect of those changes. The ^Wd command makes switching between modes a pretty easy thing to do.

Unrecognized commands which start with "." are silently ignored.

Unrecognized commands which start with "\" will be output without the initial "\" character. This falls far short of the ideal, but there are just too many weird escapes to bother implementing in something that isn't being advertised as a troff clone. (NOTE: Elvis is not a troff clone.)

A tip: If your document contains sequences which look like \*X or \*(XY (for any characters X and Y), then it is trying to use defined strings. Look for a ".ds X foo" command near the top of the document to find out what that string is supposed to look like. The string \*(bu is a bullet character.