#+TITLE: User Manual
#+AUTHOR: Eris Mathison
#+DATE: 2022/07/30 version 0.1.0

* Preface
This document describes the use of apollon,
specifically from the command line.
This does not describe the API.

* Installation
Currently there are two methods of installing apollon,
however both are essentially the same thing.

For both methods you will need a rust installation with cargo.
See the [[https://www.rust-lang.org/learn/get-started][Official Guide]] for more information.

** Through cargo
The easier method of installing apollon is to use cargo,
rust's package manager.

#+begin_src shell
  cargo install apollon
#+end_src

That command will install apollon's latest release into cargo's installation directory.
By default on UNIX-like systems, that path is "$HOME/.cargo/bin",
make sure the installation path is included in the $PATH/%PATH% variable.
This should be set by default when installing through rust up.

** From source (git)
To install from source,
First clone the source code:

#+begin_src shell
  git clone 'https://notabug.org/erislmm/Apollon.git'
  cd Apollon
#+end_src

then install with

#+begin_src shell
  cargo intstall --path .
#+end_src

On UNIX-like systems,
or

#+begin_src bat
  cargo install /path .
#+end_src

On Windows.

this will also install apollon to cargo's default installation directory.
On UNIX-like systems this is "$HOME/.cargo/bin",
which is added to $PATH/%PATH% by default when installing via rustup.

* Usage
The most basic use of the apollon command is

#+begin_src shell
  apollon [options] file
#+end_src

which will compile the input file(<file>)
using the 'ANSI' generator (see [[*Generators][Generators]]).
To read the file to the terminal use

#+begin_src shell
  more file.out
#+end_src

You should see a formatted version of the text (see [[*Formatting][Formatting]]).

** Options
For all the options listed, on UNIX-like systems
prepend '-' and '--' for short and long options respecively,
and prepend '/' for Windows.

| Long        | Short | Description            |
|-------------+-------+------------------------|
| generator   | g     | Set the generator.     |
| help        | h     | Display help message.  |
| output      | o     | Sets the output file.  |
| version     | V     | Prints version number. |


* Formatting
In Apollon, formatting is done through 'commands',
currently there are only 11 basic commands.
They are as such:

| Long        | Short | Description                |
|-------------+-------+----------------------------|
| title       |       | Title of the document      |
| author      |       | Author of the document     |
| date        |       | Date written               |
|             | #     | Comment (not included)     |
| newline     | nl    | Forced newline             |
| nheader     | nhead | A numbered header          |
| header      | head  | A unnumbered header        |
| bold        | bl    | Bold text formatting       |
| italic      | il    | Italic text formatting     |
| bold-italic | bi    | Bold and italic formatting |

If no command is supplied then the text is not formatting in any special way.

Every command in Apollon is at the start of a line and followed by a colon (':').
For example:

#+begin_example
bl: This is bold,
and this is not
#+end_example

is valid, but something like:

#+begin_example
hello, il: world!
#+end_example

isn't valid, nor is having multiple commands on the same line like:

#+begin_example
bold: THIS il: is invalid
#+end_example

Newlines in apollon do not force a line break,
to force a line break use an empty line.
For example:

#+begin_example
bold: bold text
italic: and some italic on the same line!

But this is on a different line!
#+end_example

* Generators
Currently there are 2 inbuilt generators in Apollon (with plans to expand).
There is the ANSI (default) generator, and the HTML (generator).

** Ansi generator
The ANSI Generator is the default generator,
it outputs the text interspersed with ANSI control codes
for the formatting.
To read a file generated by the ANSI generator,
open up your favourite terminal and use:

#+begin_src shell
cat <file>.out
#+end_src

or any other file reading utility, such as 'less' or 'more'.

The use of a terminal emulator is important here,
most terminals interpret ANSI control codes for text formatting.
This is how the formatting works.
** HTML Generator
The HTML Generator tries to generate correct HTML documents.
Currently there isn't any support for custom style sheets, but it is in the works.

To view the generated HTML, open your favourite web browser and
go to "file://<Path to file>.html".