SF
==

Overview
--------

The ``sf`` (or Show File) application displays a text file through a
logical window which can be moved forward and backward on the file.
The utility is invoked by using the ``sf`` command or through the
``show`` application.

If the ``sf`` application is invoked without specifiing a file name,
the following prompt requesting a file is displayed.

``Show File - Enter pathname:``

The screen format is very simple with a command line at the top of
the screen, a display window consisting of the middle rows of the
screen, and a file identification line at the bottom of the window.
The identification line gives the line and column number of the top
left character in the window. An example of the command line and
information line is given below.

``F1-Down, F2-Up, F3-Top, F4-Bottom, Config, Find, Help, Position, Quit, Wrap-on``

``File = /home/robert/sf.txt  Top = 1:1``

The end of the file is indicated by a "``*eof``" line displayed in
the file window after the last line of the file.

Command line arguments
----------------------

``-w``, ``--wrap`` Enables line wrapping.

``--theme``\ =[THEME]: Color themes. Passsing this argument
  without an option will display available themes.

``--settings-menu``
Launch ``sf`` directly into the settings menu.

``--help``: Displays help message, then exits.

``--version``: Displays program version, then exits.

Commands
--------

The ``sf`` application provides functions to move the window up or
down on the file being displayed. These functions are invoked by
function keys specified before the function name. Commands are
provided to position the window to a spesific line of the file and to
quit the utility. These commands are invoked by using the first
letter of the command name. Each of the commands and functions are
described below.

``F1``, ``PgDn``
  Move the file window down or forward on the file by the size of
  the display to show the next section of the file.

``F2``, ``PgUp``
  Move the file window up or backward on the file by the size of the
  display to show the previous section of the file.

``F3``
  Top of File - Position the file window to the first line of the
  file.

``F4``
  Bottom of File - Position the file window to the last line of the
  file.

``Config``
Launches ``sf``\ 's configuration menu. From here, all aspects of ``sf``
can be configured, and settings saved so they will persist between sessions.
Further information can be found in the `configuring sf <#configuring-sf>`__ section.

``Find``
  Searches for a string provided in the form of a Regex. Case
  sensitivity is requested by the following prompt, afterwards the
  user is asked to input the string to search. To abort at this
  prompt, the *ESC* key must be used.

  ``Ignore-case Case-sensitive (enter = I)``

  Following this selection, one of the following prompts will be
  displayed:

  ``Match Case - Enter string:``

  ``Ignore Case - Enter string:``

  After a search has been made, the keybinding ``CTRL + F`` will repeat the search
  to find further occurrences.

``Help``
  Launches the ``man`` pages for ``sf``.

``Position``
  Position the file window to a specific line of the file or
  relative from the current file position. The new file postion is
  requested by the following prompt.

  ``Position relative (+num || -num) or absolute (num):``

  If a number without a plus "+" or minus "-" sign is specified,
  then the file window is moved to the specified line number if it
  exists. If a number with a plus "+" sign is specified, then the
  file window is moved down or forward by the specified number of
  lines. Otherwise if a number with a minus "-" sign is specified
  then the file window is moved up or backward by the specified
  number of lines.

``Quit``
  Terminate the ``sf`` application and return to the utility which
  invoked it, or the user's terminal.

``Wrap-on``, ``Wrap-off``
  Toggles line wrapping on or off. When enabled, the information
  line only shows the line number.

``Home``
  Position the file window to the first column of the file.

``End``
  Position the file window to the last column of the file.

Configuring sf
--------------
``sf`` features an inbuilt configuration menu where the user can tweak
the default settings. It is accessed using the Config command.

The following screen is displayed.

::

   SF Settings Menu - Quit, Revert, Save

      [ ] Enable text wrapping

The menu is made up of toggle switches. When active, the switch will display
``[*]``, when inactive ``[ ]`` is displayed. To toggle a value, press *SPACE*
when the cursor is highlighed over a specific item.

The following commands can be used within this menu.

``Quit``
Applies changes and either returns to the previous screen.

``Revert``
Reverts settings to their original value from when the settings menu was
invoked.

``Save``
Saves settings for future sessions.
