# Dusk OS documentation

## In-system help

If you see this after having typed "help", what you see is the result of the
unit [text/help] having invoked [text/ged] to open doc/index.txt. You are now
in the "ged" text editor. You can quit it with 'q'.

You can scroll up and down with '[' and ']' and move the cursor with 'h/j/k/l'.
You can follow links (for example, [lib/str] is a link) by placing the cursor
over that link and press CTRL+E.

This opens a new editor buffer. You can cycle through opened buffers with
CTRL+].

## Where to start

If you don't have Dusk running yet, refer to the instructions in the README file
at the root of the Dusk package.

Once you have it running, begin with [doc/operator], then [doc/usage].

Learning about operating Dusk is involving and if you want to have a quick tour
of its abilities before to commit to learning it, you can, instead of
[doc/usage], begin with [doc/tour].

## Contents of this documentation

Documentation about specific units have the same path in the documentation as
they have in the system and are not listed below. For example, for documentation
about [io/stream], you'll want to open [doc/io/stream.txt].

Some documentation pages are tied to a topic rather than a unit. The list below
is in rough suggested reading order.

tour      A tour of Dusk's capabilities
operator  Hello Operator!
usage     General usage reference
dict      Dictionary of system word
hal       Harmonized Assembly Layer
terms     Terminology
data      Fundamental data structures
dirs      Directory structure
deploy    Deploy Dusk to another machine
kernel    Anatomy of a kernel
boot      Boot Sequence
code      Understanding Dusk's code
tips      Tips and tricks
qa        Questions and answers
design    Description and justification of design decisions
indepth   Guided explanations of particular topics
hw        Hardware notes and CPU port implementation details. For example,
          [hw/i386] lists the specificities of the i386 port.

## Unit documentation format

Unit documentation roughly follow the same format, that is a first half that
describes its theory of operation and a second half describing its API. Very
simple units might omit the second part. The API part is divided by word types
such as "Structs", "Constants", "Values", "Words".

The "Words" part will describe each word with its full signature, but the other
parts will omit the signatures because it's always the same and/or modal.

* Structs: created with "struct" from [lib/struct]. The clearest thing to do is
  to copy thoe whole struct definition in the docs, then underneath add a
  detailed description for each field/method.
* Values: created with "value" from [lib/bm].
* Constants: created with "const" from [doc/dict].

Not all words of a unit appear in the "API" part of the unit's documentation.
When they don't, it means that their semantics are subject to change and
shouldn't be relied upon if you want your code to stay compatible with further
Dusk releases. If collapse happened, you can of course not care about this
notice and take comfort in the knowledge that nobody's ever going to break an
API you use ever again.
