

 sysline  --  status-line display utility for Linux


 INTRO
 -----
 This is a Linux port of the BSD sysline utility. The original sources are
 included here in ./BSD.


 SPARE ME THE DETAILS
 --------------------
 If you're in a hurry to install:

 0. in this example, let CC be the number of columns, RR the number
    of rows on you terminal, and rr be equal to RR-1
 1. run Configure and "make install" (compile for use of /etc/termcap)
 2. do "make.termcap-entry >file" (answer CC and RR respectively)
 3. add the entries in file to /etc/termcap (replace "con-unk" as necessary)
 4. do "stty rows rr" on the vt where you want to run sysline
 5. do "TERM=80xRR-s" (for bash, zsh) or "set term=con80xRR-s" (for csh) on
    that vt
 6. do "sysline +10" on that vt
 7. check if the status-line isn't messed up, by doing "ls -la", "less
    <something>", etc.
 8. do "echo 'I did it!!!' >~/.who"
 9. read man-page

 INSTALL
 -------
 The program assumes presence of the /proc file-system; if you don't
 have it, you might consider recompiling your kernel.

 Run ./Configure to make Makefile and config.h.

 The file config.h has some #defines which you may want to change to
 suit your taste.

 Running `make' will compile sysline, `make install' will install
 sysline and sysline.1 in the paths as per the Makefile (if you
 install by hand, run strip on the binary first). If you want to have
 `cs' installed as well (see below), edit the Makefile accordingly.

 If `make' fails with an error like:
 ``*** commands commence before first target.  Stop.''
 you prob. need to remove tabs from empty lines in the Makefile
 (either that or get a newer version of make; make-3.73 has fixed
 this).

 After having installed sysline, run either of the make.termcap-entry
 or make.terminfo-entry scripts (or both), and add the output to the
 termcap and/or terminfo database (see below).


 TERMCAP/TERMINFO REQUIREMENTS
 -----------------------------
 Your termcap file or terminfo file -whichever you've compiled
 sysline to use- might be lacking some capabilities that sysline
 needs/appreciates. Here's an overview.

 The following capabilities are absolutely 100% essential:
 termcap capability	terminfo equiv.  meaning
 ------------------	---------------  -------
 hs			hs	         terminal has status-line
 es			eslok	         escapes in status-line ok
 ts			tsl	         move to status-line
 fs			fsl	         move from status-line
 ds			dsl	         clear status-line


 The following capabilities are prob. already defined some place, and
 can be used unchanged; just check if you have them:
 termcap capability	terminfo equiv.  meaning
 ------------------	---------------  -------
 so			smso	         begin standout (reverse) mode
 se			rmso	         end standout (reverse) mode
 ce			el	         clear to end-of-line
 bl			bel	         audible signal (bell)


 These too are capabilities which prob. are already defined some
 place, but which need modifications:
 termcap capability	terminfo equiv.  meaning
 ------------------	---------------  -------
 cs			csr		 set scroll-region
 cl			clear		 clear screen and home cursor
 cd			ed		 clear to end-of-screen     (*
 cm			cup		 move cursor to row, column (**
 ho			home		 home cursor		    (**
				(*  only for a top status-line
				(** only for a bottom status-line


 The following capabilities are also used by sysline, if they are
 defined; i2 better be present when you're not using the `cs' script
 (see below); ws#80 can normally be left out, unless you want a
 shorter status-line:
 termcap capability	terminfo equiv.  meaning
 ------------------	---------------  -------
 i2			is2	         initialization string
 ws#80			wsl	         width of status-line


 In modifying termcap (or the terminfo database file), the most
 convenient is to add referring entries to the file.

 Such entries, having all of the capabilities mentioned here, can be
 created quickly for any size terminal with the scripts
 make.termcap-entry and make.terminfo-entry. These scripts make a
 referring entry for a status-line on the bottom-line and an
 additional entry for a status-line on the top line of the screen.

 One note about the 'cd' capability-string. This should really clear
 from the cursor to the end-of-screen (\E[J), however, what these
 scripts generate (\E[K) clears only to the end-of-line. Since
 clearing to the end-of-screen will temporarily erase the status-
 line, this prevents that from happening but has the side-effect that
 other programs may clear too little. So comment out this modified
 'cd' (by placing a period in front of it: .cd) depending on which
 annoys you more (if only there were a way we could clear from the
 cursor to a specific position; I didn't find any, but am open to
 suggestions, even the less elegant ones).

 Also note that the entries produced by these scripts refer to entry
 'con-unk' only as an example; change to whatever is appropriate.


 COLORIZING THE STATUS-LINE
 --------------------------
 You can give the status-line most any color you like by setting an
 environment variable SYSLINE_COLORS (or, if that's greek to you,
 SYSLINE_COLOURS).
 [The plural form of this variable is a change from the previous
 release!]

 This variable is expected to contain the values of attributes and
 colors of both the normal status-line and the reversed status-line.

 The format of its value is "rv=aa[;bb[;cc...]]:nm=zz[;yy[;xx...]]"
 where aa, bb, ... and zz, yy, ... each represent a color attribute
 or (foreground or background) color, separated from one another by a
 semi-colon. The attributes/colors following "rv=" are for the
 reversed status-line (the one displayed most of the time), those
 following "nm=" are for the normal (un-reversed) status-line (the
 one that will only show every fifth display - I know this seems
 counterintuitive)). For clarity, separate the "rv=" part from the
 "nm=" part with a character like a blank or a colon; the order of rv
 or nm is unimportant. Each should define no more than 8 attributes
 or colors.

 An example: to have a bold/blue-bg/yellow-fg status-line which
 becomes a bold/red-bg/white-fg status-line every fifth display, I'd
 do SYSLINE_COLORS="rv=1;44;33:nm=1;41;37" on that vt.

 Note that fancy colorization of the normal status-line defeats the
 purpose of displaying this status-line in normal video, namely to
 give the screen a rest every 5th display.

 Attributes are as follows (incomplete):

	0 = all attributes off
	1 = intensity 2 (bold)
	2 = intensity 0 (half-bright)
	4 = underline on
	5 = blink on
	7 = reverse on

 Color codes are as follows:

	color		foreground	background
	-----		----------	----------
	black		30		40
	red		31		41
	green		32		42
	yellow		33		43
	blue		34		44
	magenta		35		45
	cyan		36		46
	white		37		47


 OPERATION
 ---------
 Each time before starting sysline you need to take some precautions
 to ensure that other programs don't interfere with the status-line.
 This may involve setting a scroll-region, but at least involves
 doing `stty rows N', where N is the number of rows (lines) in the
 scroll-region.

 If you have the 'i2/is2' capability in your termcap/terminfo entry
 defined, sysline will set the scroll-region itself upon startup. The
 only thing you have to do then before starting sysline is `stty rows
 N', N being 1 less than the number of lines on the terminal.

 If on the other hand you have commented out or deleted the 'i2/is2'
 capability from the termcap/terminfo database, you also need to set
 the scroll-region yourself, in addition to making the stty call,
 before starting sysline. The `cs' script will do both; as arguments
 it takes the first and last line of the scroll-region.

 Note: if you're going to use `cs', you might want to take a look at
 it, for it can use either GNU's termcap-based `tput', or ncurses'
 terminfo-based `tput'. If neither is found, it uses its own strings.

 Example for a 80x30 terminal:
 ------------------------------

 to add status-line:

 1. stty rows 29	(or `cs 1 30')
 2. TERM=con80x30-s	(for bash, zsh; for csh: "set term=con80x30-s")
 3. sysline		(will set scroll-region through i2/is2 capability)

 to remove status-line:

 1. kill -HUP <sysline_pid>
 2. TERM=con80x30	(for bash, zsh; for csh: "set term=con80x30")
 3. stty rows 30      \	(back to full-screen)
 4. tput csr 1 30     /	(or `cs 1 30') (reset scroll-region to normal)


 FURTHER NOTES AND HINTS
 -----------------------
 * To run sysline in a 1-line xterm, your termcap/terminfo database
   file does not need any of the above mentioned capabilities; just
   start sysline with the -w flag and resize the window any way you
   like, preferably to 1 line.
   Running sysline without the -w flag in a larger xterm -which does
   require all the capabilities to be present in the xterm entry-
   doesn't make much sense, unless you never intend to resize that
   particular window, because if you do, your status-line will
   disappear and move around.

 * If you're using sysline compiled for terminfo and you changed the
   contents of the terminfo database file, do not forget to run 'tic
   <terminfo_file>' to compile the contents of that file and make
   your changes take effect.
   Similarly, if you're using sysline with termcap, and have a
   TERMCAP environment variable set, and it contains the full
   terminal description, you have to actually logout or do `eval
   `tset -s`' to make the changes take effect.

 * To clear the screen without it -albeit temporarily- removing the
   status-line, you can just use the 'tput clear' command.

   A terminfo-based `tput' comes with the ncurses package; a
   termcap-based `tput' (which accepts the same terminfo capability
   names as the ncurses `tput') can be found in GNU's
   tput-1.0.tar.gz.

 * Also, to reset the screen without it removing the status-line, you
   can use the `reset' script that comes with the util-linux package,
   which uses `tput' (since ncurses' terminfo-based `tput' and GNU's
   termcap-based `tput' accept the same capability names, this script
   can be used for both).

 * To force an update of the status-line, do `kill -ALRM <sysline-pid>'.

 * If you run sysline as root, it may continue to run after you log
   out (without it actually updating the status-line anymore). This
   happens with getty_ps at least (2.0.7c and later), not with
   getty4.32 by Fred van Kempen; I don't know about other getty's,
   nor why they behave so differently and what would be correct. To
   avoid this, you could start it like:

	       	sysline -i >~/sysline.pid
   and then have:
		if [ -e ~/sysline.pid ]
		then
			kill -HUP `cat ~/sysline.pid` 2>/dev/null
			rm ~/sysline.pid
			cs 1 25
		fi

   in your ~/.logout file, or something more elaborate.

* Hardscroll (Shift-PgUp/Dn) does not work on vt's with a
  status-line. This is normal (I never use it anyway).

* Check you termcap file for trailing whitespace on lines which are
  part of an entry, if programs start behaving erratically.

* Individual capabilities in the termcap and terminfo databases can be
  commented out by placing a period just before the capability name.



 FEEDBACK
 --------
 Questions, bugs, comments, suggestions, flames to yours truly.

 Enjoy.

				- BJ
				``in the software business since tuesday''
				bjdouma@xs4all.nl (Bauke Jan Douma)
