Read Me
Overview and build instructions for the mdterm project.
The mdterm project aims to create a lightweight markdown syntax for
use in terminals. The markdown language used bears no resemblance to
any existing markdown languages.
Highlights are:
Paragraphs begin with ^.
Paragraphs can have alignment, one of left, centre, or right. Full
alignment is not supported.
Paragraphs support a first-line-indent, an indent, and before and
after spacing. Indents are specified in character widths, and before
and after spacing as line counts.
For example:
- ^:left:0:0:0:0 specifies a paragraph that is left-aligned, with no
indent or before or after spacing.
- ^:right:2:1:0:0 specifies a paragraph with right-aligned text, with
each line indented two spaces and the first line indented one space
more than the regular indent. The first-line-indent is relative to
the line indent.
- ^:centre:0:0:0:0 specifies a centered paragraph.
- There are lists. There are bulleted lists, created with @, and
numbered lists, created with #. Up to six levels of indent are
supported by repeating the list marker. That is, ## creates a
second-level numbered lists. Numbering is automatic.
- Quotes can be created with ~.
- Text can be bold, underline, inverse, or any combination of the
three. To underline text, surround with _. To make it inverse, use |
either side of the text. For bold, use * either side of the text.
- To combine text effects, try *_boldunderline_*, *|boldinverse|*, and
|_inverseunderline_|
- Colours are supported using / followed by a colour name. For
example, /red, or /blue. Supported colours are:
- normal (resets to whatever the terminal considers normal)
- black
- red
- green
- brown
- blue
- magenta
- cyan
- white
To specify a background colour, use a colon and a new colour name. For
example, /red:blue red on blue /normal . To specify a background
colour without specifying a foreground colour, use /:bg. For example,
/:green will start text with a green background.
Building
A Makefile is provided to build the code. This project doesn't use
autotools so there's no configure step. Just make and it should build,
provided that:
- You have fpc installed on your path, and it's at least version 3.2
- You have Lazutils available in its default location of
/usr/lib64/lazarus/components/lazutils/lib/x86_64-linux. If you
have it somewhere else, specify it using:
make LAZUTF8=</path/to/lazutils>
On MacOS, for instance, it might be:
make LAZUTF8=/usr/local/share/lazarus/components/lazutils/lib/aarch64-darwin
- You have ncursesw available for linking. At least version 6. If fpc
doesn't find it during linking, you can specify additional lib
directories using make LIBS=</path/to/libs>. For example,
make LIBS=/usr/local/lib.
Supported make targets are:
- clean, to remove all build artifacts
- debug, to build debug versions of all objects,
- all, to build release versions of all objects,
- tests, to build everything and run all tests.
The default build target builds objs/mdviewer. This program can be fed
any text file and it will parse it for markdown syntax and output the
results. There are two example of markdown text files included with
the program, inputtext.txt and inputlists.txt. Both are found in the
top-level directory. To display one of them, run obj/mdviewer
<input-file>. For example:
obj/mdviewer inputtext.txt
The default make target also builds obj/mdfifo. This is similar to
mdviewer but it reads from a fifo. It creates a fifo at the path
specified using -f or --fifopath. It then opens and reads from that
fifo. Another program can then be launched to write to that fifo.