The --chars option
Florent Gallaire
%%mtime(%m/%d/%Y)

%!encoding: UTF-8
%!cc: by-sa

= Targets =

- All the ASCII-Art targets: aat, aap, aas and aaw. **12 chars length**.
- The reStructuredText target: rst. **8 chars length**.


== ASCII-art targets ==

=== Default values ===

|| corner | border | side | bar1 | bar2 | level2 | level3 | level4 | level5 | bullet | hhead | vhead
| + | - | | | - | =  | = | - | ^ | " | - | = | $

There is two exceptions:
- The hhead char of the tables with no border is bind to the border char, so its default value is **-**.
- The bullet char default value is ***** for the aap target.


=== Rendering ===

corner, border and side define box for first level titles (quotes and lists are also boxed by the aap target). They are used for the tables too, with hhead the horizontal header char and vhead the vertical header char:

```
                +------------------------------+
                | a first level title in a box |
                +------------------------------+

+---+-------+-------+
|   $   A   |   B   |
+===+=======+=======+
| 1 $ hhead | vhead |
+---+-------+-------+
| 2 $   =   |   $   |
+---+-------+-------+

```

bar1 is a thin horizontal line char:

```
------------------------------------------------------------------------
```

bar2 is a large horizontal line char:

```
========================================================================
```

level2, level3, level4 and level5 are underlined title chars:

```
level2
======

level3
------

level4
^^^^^^

level5
""""""
```

bullet is the bullet list char:

```
- first item
- other item
- last item
```

=== Valid chars ===

**The choice of the chars is completely free** in all the ASCII-Art targets.
There's only one limitation, **in UTF-8 encoding, the CJK double width chars are forbidden**, because of their double size which make them useless for the job:

```
7 chars
すすすす
```

== reStructuredText target ==

=== Default values ===

|| title | level1 | level2 | level3 | level4 | level5 | bar1 | bullet
| # | * | = | - | ^ | " | - | -


=== Rendering ===

title is the underlined and overlined document title char :

```
#####
title
#####
```

level1 is the underlined and overlined first level title char :

```
******
level1
******
```

level2, level3, level4 and level5 are underlined title chars:

```
level2
======

level3
------

level4
^^^^^^

level5
""""""
```

bar1 is a horizontal line char:

```
------------------------------------------------------------------------
```

bullet is the bullet list char:

```
- first item
- other item
- last item
```

=== Valid chars ===

Bullet list char must be chosen from the *** + -** chars.

All the others  must be chosen from the **! " # $ % & \ ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~** chars.
The = - ` : . ' " ~ ^ _ * + # chars are recommended.

%%cc