manual

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

intro.roff (5135B)


      1 .tp
      2 .sp 2i
      3 .(l C
      4 FENIX INTERFACE MANUAL
      5 .sp 2
      6 K. Richey
      7 .sp 2
      8 XX XXX 20XX
      9 .)l
     10 .bp
     11 
     12 .ce
     13 INTRODUCTION
     14 .pp
     15 This manual provides descriptions of the publicly available features of Fenix.
     16 It is neither a general overview nor a description of the internals, neither of
     17 which have yet been written. Rather, it documents the programs, system calls,
     18 and other interfaces to Fenix.
     19 .pp
     20 This manual is designed to be timely. However, being in print, it will
     21 inevitably fall behind current developments to the operating system. Every
     22 attempt will be made to keep the manual up to date. However, it's important to
     23 ensure that you are reading the version of the manual that corresponds to the
     24 version of Fenix you are running. To check the current version, simply run the
     25 command \fIfenver\fR.
     26 .pp
     27 This manual is divided into seven sections:
     28 .(l
     29 I. Commands
     30 II. System calls
     31 III. Library routines
     32 IV. Special files
     33 V. File formats
     34 VI. User-maintained programs
     35 VII. Miscellanea
     36 .)l
     37 .pp
     38 Commands are programs to be called by the user from a command interpreter, in
     39 contrast to library routines, which are designed to be called by the user inside
     40 of a program's source code. Most commands reside in \fI/bin\fR. Some, however,
     41 reside within \fI/usr/bin\fR. If a command does such, it will be indicated in
     42 the command's entry.
     43 .pp
     44 System calls differ from library routines in that they directly interact with
     45 the Fenix kernel.
     46 .pp
     47 Special files refer to the system files used to refer to I/O devices.
     48 .pp
     49 File formats documents the structure of various files in use by the system. Note
     50 that temporary files are not included, such as intermediate output by a
     51 compiler.
     52 .pp
     53 User-maintained programs are not a part of Fenix and are only included in the
     54 manual for a particular system. This section will vary from system-to-system.
     55 This section is designed for a system administrator to fill in with their own
     56 system's user-maintained programs. Note that this section may not be up-to-date,
     57 even on the system for which it was written, as users add or remove programs.
     58 Information and assistance on user-maintained programs should not be directed
     59 at the Fenix developers, but at the user currently maintaining the program,
     60 given under the \fIowner\fR heading for a program.
     61 .pp
     62 Miscellanea covers various things that don't fit in any other part of the
     63 manual.
     64 .pp
     65 Each section contains entries of around a page in length. The name of the
     66 entry and its date of writing will be given in the header. Within each section,
     67 entries are alphabetised. The manual is designed to be easily updatable, where
     68 a system administrator can easily add, remove, or replace pages from a looseleaf
     69 manual.
     70 .pp
     71 All entries share conventions with most UNIX man pages.
     72 .(l F
     73 The \fIname\fR section simply gives the name of the entry and a description of
     74 purpose.
     75 
     76 the \fIsynopsis\fR summarizes the use of the program in question. Again,
     77 conventions are shared with UNIX man pages:
     78 .(l F
     79 Underlined/italic words are literals, typed as they appear.
     80 
     81 Square brackets around an option ([]) indicate that an argument is optional. If
     82 an argument is given as name, it always refers to a file name.
     83 
     84 Ellipses (...) are used to show the previous argument can be repeated.
     85 
     86 An argument starting with a hyphen (\-) is always a flag. This is more of a
     87 command convention than a manual convention. Hence, it is advised to avoid file
     88 names starting with \-.
     89 .)l
     90 .in 4
     91 The \fIdescription\fR section discusses the topic in detail.
     92 
     93 The \fIfiles\fR section lists relevant files to the program, such as
     94 configuration files.
     95 
     96 A \fIsee also\fR section is given that points to related information.
     97 
     98 The \fIdiagnostics\fR section gives the kinds of errors that may be produced,
     99 whether they print a diagnostic message or not, and whether they cause the
    100 program to terminate (fatal) or if it can continue running (non-fatal).
    101 
    102 The \fIbugs\fR section gives known bugs and deficiencies as of the date of
    103 writing. It may also include fixes or workarounds.
    104 
    105 The \fIauthor\fR section gives the Fenix team member to be consulted in case of
    106 difficulty. The team members are identified by a short identifier, as follows:
    107 .(l F
    108 kat    K. Richey
    109 .)l
    110 .in 4
    111 For those on the official Fenix development system, the short identifier is also
    112 the team member's user name, and messages may be sent to them via the \fImail\fR
    113 command.
    114 
    115 In section VI, the \fIauthor\fR section is replaced by the \fIowner\fR section.
    116 The identifier in this section should be the name of the system user responsible
    117 for maintenance of the command in question. It is up to the system administrator
    118 to query users for manual pages for this section or to otherwise write the
    119 manual page themself. On systems other than the Fenix development system, the
    120 Fenix development team is not responsible for the contents of this section.
    121 .)l
    122 .pp
    123 At the beginning of this document is a table of contents documenting sections
    124 I\-V and VII. The table of contents is organised by section and alphabetically
    125 within each section.
    126 .pp
    127 The initial version of this manual was produced using GNU Emacs and the GNU roff
    128 version of \fItroff\fR on a FreeBSD system.