trader/doc/trader.6

.\" *********************************************************************
.\" *                                                                   *
.\" *           Star Traders: A Game of Interstellar Trading            *
.\" *              Copyright (C) 1990-2024, John Zaitseff               *
.\" *                                                                   *
.\" *********************************************************************
.\"
.\" Author: John Zaitseff <J.Zaitseff@zap.org.au>
.\" $Id$
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or (at
.\" your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see https://www.gnu.org/licenses/.
.\"
.\"
.\" *********************************************************************
.\" Various settings, character sequences and macros
.\"
.\" Allow hyphenation
.hy 14
.\"
.\" Character sequences
.ie !n \{\
.char \[hellip] \[u2026]\"	U+2026 Horizontal ellipsis
.\}
.el \{\
.char \[hellip] ...\"		Three full stops
.\}
.\"
.\" Define .MR page-topic page-section [trailing-text]
.if !d MR \{\
.de MR
.IR \\$1 (\\$2)\\$3
..
.\}
.\"
.\" Define .CEX (start cmdline example) and .ECEX (end cmdline example)
.de CEX
.RS
.sp
.nh
.na
.ft \\*(mC
..
.de ECEX
.ft \\*(mR
.ad
.hy 14
.sp
.RE
..
.\"
.\" Define .URL, .MTO and .FTP, then try to load the www.tmac version
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.de MTO
\\$2 \(la\\$1\(ra\\$3
..
.de FTP
\\$2 \(la\\$1\(ra\\$3
..
.if \n[.g] .mso www.tmac
.\"
.\" *********************************************************************
.TH TRADER 6 "5th January, 2024" "Unix-like systems"
.SH NAME
trader \- a game of interstellar trading
.\" *********************************************************************
.SH SYNOPSIS
.B trader
.RB [ \-\-no\-color | \-\-no\-colour ]
.RB [ \-\-max\-turn=\c
.IR NUM ]
.RI [ GAME ]
.br
.B trader
.RB [ \-h | \-\-help ]
.RB [ \-V | \-\-version ]
.\" *********************************************************************
.SH DESCRIPTION
\fBStar Traders\fP is a simple game of interstellar trading, where the
objective is to create companies, buy and sell shares, borrow and repay
money, in order to become the wealthiest player (the winner).
.\" *********************************************************************
.SH OPTIONS
.TP
.I GAME
If \fIGAME\fP is specified as a number between \fB1\fP and \fB9\fP
(inclusive), load and continue playing that game.  If \fIGAME\fP is not
specified, start a new game.
.TP
.BR \-\-no\-color ", " \-\-no\-colour
Don't use colour for displaying the text in the game.  Use this option
for a \*(lqretro-computing\*(rq look (as shown in the
.B EXAMPLES
below).
.TP
.BI \-\-max\-turn= NUM
Set the number of turns in the game to \fINUM\fP.  In this version of
Star Traders, \fINUM\fP must be greater or equal to 10.  If this option
is not specified, the default is 50 turns.
.TP
.BR \-h ", " \-\-help
Show a summary of command-line options and exit.
.TP
.BR \-V ", " \-\-version
Display version information about the program, then exit.
.\" *********************************************************************
.SH "EXIT STATUS"
.TP
.B 0
Star Traders finished without any errors.
.TP
.B 1
Star Traders encountered an unrecoverable problem or error; a diagnostic
message will be written to standard error in this case.
.\" *********************************************************************
.SH EXAMPLES
You can start a new game by running Star Traders without any command line
options:
.CEX
trader
.ECEX
Once the game starts, you will be asked to enter the number of people
playing.  From one to eight people can play (although, in this version,
they will all have to share the one keyboard and screen!).  After
entering the names of the players, you will have the opportunity to read
instructions on how to play the game.  Do so\(emand good luck in the
game!
.PP
If you would like to continue a previously-saved game, simply specify
that game number on the command line.  For example, the following starts
game 4, if it was previously saved:
.CEX
trader 4
.ECEX
If you are running under the X Window System, you might like to start the
game in a dedicated
.MR xterm 1
window (typed all on one line):
.CEX
xterm \-g 80x24 \-fa Mono \-fs 18 \-bg black \-fg white \-bc +sb +fbx
\-e trader &
.ECEX
If you would like a full \*(lqretro-computing\*(rq green-screen
experience, try (again, typed all on one line):
.CEX
xterm \-g 80x24 \-fa Mono \-fs 18 \-bg \(aq#181818\(aq \-fg \(aq#2CAB00\(aq
\-bc +sb +bdc +fbx \-xrm \(aqXTerm*colorBD: #41FF00\(aq \-e trader
\-\-no\-colour &
.ECEX
Or, if you prefer the old amber screens of yesteryear:
.CEX
xterm \-g 80x24 \-fa Mono \-fs 18 \-bg \(aq#101010\(aq \-fg \(aq#AB7A00\(aq
\-bc +sb +bdc +fbx \-xrm \(aqXTerm*colorBD: #FFB700\(aq \-e trader
\-\-no\-colour &
.ECEX
.\" *********************************************************************
.SH ENVIRONMENT
.TP
.BR XDG_DATA_HOME ", " HOME
If \fBXDG_DATA_HOME\fP is set to an absolute pathname (that is, a path
that starts with \*(lq\fI/\fP\*(rq), Star Traders will use that
directory, with a subdirectory \fItrader\fP, to store game files.  If
this environment variable is not set or does not start with
\*(lq\fI/\fP\*(rq, \fI\(ti/.local/share/trader\fP will be used instead,
where \*(lq\fI\(ti\fP\*(rq represents your home directory, as contained
in the \fBHOME\fP environment variable.
.TP
.BR LINES ", " COLUMNS
Star Traders uses the Curses library for displaying text on the screen.
As such, it will access these two environment variables if the underlying
Curses library does so (see, for example, the \fBENVIRONMENT\fP section
in the
.MR ncurses 3
manual page for in-depth details).  It requires a text console or window
of at least 80\(mu24 in size.
.TP
.BR LANG ", " LC_ALL ", etc."
This version of Star Traders has full support for locales and will use
appropriate settings.  In particular, messages will be displayed using
\fBLC_MESSAGES\fP and \fBLANGUAGE\fP (if Star Traders has been translated
into that language).  In addition, numeric quantities will be displayed
using \fBLC_NUMERIC\fP and monetary quantities will use
\fBLC_MONETARY\fP.  See the
.MR locale 7
or
.MR setlocale 3
manual pages for more details on locale settings.
.TP
.B TEXTDOMAINDIR
If set, Star Traders will use this path as the base with which to locate
its message catalogs instead of the compiled-in path; the relevant
\fItrader.mo\fP files should be located in language-code subdirectories
(such as \fIen_AU\fP), in \fILC_MESSAGES\fP sub-subdirectories.
.\" *********************************************************************
.SH FILES
.TP
.IB \(ti/.local/share/trader/game N
Star Traders stores saved game files in the \fI.local/share/trader\fP
subdirectory in your home directory (unless overridden by the
\fBXDG_DATA_HOME\fP environment variable).  \fIN\fP is a number between
\fB1\fP and \fB9\fP inclusive.  The game file is scrambled to prevent you
or others from casually cheating!
.TP
.IB \(ti/.trader/game N
If the \fI\(ti/.trader\fP directory exists, game files will be read from
and saved to this location instead.  This is for compatibility with
versions of Star Traders prior to version 7.15.
.\" *********************************************************************
.SH BUGS
None yet known\[hellip]
.\" *********************************************************************
.SH FEEDBACK
Your comments, suggestions, corrections and enhancements are always
warmly welcomed!  Please send these to:
.IP Postal: 10n
\fBJohn Zaitseff\fP,
.br
The ZAP Group Australia,
.br
Unit 6, 116 Woodburn Road,
.br
Berala, NSW, 2141,
.br
Australia
.IP Email: 10n
.MTO J.Zaitseff@zap.org.au
.PD 0
.IP Web: 10n
.URL https://www.zap.org.au/projects/trader/
.IP FTP: 10n
.URL https://ftp.zap.org.au/pub/trader/
.br
.FTP ftp://ftp.zap.org.au/pub/trader/
.PD 0
.IP Git: 10n
.URL https://www.zap.org.au/git-browser/trader.git
.br
.URL https://git.zap.org.au/git/trader.git
.br
.URL git://git.zap.org.au/data/git/trader.git
.PD
.PP
.\" *********************************************************************
.SH COPYRIGHT
Copyright \(co 1990\-2024, John Zaitseff.
.PP
\fBStar Traders\fP is free software that is distributed under the terms
of the GNU General Public License.  You can redistribute it and/or modify
it under the terms of that License as published by the Free Software
Foundation, either version 3 or (at your option) any later version.
.PP
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
with this program.  If not, see the
.URL https://www.gnu.org/licenses/ "GNU licenses web page" .
.PP
Even though the GNU General Public License does \fInot\fP require you to
send your modifications back to the author, it is considered \*(lqgood
form\*(rq to do so, as this allows your modifications to be incorporated
into future versions of the program, allowing others to benefit from
them.
.\" *********************************************************************
.SH HISTORY
The original (and very primitive) Star Traders game was written by
S.\~J\. Singer in 1984 using Altair Basic.  This was modified for
Microsoft Basic (MBASIC) running under the CP/M-80 operating system by
John Zaitseff and released on 7th March, 1988.
.PP
Star Traders was then completely rewritten in 1990 for the
Australian-designed 8-bit MicroBee computer running CP/M-80 on a Zilog
Z80 processor, using Turbo Pascal 3.01a.  Essentially, only the name of
the game and some of the ideas were retained in this version.  Version
4.1 of Star Traders was released on 1st August, 1991.
.PP
In 1992, it was recompiled for the NEC Advanced Personal Computer (with
8-inch floppy drives!) running CP/M-86 on an 8086 processor, using Turbo
Pascal 2.0.  This version had colour added to it in the form of ANSI
escape sequences; version 4.4 was released on 2nd August, 1993.
.PP
The next version came in 1993, when the program was recompiled to run on
IBM-compatible machines running MS-DOS and ANSI.SYS.  Turbo Pascal 6.0
was used for this.  The ANSI escape sequences were slightly different
under MS-DOS than under the NEC, in that the NEC supported a number of
extra character attributes.  In other words, the MS-DOS version looked
worse than the one running under CP/M-86!
.PP
Star Traders was recompiled again in 1994 for IBM-compatible machines
with VGA/EGA/CGA video graphics adapters.  The output routines were
recoded to use a \*(lqwindowed\*(rq look.  Borland Pascal 7.0 was used
for this purpose, along with a number of text window manipulation
modules.  Version 5.4 was released on 1st June, 1994.
.PP
In 1995, Star Traders was completely rewritten for the 16-bit Microsoft
Windows 3.1 graphical environment.  Microsoft Visual Basic 3.0 was used
for this purpose.  Although completely rewritten, the original algorithms
were reused from previous versions.  Version 6.0 of the game was released
on 15th September, 1995.
.PP
Star Traders was then to languish until almost 16 years later\[hellip]
when the game was rewritten once again, this time in the C programming
language.  Version 7.0 was released on 25th July, 2011 for Unix-like
operating systems such as Linux, with subsequent releases to add features
and correct bugs.  Now you, too, can run this small piece of computing
history!
.\" *********************************************************************
.SH "SEE ALSO"
.URL https://www.zap.org.au/projects/trader/ "Star Traders home page"
.\" *********************************************************************
.\" End of file