* Docs theme to match ENiGMA website

* New docs layout ready for github pages serving
* Tonnes of new docs
* Update gitignore
* Probably other stuff too
This commit is contained in:
David Stephens 2018-01-31 23:35:54 +00:00
parent 06ea2d1600
commit 26849ba4fa
62 changed files with 1974 additions and 810 deletions

View file

@ -0,0 +1,77 @@
---
layout: page
title: Archivers
---
ENiGMA½ can detect and process various archive formats such as zip and arj for a variety of tasks from file upload processing to EchoMail bundle compress/decompression. The `archives` section of `config.hjson` is used to override defaults, add new handlers, and so on.
## Archivers
Archivers are manged via the `archives:archivers` configuration block of `config.hjson`. Each entry in this section defines an **external archiver** that can be referenced in other sections of `config.hjson` as and in code. Entries define how to `compress`, `decompress` (a full archive), `list`, and `extract` (specific files from an archive).
### Predefined Archivers
The following archivers are pre-configured in ENiGMA½ as of this writing. Remember that you can override settings or add new handlers!
#### ZZip
* Formats: .7z, .bzip2, .zip, .gzip/.gz, and more
* Key: `7Zip`
* Homepage/package: [7-zip.org](http://www.7-zip.org/). Generally obtained from a `p7zip` package in *nix environments. See http://p7zip.sourceforge.net/ for details.
#### Lha
* Formats: <a href="https://en.wikipedia.org/wiki/LHA_(file_format)">LHA</a> files such as .lzh.
* Key: `Lha`
* Homepage/package: `lhasa` on most *nix environments. See also https://fragglet.github.io/lhasa/ and http://www2m.biglobe.ne.jp/~dolphin/lha/lha-unix.htm
#### Arj
* Formats: .arj
* Key: `Arj`
* Homepage/package: `arj` on most *nix environments.
#### Rar
* Formats: .Rar
* Key: `Rar`
* Homepage/package: `unrar` on most *nix environments. See also https://blog.hostonnet.com/unrar
### Archiver Configuration
Archiver entries in `config.hjson` are mostly self explanatory with the exception of `list` commands that require some additional information. The `args` member for an entry is an array of arguments to pass to `cmd`. Some variables are available to `args` that will be expanded by the system:
* `{archivePath}` (all): Path to the archive
* `{fileList}` (compress, extract): List of file(s) to compress or extract
* `{extractPath}` (decompress, extract): Path to extract *to*
For `list` commands, the `entryMatch` key must be provided. This key should provide a regular expression that matches two sub groups: One for uncompressed file byte sizes (sub group 1) and the other for file names (sub group 2). An optional `entryGroupOrder` can be supplied to change the default sub group order.
#### Example Archiver Configuration
```
7Zip: {
compress: {
cmd: 7za,
args: [ "a", "-tzip", "{archivePath}", "{fileList}" ]
}
decompress: {
cmd: 7za,
args: [ "e", "-o{extractPath}", "{archivePath}" ]
}
list: {
cmd: 7za,
args: [ "l", "{archivePath}" ]
entryMatch: "^[0-9]{4}-[0-9]{2}-[0-9]{2}\\s[0-9]{2}:[0-9]{2}:[0-9]{2}\\s[A-Za-z\\.]{5}\\s+([0-9]+)\\s+[0-9]+\\s+([^\\r\\n]+)$",
}
extract: {
cmd: 7za,
args [ "e", "-o{extractPath}", "{archivePath}", "{fileList}" ]
}
}
```
## Archive Formats
Archive formats can be defined such that ENiGMA½ can detect them by signature or extension, then utilize the correct *archiver* to process them. Formats are defined in the `archives:formats` key in `config.hjson`. Many differnet types come pre-configured (see `core/config.js`).
### Example Archive Format Configuration
```
zip: {
sig: "504b0304" /* byte signature in HEX */
offset: 0
exts: [ "zip" ]
handler: 7Zip /* points to a defined archiver */
desc: "ZIP Archive"
}
```

View file

@ -0,0 +1,122 @@
---
layout: page
title: config.hjson
---
## System Configuration
The main system configuration file, `config.hjson` both overrides defaults and provides additional configuration such as message areas. The default path is `/enigma-bbs-install-path/config/config.hjson` though you can override the `config.hjson` location with the `--config` parameter when invoking `main.js`. Values found in `core/config.js` may be overridden by simply providing the object members you wish replace.
### Creating a Configuration
Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your enigma-bbs root directory:
```
./oputil.js config new
```
You will be asked a series of questions to create an initial configuration.
### Overriding Defaults
The file `core/config.js` provides various defaults to the system that you can override via `config.hjson`. For example, the default system name is defined as follows:
```javascript
general : {
boardName : 'Another Fine ENiGMA½ System'
}
```
To override this for your own board, in `config.hjson`:
```hjson
general: {
boardName: Super Fancy BBS
}
```
(Note the very slightly different syntax. **You can use standard JSON if you wish**)
While not everything that is available in your `config.hjson` file can be found defaulted in `core/config.js`, a lot is. [Poke around and see what you can find](https://github.com/NuSkooler/enigma-bbs/blob/master/core/config.js)!
### A Sample Configuration
Below is a **sample** `config.hjson` illustrating various (but certainly not all!) elements that can be configured / tweaked.
**This is for illustration purposes! Do not cut & paste this configuration!**
```hjson
{
general: {
boardName: A Sample BBS
menuFile: "your_bbs.hjson" // copy of menu.hjson file (and adapt to your needs)
}
defaults: {
theme: "super-fancy-theme" // default-assigned theme (for new users)
}
preLoginTheme: "luciano_blocktronics" // theme used before a user logs in (matrix, NUA, etc.)
messageConferences: {
local_general: {
name: Local
desc: Local Discussions
default: true
areas: {
local_enigma_dev: {
name: ENiGMA 1/2 Development
desc: Discussion related to development and features of ENiGMA 1/2!
default: true
}
}
}
agoranet: {
name: Agoranet
desc: This network is for blatant exploitation of the greatest BBS scene art group ever.. ACiD.
areas: {
agoranet_bbs: {
name: BBS Discussion
desc: Discussion related to BBSs
}
}
}
}
messageNetworks: {
ftn: {
areas: {
agoranet_bbs: { /* hey kids, this matches above! */
// oh oh oh, and this one pairs up with a network below
network: agoranet
tag: AGN_BBS
uplinks: "46:1/100"
}
}
networks: {
agoranet: {
localAddress: "46:3/102"
}
}
}
}
scannerTossers: {
ftn_bso: {
schedule: {
import: every 1 hours or @watch:/home/enigma/bink/watchfile.txt
export: every 1 hours or @immediate
}
defaultZone: 46
defaultNetwork: agoranet
nodes: {
"46:*": {
archiveType: ZIP
encoding: utf8
}
}
}
}
}
```

View file

@ -0,0 +1,27 @@
---
layout: page
title: Creating Initial Config Files
---
Configuration files in ENiGMA½ are simple UTF-8 encoded [HJSON](http://hjson.org/) files. HJSON is just
like JSON but simplified and much more resilient to human error.
## config.hjson
Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your
enigma-bbs root directory:
```
./oputil.js config new
```
You will be asked a series of questions to create an initial configuration.
## menu.hjson and prompt.hjson
Create your own copy of `/config/menu.hjson` and `/config/prompt.hjson`, and specify it in the
`general` section of `config.hjson`:
````hjson
general: {
menuFile: my-menu.hjson
promptFile: my-prompt.hjson
}
````

View file

@ -0,0 +1,20 @@
---
layout: page
title: Directory Structure
---
All paths mentioned here are relative to the ENiGMA½ checkout directory.
| Directory | Description |
|---------------------|-----------------------------------------------------------------------------------------------------------|
| `/art/general` | Non-theme art - welcome ANSI, logoff ANSI, etc. See [General Art](/art/general).
| `/art/themes` | Theme art. Themes should be in their own subdirectory and contain a theme.hjson. See [Themes](/art/themes).
| `/config` | config.hjson, [menu.hjson](/configuration/menu-hjson) and prompt.hjson storage. Also default path for SSL certs and public/private keys
| `/db` | All ENiGMA½ databases in Sqlite3 format
| `/docs` | These docs ;-)
| `/dropfiles` | Dropfiles created for [local doors](/modding/local-doors)
| `/logs` | Logs. See [Monitoring Logs](/troubleshooting/monitoring-logs)
| `/misc` | Stuff with no other home; reset password templates, common password lists, other random bits
| `/mods` | User mods. See [Modding](/modding/existing-mods)
| `/node_modules` | External libraries required by ENiGMA½, installed when you run `npm install`
| `/util` | Various tools used in running/debugging ENiGMA½
| `/www` | ENiGMA½'s built in webserver root directory

View file

@ -0,0 +1,16 @@
---
layout: page
title: Editing Hjson
---
Hjson is a syntax extension to JSON. It's NOT a proposal to replace JSON or to incorporate it into the JSON spec itself.
It's intended to be used like a user interface for humans, to read and edit before passing the JSON data to the machine.
You can find more info at the [Hjson.org website](http://hjson.org/).
## Editor Plugins
### Visual Studio Code
[Visual Studio Code](https://code.visualstudio.com/) has a nice Hjson extension that can be installed from
within the IDE. It provides syntax highlighting to make it clear when you've made a syntax mistake within
a config file.

View file

@ -0,0 +1,101 @@
---
layout: page
title: menu.hjson
---
:warning: ***IMPORTANT!*** Before making any customisations, create your own copy of `/config/menu.hjson`, and specify it in the
`general` section of `config.hjson`:
````hjson
general: {
menuFile: my-menu.hjson
}
````
This document and others will refer to `menu.hjson`. This should be seen as an alias to `yourboardname.hjson`
## The Basics
Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format.
Entries in `menu.hjson` are objects defining a menu. A menu in this sense is something the user can see
or visit. Examples include but are not limited to:
* Classical Main, Messages, and File menus
* Art file display
* Module driven menus such as door launchers
Each entry in `menu.hjson` defines an object that represents a menu. These objects live within the `menus`
parent object. Each object's *key* is a menu name you can reference within other menus in the system.
## Example
Let's look a couple basic menu entries:
```hjson
telnetConnected: {
art: CONNECT
next: matrix
options: { nextTimeout: 1500 }
}
```
The above entry `telnetConnected` is set as the Telnet server's first menu entry (set by `firstMenu` in
the Telnet server's config).
An art pattern of `CONNECT` is set telling the system to look for `CONNECT<n>.*` where `<n>` represents
a optional integer in art files to cause randomness, e.g. `CONNECT1.ANS`, `CONNECT2.ANS`, and so on. If
desired, you can also be explicit by supplying a full filename with an extention such as `CONNECT.ANS`.
The entry `next` sets up the next menu, by name, in the stack (`matrix`) that we'll go to after
`telnetConnected`.
Finally, an `options` object may contain various common options for menus. In this case, `nextTimeout`
tells the system to proceed to the `next` entry automatically after 1500ms.
Now let's look at `matrix`, the `next` entry from `telnetConnected`:
```hjson
matrix: {
art: matrix
desc: Login Matrix
form: {
0: {
VM: {
mci: {
VM1: {
submit: true
focus: true
items: [ "login", "apply", "log off" ]
argName: matrixSubmit
}
}
submit: {
*: [
{
value: { matrixSubmit: 0 }
action: @menu:login
}
{
value: { matrixSubmit: 1 },
action: @menu:newUserApplication
}
{
value: { matrixSubmit: 2 },
action: @menu:logoff
}
]
}
}
}
}
}
```
In the above entry, you'll notice `form`. This defines a form(s) object. In this case, a single form
by ID of `0`. The system is then told to use a block only when the resulting art provides a `VM`
(*VerticalMenuView*) MCI entry. `VM1` is then setup to `submit` and start focused via `focus: true`
as well as have some menu entries ("login", "apply", ...) defined. We provide an `argName` for this
action as `matrixSubmit`.
The `submit` object tells the system to attempt to apply provided match entries from any view ID (`*`).
Upon submit, the first match will be executed. For example, if the user selects "login", the first entry
with a value of `{ matrixSubmit: 0 }` will match causing `action` of `@menu:login` to be executed (go
to `login` menu).

View file

@ -0,0 +1,6 @@
---
layout: page
title: SysOp Setup
---
SySop privileges will be granted to the first user to log into a fresh ENiGMA½ installation.