Man terminal controls

From LSWiki

(Difference between revisions)

Revision as of 17:37, 11 June 2007

Files

/std/def/term.c

Description

The Ain Soph terminal processing subsystem supports several types of terminal processing controls. The best-known type is the color control, which is covered in great detail in 'help color'. This document exists to describe the four other types of control: format, indent, justify, and column controls.

The reason this is done in developer documentation rather than a help file is that players are largely unable to use these types of control, as the terminal code analysis applied to relevant commands denies their use, and in the relatively unusual situations where they can use them, it's really best if they don't. These controls are for the use and convenience of developers.

The simplest of the types is the format control. These appear in two forms: {{format on}text} and {{format off}text}. Of the two, only the ability to turn formatting off sees much use. What these controls enable you to do is turn the formatting element of terminal processing (the portion that introduces line breaks into text to prevent line overruns) on and off within a string, letting you mix text that should be formatted and text that shouldn't within the same string. The most common application of this is disengaging formatting when producing preformatted reports that extend far enough to the right that the terminal processing code would otherwise introduce line breaks, ruining the layout.

Next come indent controls, which are more complex. These controls allow you to apply automatic indentation to the terminal processing's formatting. A very simple example is {{indent 2}text}, telling the system to indent two spaces each time a line break is generated or encountered within the affected text. In the case of paragraph breaks (\f characters), the indentation level is added to the normal 4-space indent for paragraph breaks. The full set of the forms these controls can take, and modifiers to those forms, is:

{{indent N}text}, e.g. {{indent 2}text}

   Indent to the specified number of spaces.

{{indent +N}text}, e.g. {{indent +2}text}

   Add the specified number of spaces to the current indentation level.

{{indent -N}text}, e.g. {{indent -2}text}

   Subtract the specified number of spaces from the current indentation level.

{{indent N%}text}, e.g. {{indent 20%}text}

   Indent to the specified percentage of the viewer's available screen width.

{{indent +N%}text}, e.g. {{indent +5%}text}

   Add the specified percentage of the viewer's available screen width to the current indentation     
   level.

{{indent -N%}text}, e.g. {{indent -5%}text}

   Subtract the specified percentage of the viewer's available screen width from the current 
    indentation level.

{{indent here}text}

   Indent to the current horizontal position of the text on the viewer's screen.

{{indent here +N}text}, e.g. {{indent here +2}text}

   Indent to the current horizontal position of the text on the viewer's screen plus the specified 
    number of spaces.

{{indent here -N}text}, e.g. {{indent here -2}text}

   Indent to the current horizontal position of the text on the viewer's screen minus the specified 
   number of spaces.

{{indent here +N%}text}, e.g. {{indent here +5%}text}

   Indent to the current horizontal position of the text on the viewer's screen plus the specified 
    percentage of the viewer's screen width.

{{indent here -N%}text}, e.g. {{indent here -5%}text}

   Indent to the current horizontal position of the text on the viewer's screen minus the specified 
   percentage of the viewer's screen width.

{{indent ...!}text}, e.g. {{indent +2!}text}

Modify any of the above forms so that, if we are at the beginning of a line, our current position is moved to conform to the new indentation level immediately, rather than waiting for the next line break. When the indentation ends, if we are at the beginning of a line, also immediately adjust our current position to the indentation level we are returning to.

Some sanity checks are applied to indentation controls. The indentation level is not allowed to pass below zero, and is also not allowed to pass above four-fifths of the viewer's screen width (meaning, among other things, that the maximum percentage-based indent specification is {{indent 80%}text}; anything above that has the same effect as a specification of 80%).

Justification controls provide the ability to perform text justification, using left, right, or center alignment in a given number of columns. Each justification control specifies an alignment and a number of columns. The number of columns will be capped at the viewer's screen width. Justification controls will not generally interact very intelligently with line wrapping, and so are best used in preformatted-text situations. The forms justification controls take are:

{{justify align N}text}, e.g. {{justify left 20}text}

   Justify the enclosed text within the specificed number of columns.

{{justify align N%}text}, e.g. {{justify center 20%}text}

   Justify the enclosed text within the specificed percentage of the
   viewer's screen width.

Last are column controls, which are used to shift the current column position of text to a specified point. (Technical point: if, on a blank line, a column shift to column 20 is done, 19 spaces will be produced so that the text to follow is located at column 20.) If the column is shifted to the left, any text in the intervening space is lost. Unlike other controls, column controls do not enclose text. The full set of the forms these controls can take, and modifiers to those forms, is:

Template:Column N, e.g. Template:Column 20

   Shift the current column to the specified column.

Template:Column +N, e.g. Template:Column +2

   Shift the current column N columns right.

Template:Column -N, e.g. Template:Column -2

   Shift the current column N columns left.

Template:Column N%, e.g. Template:Column 50%

   Shift the current column to N percent of the viewer's screen width.

Template:Column N%, e.g. Template:Column 5%

   Shift the current column right by N percent of the viewer's screen width.

Template:Column -N%, e.g. Template:Column -5%

   Shift the current column left by N percent of the viewer's screen width.

The current column cannot be shifted left of 1 or right of the viewer's screen width.

The greatest application of these controls is in formatting various kinds of out-of-character report; it is rarely useful or appropriate to apply them to in-character output. For example, they are used extensively in the reports gathered together in the 'show daemons' command. Where they apply, they can make life much easier, removing the need to write nitpicky code to preformat strings to a desired width and manage the indentation by hand. However, you are strongly encouraged to test your usage of them to ensure that they are behaving as expected, since if you miswrite an indent control, unless you go to the trouble to pass the string through error analysis, it will silently fail (no error message will be issued) and therefore the broken control may go unnoticed until the data associated with a particular situation bring it into play.

Retrieved from "http://wiki.lostsouls.org/Man_terminal_controls"

Man terminal controls

From LSWiki

Revision as of 17:37, 11 June 2007

Files

Description

Views

Personal tools

Navigation

Search

Toolbox