Permalink
Browse files

Update documentation for 2.0 release

  • Loading branch information...
jquast committed Dec 30, 2014
1 parent 18acdd8 commit 9cb6148bc1cf2d6d8d7617cc0f037f33a6f5c2fb
Showing with 144 additions and 228 deletions.
  1. +0 −77 README.rst
  2. +1 −0 README.rst
  3. +0 −77 README.txt
  4. +20 −19 docs/bbs_api.rst
  5. +2 −4 docs/clients.rst
  6. +8 −29 docs/default_api.rst
  7. +2 −1 docs/developers.rst
  8. +0 −1 docs/index.rst
  9. +74 −10 docs/intro.rst
  10. +32 −7 docs/others.rst
  11. +4 −2 docs/port23.rst
  12. +1 −1 x84/bbs/__init__.py
View
@@ -1,77 +0,0 @@
====
x/84
====
**A python Telnet server for modern UTF-8 and classic cp437 network virtual terminals**.
x/84 supplies a scripting_ engine for developing character-at a time telnet services, such as **MUD** or **BBS** systems. Technologies used in x/84 are derived from miniboa_ (Apache 2.0 Licensed) for telnet, blessed_ (MIT Licensed) for terminal capabilities, and sqlitedict_ (Public Domain) for persistent data. Recordings of sessions are stored in ttyplay_-compatible format files.
Asynchronous inter-process communication between sessions is provided through an event queuing framework, for scripting of 'shared' experiences. Several examples of these are provided, such as *chat.py*. The default board provides several activities.
Portability is as equal to python, and has been tested on Raspberry Pi, Android, Mac, OpenBSD, Solaris, etc.
**ANSI Art**, such as found on ACiD_ *dark domains* DVD, is translated for reasonably accurate reproductions for both UTF-8 and IBM CP437 terminals. This allows classic DOS art to be used on modern terminals such as Terminal.app, or classic emulating terminals such as syncterm_. Artwork with Sauce_ records are also supported.
Telnet to host address 1984.ws to preview the default board. See clients_ for a list of compatible clients.
Install
=======
1. Install python_ 2.6 or 2.7
2. Install pip_
3. Ensure pip is up-to-date::
pip install --upgrade pip
4. Install x/84::
pip install x84
5. Upgrading::
pip install --upgrade x84
Getting Started
===============
1. Launch the *x84.engine* python module::
x84
If the ``*x84`` helper script fails, try using the
python interpreter used by ``pip``::
python2.7 -m x84.engine
2. Telnet to 127.0.0.1 6023, Assuming a *bsd telnet* client::
telnet localhost 6023
Further documentation
=====================
See Documentation_ generated by Sphinx for both docstring API documentation and general tutorials.
Issue Tracking & Development
============================
See the project on github_ for source tree and issue tracking.
.. _miniboa: https://code.google.com/p/miniboa/
.. _sqlitedict: http://pypi.python.org/pypi/sqlitedict
.. _blessed: http://pypi.python.org/pypi/blessed
.. _ttyplay: http://0xcc.net/ttyrec/index.html.en
.. _ACiD: https://en.wikipedia.org/wiki/ACiD_Productions
.. _Sauce: https://github.com/tehmaze/sauce
.. _syncterm: http://syncterm.bbsdev.net/
.. _python: https://www.python.org/
.. _pip: http://guide.python-distribute.org/installation.html#installing-pip
.. _Documentation: http://x84.readthedocs.org/
.. _clients: https://x84.readthedocs.org/en/latest/clients.html
.. _scripting: https://x84.readthedocs.org/en/latest/bbs_api.html
.. _github: https://github.com/jquast/x84
View
View
@@ -1,77 +0,0 @@
====
x/84
====
**A python Telnet server for modern UTF-8 and classic cp437 network virtual terminals**.
x/84 supplies a scripting_ engine for developing character-at a time telnet services, such as **MUD** or **BBS** systems. Technologies used in x/84 are derived from miniboa_ (Apache 2.0 Licensed) for telnet, blessed_ (MIT Licensed) for terminal capabilities, and sqlitedict_ (Public Domain) for persistent data. Recordings of sessions are stored in ttyplay_-compatible format files.
Asynchronous inter-process communication between sessions is provided through an event queuing framework, for scripting of 'shared' experiences. Several examples of these are provided, such as *chat.py*. The default board provides several activities.
Portability is as equal to python, and has been tested on Raspberry Pi, Android, Mac, OpenBSD, Solaris, etc.
**ANSI Art**, such as found on ACiD_ *dark domains* DVD, is translated for reasonably accurate reproductions for both UTF-8 and IBM CP437 terminals. This allows classic DOS art to be used on modern terminals such as Terminal.app, or classic emulating terminals such as syncterm_. Artwork with Sauce_ records are also supported.
Telnet to host address 1984.ws to preview the default board. See clients_ for a list of compatible clients.
Install
=======
1. Install python_ 2.6 or 2.7
2. Install pip_
3. Ensure pip is up-to-date::
pip install --upgrade pip
4. Install x/84::
pip install x84
5. Upgrading::
pip install --upgrade x84
Getting Started
===============
1. Launch the *x84.engine* python module::
x84
If the ``*x84`` helper script fails, try using the
python interpreter used by ``pip``::
python2.7 -m x84.engine
2. Telnet to 127.0.0.1 6023, Assuming a *bsd telnet* client::
telnet localhost 6023
Further documentation
=====================
See Documentation_ generated by Sphinx for both docstring API documentation and general tutorials.
Issue Tracking & Development
============================
See the project on github_ for source tree and issue tracking.
.. _miniboa: https://code.google.com/p/miniboa/
.. _sqlitedict: http://pypi.python.org/pypi/sqlitedict
.. _blessed: http://pypi.python.org/pypi/blessed
.. _ttyplay: http://0xcc.net/ttyrec/index.html.en
.. _ACiD: https://en.wikipedia.org/wiki/ACiD_Productions
.. _Sauce: https://github.com/tehmaze/sauce
.. _syncterm: http://syncterm.bbsdev.net/
.. _python: https://www.python.org/
.. _pip: http://guide.python-distribute.org/installation.html#installing-pip
.. _Documentation: http://x84.readthedocs.org/
.. _clients: https://x84.readthedocs.org/en/latest/clients.html
.. _scripting: https://x84.readthedocs.org/en/latest/bbs_api.html
.. _github: https://github.com/jquast/x84
View
@@ -24,7 +24,16 @@ General functions
Terminal
````````
Please see the general documentation for blessed at
https://pypi.python.org/pypi/blessed
.. autofunction:: x84.bbs.getterminal
.. autofunction:: x84.bbs.showart
.. autofunction:: x84.bbs.encode_pipe
.. autofunction:: x84.bbs.decode_pipe
.. autofunction:: x84.bbs.syncterm_setfont
.. autofunction:: x84.bbs.output.ansiwrap
.. autoclass: x84.bbs.Ansi
.. autoclass: blessed.Terminal
Session
@@ -50,6 +59,17 @@ Database
.. autoclass:: x84.bbs.DBProxy
Configuration
`````````````
.. autofunction:: x84.bbs.get_ini
File Transfers
``````````````
.. autofunction:: x84.bbs.send_modem
.. autofunction:: x84.bbs.recv_modem
Ansi UI Elements
````````````````
@@ -88,22 +108,3 @@ Doors
.. automodule:: x84.bbs.door
:members:
CP437 and ANSI
``````````````
.. autofunction:: x84.bbs.showcp437
.. autofunction:: x84.bbs.from_cp437
.. autofunction:: x84.bbs.ropen
.. autoclass: x84.bbs.Ansi
.. autofunction:: x84.bbs.output.ansiwrap
Keysets, Themes
```````````````
.. autoattribute:: x84.bbs.editor.PC_KEYSET
.. autoattribute:: x84.bbs.pager.VI_KEYSET
.. autoattribute:: x84.bbs.selector.VI_KEYSET
.. autoattribute:: x84.bbs.lightbar.NETHACK_KEYSET
.. autoattribute:: x84.bbs.ansiwin.GLYPHSETS
View
@@ -27,15 +27,13 @@ Non-unicode
Other than UTF-8, only IBM CP437 encoding is supported. Any telnet client with CP437 font is supported.
Examples of these include PuTTy, SyncTerm, mtel, netrunner, linux/bsd console + bsd telnet.
Examples of these include PuTTy, SyncTerm, mtel, netrunner, linux/bsd console + linux/bsd telnet.
Some non-DOS terminal emulators may require installing a fontset, such as *Terminus_* to provide CP437 art.
TCP Encryption
--------------
Telnet is not a secure protocol. This implementation of x/84 is without any encryption. It is not secure from network eavesdropping. SSH works perfectly fine as an intermediary transport if eavesdropping is a concern.
Previous versions included ssh support directly through twisted conch, and can be found in the earliest github revisions as ``ssh.py``. The twisted dependency was considered too 'heavyweight' and dropped.
Telnet is not a secure protocol. This implementation of x/84 is without any encryption. It is not secure from network eavesdropping. SSH is supported and works perfectly fine if eavesdropping is a concern.
.. _Terminus: http://terminus-font.sourceforge.net/
View
@@ -8,14 +8,14 @@ The ``default.ini`` file option, *scriptpath*, of section *[system]*, defines fo
This folder may be changed to a folder of your own chosing, and populated with your own scripts. A good start would be to copy the default/ folder, or even perform a checkout from github.
By default, matrix.py_ is called on-connect, set by the ``default.ini`` file option *script* of section *[matrix]*. This script calls out to nua.py_ for new account creation, top.py_ when authenticated, and main.py_ for a main menu.
By default, matrix.py_ is called on-connect, with variations for sftp and ssh as matrix_sftp.py and matrix_ssh.py set by the ``default.ini`` file option *script* of section *[matrix]*. This script calls out to nua.py_ for new account creation, top.py_ when authenticated, and main.py_ for a main menu.
main(), gosub, and goto
-----------------------
All scripts to be called by ``goto`` or ``gosub`` must suply a ``main`` function. Keyword arguments are not allowed.
All scripts to be called by ``goto`` or ``gosub`` must supply a ``main`` function. Keyword and positional arguments are allowed.
If a script fails due to import or runtime error, the exception is caught, optionally displayed, and the previous script is re-started.
If a script fails due to import or runtime error, the exception is caught, (optionally displayed by ``default.ini`` option ``show_traceback``), and the previous script is re-started.
If a script returns, and was called by ``gosub``, the return value is returned by ``gosub``.
@@ -108,19 +108,10 @@ Displays System Information, about the BBS system, and its authors.
.. automodule:: x84.default.si
:members:
bbslist.py
----------
A bbs listing utility, to allow users to post, vote on, and leave comments for other bbs systems. Systems may be directly connected via gateway to other systems by a gosub routine to telnet.py_.
A list of bbs's from bbs-scene_.org's API is retrieved if configured. Create a new section, *[bbs-scene]* in ``defaults.ini``, with two options, *user* and *pass*.
.. automodule:: x84.default.bbslist
:members:
weather.py
----------
An example of using the various user interface elements to display the local weather report. Currently only reads in Fahrenheit and Celcius. Not all xml values are displayed.
An example of using the various user interface elements to display the local weather report in an artful fashion.
.. automodule:: x84.default.weather
:members:
@@ -131,15 +122,15 @@ An example of using the various user interface elements to display the local wea
chat.py
-------
This script demonstrates use of global broadcasts by creating a chat interface over the intra-process event system. It is anagolous to irc, and provides similar commands, */join*, */act*, */whois*, etc.
This script demonstrates use of global broadcasts by creating a chat interface over the intra-process event system.
.. automodule:: x84.default.chat
:members:
debug.py
--------
This script demonstrates the ability for a sysop to run maitenance scripts or to test new code. Provided is an example of importing user records from another bbs system.
This script demonstrates the ability for a sysop to run maintenance scripts or to test new code.
.. automodule:: x84.default.debug
:members:
@@ -161,7 +152,7 @@ By using various event subsystems, global "are you there?" pings are sent to all
Each time an activity change is discovered, the display is refreshed. This provides a "waiting for callers" screen for sysops or users, with a scroll buffer indicating the previous days activities.
Gosub routines are provided to page other users for chat.py_ and writemsg.py_ to online recipients. Sysops have additional functionality to disconnect sessions, or playback and watch current session recordings using ttyplay.py_.
Gosub routines are provided to page other users for chat.py_ and writemsg.py_ to online recipients.
.. automodule:: x84.default.online
:members:
@@ -194,7 +185,7 @@ A message scanning and browsing interface. Analogous to mutt.
telnet.py
---------
A telnet client within the bbs. Used by bbslist.py_.
A telnet client within the bbs, may be used to gateway to other hosts.
.. automodule:: x84.default.telnet
:members:
@@ -206,22 +197,10 @@ A terminal game of tetris with ANSI art blocks by jojo. High scores are persiste
.. autofunction:: x84.default.tetris.main
ttyplay.py
----------
The ``default.ini`` file option, *exe*, of section *[ttyplay]*, defines path to external door to be used to playback ttyplay_ formatted files.
If no arguments are specified, the sysop is provided a lightbar interface to display all recorded tty sessions for playback.
.. automodule:: x84.default.ttyplay
:members:
writemsg.py
-----------
Provides an interface to popular a Msg record, and gosub the editor.py_ script to construct and send a message to the messagebase.
.. automodule:: x84.default.writemsg
:members:
.. _ttyplay: http://0xcc.net/ttyrec/index.html.en
View
@@ -69,7 +69,8 @@ Engine and Internals
====================
x/84 is designed in three distinct parts: The Engine_, Userland_, and
the default 'bbs board'.
the default 'bbs board'. You are encouraged to extend and modify any
component of the system, it is all authored in the python language.
Userland
````````
View
@@ -14,7 +14,6 @@ Contents:
:maxdepth: 4
intro
install
clients
port23
developers
Oops, something went wrong.

0 comments on commit 9cb6148

Please sign in to comment.