iconv: Bail out of the loop when an illegal sequence of bytes occurs.
[elinks/elinks-j605.git] / doc / terminals.txt
blob7c03f41d8f62859d231be2f1f34d7defcb7ccc46
1 The Terminal Setup
2 ------------------
4 ELinks uses neither (n)curses nor termcap/terminfo, so unless you are using
5 a terminal that is known by ELinks and have a built-in configuration (see below
6 for a list), it might be required that you do a little configuring of how your
7 terminal should be handled.  The easiest way to do this is by using the Terminal
8 Options dialog located in the Setup submenu of the Main menu.
10 It is possible to have configurations for multiple terminals as long as the TERM
11 environment variable -- used to distinguish terminals from one another -- is set
12 to something different for each terminal.  So be sure to set TERM to different
13 values for two terminals that cannot share the same configuration.  For example,
14 always setting TERM to xterm-color can lead to problems if you run ELinks under
15 the Linux console.  This is because the Linux console does not support
16 underlining and ELinks will not know that underlined characters will have to be
17 color highlighted so they stand out.
19 In short, ELinks does not use termcap or terminfo.  ELinks uses $TERM, but only
20 to distinguish between terminals in its own configuration.  That is, you need
21 only configure your terminal within ELinks: Go to the Setup menu and select
22 Terminal Options.  If $TERM is set to 'screen' when you configure ELinks'
23 terminal settings, ELinks will remember to use those settings when $TERM is
24 'screen'.
27 Options
28 ~~~~~~~
30 Apart from the last charset option configurable through the Setup -> Character
31 Set submenu in the Main menu, the rest can be configured using the Terminal
32 Options dialog.
35 Terminal type
36 ^^^^^^^^^^^^^
37                 
38 It maps roughly to the terminal type, such as Linux console, XTerm, VT100 etc.
39 It matters mostly when drawing frames and borders around dialog windows.  As
40 already mentioned, it also turns on certain features which try to compensate for
41 ``missing'' terminal capabilities when drawing.  Special highlighting of
42 underlined text if underlining is not supported is one such thing.
44 `-----------------------`-----------------------------------------------------
45 Type                    Notes
46 ------------------------------------------------------------------------------
47 No frames               Dumb terminal type / ASCII art
48 VT 100 frames           Works in most terminals
49 Linux or OS/2 frames    Linux console / you get double frames and other goodies
50 KOI-8
51 FreeBSD                 FreeBSD console
52 ------------------------------------------------------------------------------
54 The default is to assume dumb terminal/ASCII art.
57 Color mode
58 ^^^^^^^^^^
60 The color mode controls what colors are used and how they are output to the
61 terminal.  The available color modes are:
63 `-----------------------`-----------------------------------------------------
64 Mode                    Color codes
65 ------------------------------------------------------------------------------
66 Mono mode               Only 2 colors are used
67 16 color mode           Uses the common ANSI colors
68 88 color mode           Uses XTerm RGB codes (if compiled in)
69 256 color mode          Uses XTerm RGB codes (if compiled in)
70 ------------------------------------------------------------------------------
72 The default is to use mono mode.
75 Switch fonts for line drawing (aka 11m hack)
76 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
78 This is related to the drawing of frames and window borders controlled by the
79 option above.  It controls whether to switch fonts when drawing lines, enabling
80 both local characters and lines working at the same time.
82 This boolean option only makes sense with the Linux console.  Off by default.
85 Restrict frames in cp850/852
86 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88 This is related to the drawing of frames and window borders controlled by the
89 option above.  If enabled, it restricts the characters used when drawing lines.
91 This boolean option only makes sense with the Linux console using the cp850/852
92 character sets.  Off by default.
95 Block cursor
96 ^^^^^^^^^^^^
98 Move cursor to the bottom right corner when done drawing, if possible.  This is
99 particularly useful when we have a block cursor, so that text colors are
100 displayed correctly.  If you are using a screen reader you do not want to enable
101 this since the cursor is strategically positioned near relevant text of selected
102 dialog elements.
104 This boolean option is off by default.
107 Transparency
108 ^^^^^^^^^^^^
110 Determines whether or not to set the background to black.  This is particularly
111 useful when using a terminal (typically in some windowing environment) with
112 a background image or a transparent background.  If this option is enabled the
113 background will be visible in ELinks as well.
115 Note that this boolean option makes sense only when colors are enabled.  On by
116 default.
119 Text underlining capability
120 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
122 This boolean option controls whether to underline text or instead, enhance the
123 color.
125 Note: not all terminals support text underlining, so it is off by default.
128 UTF-8 I/O
129 ^^^^^^^^^
131 This boolean option controls outputting of I/O in UTF-8 for Unicode terminals.
133 Note that currently, only a subset of UTF-8 according to the terminal
134 codepage is used.  This is off by default.
137 Character Set
138 ^^^^^^^^^^^^^
140 Codepage of the charset used for displaying content on terminal.
142 The value 'System' (which is the default) will set the charset according to the
143 current locale.  The default is to use the charset of the current locale.
146 Terminal Configurations
147 ~~~~~~~~~~~~~~~~~~~~~~~
149 Built-in configurations exists for the following terminals:
151  - linux
152  - vt100
153  - vt110
154  - xterm
155  - xterm-color
156  - xterm-88color
157  - xterm-256color
159 The last two configurations requires that support for either 88 or 256 colors
160 is compiled in to xterm.
162 GNU Screen is VT100-compatible, so select 'VT 100 frames'.  GNU Screen also
163 supports colors just fine, so select '16 colors', or, if you are running Screen
164 within a terminal emulator that supports 256 colors and you have compiled both
165 Screen and ELinks to support it, choose '256 colors'.