THE HELP SYSTEM

satellite carries its own help. You ask for it at the satl prompt, the place where you type one line and see it run straight away, and it answers with a page of plain text about one part of the language: what it is, the rules, and an example program.

Opening the prompt and asking

Start the prompt with satl --repl. Then type satellite.help() on a line of its own to see every topic there is:

satl --repl

satellite.help()

--------------------------------------------------------------------------------
 THE SATELLITE HELP SYSTEM
--------------------------------------------------------------------------------
 usage: type satellite.help(include) or satellite.help(satellite.include)
 to bring up info on including other files
TOPICS:

1) satellite.include (other files)

2) satellite.help (the help system)

3) satellite.capsule (functions)

The list goes on through 28 topics, from numbers and strings to spacesuits, windows and the terminal. To read one, put its name between the brackets. You can name a topic in several ways:

• by its whole name: satellite.help(satellite.include)
• by its last part: satellite.help(include) finds the same topic
• by a second spelling: satellite.help(colour) finds satellite.variable.color, and satellite.help(double) finds satellite.variable.float
• by the start of its last part: satellite.help(percentage) finds satellite.variable.percent

satellite.help(help) brings up the help system’s own page. exit, quit or Ctrl-D leaves the prompt.

When a name fits two topics, or none

Two topics end in window, so satl will not guess which one you meant. It names both and lets you choose:

satellite.help(window)
satl(prompt): window is more than one topic -- write satellite.help(satellite.variable.window) or satellite.help(satellite.window)
satellite.help(unicorns)
satl(prompt): there is no help on unicorns yet -- satellite.help() lists the topics there are

Help is for the prompt, not for a program

satellite.help is something you ask satl, not a statement your program runs. Written inside a program, it is refused before the program starts:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.help(library)
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S210: NOT_BUILT_YET
satl(check): in satellite.main, satellite.help has no library built for it yet

directory: ask_for_help.satl:5
syntax: satellite.help(library)
        /\

this word is numbered in the language and the library behind it does not exist
yet. The word is right; there is nothing yet to run.
machine code 14 not_built_yet -- satl exits with this.

--------------------------------------------------------------------------------

At the prompt it also has to be the whole line: satellite.console.display(satellite.help()) is refused, and satl says that help is written on a line of its own.

Every topic ends in a program you can run

Each topic finishes with an example. The examples are real programs: save one as a .satl file and run it with satl. This is the example from satellite.help(library):

satellite.include(satellite)

satellite.library.rounds = 4
satellite.library.label = "rounds counted"

satellite.capsule satellite.main()
{
    satellite.variable.number count = 0
    satellite.statement.while (count < satellite.library.rounds)
    {
        count = count + 1
    }
    satellite.console.display(satellite.library.label)
    satellite.console.display(count)
    satellite.return(satellite)
}

rounds counted
4

Comments in an example, such as // 42, often show what a line prints, so you can check your run against the page.

Help is plain text, and it is yours

Every topic is a plain text file, read at the moment you ask for it and never built into satl. That means you can open them, read them in any editor, and change them. The next time you ask, you get your version.

The files live in a folder named satellite.help:

• satellite.help/help.txt is the list that satellite.help() prints.
• Each topic is a folder named after it, holding a file called help_text.txt. The include topic is satellite.help/satellite.include/help_text.txt.
• A new folder is a new topic. Make satellite.help/my_notes/help_text.txt, and satellite.help(my_notes) shows it. Add a line to help.txt if you want it in the list too.

satl looks for the satellite.help folder beside the satl program, or one folder up from it. If it finds neither, it tells you so and names both places it looked:

satellite.help(include)
satl(prompt): the help files are not beside satl -- looked in ~/.satl/satellite.help and ~/.satl/../satellite.help

Where next

The FULL REFERENCE collects the whole language on one page. For the prompt and satl’s other options, see THE SATL COMMAND. The library example above is explained in SATELLITE.LIBRARY.