% qmdoc manual
% qmdoc(1)
% qmdoc 0.1.0
% 2023-01-16
# NAME
qmdoc - Quick markdown documentation generator
# SYNOPSIS
*qmdoc* [`OPTION`..] `FILE|DIR`..
# DESCRIPTION
*qmdoc* is a small tool to generate static HTML documentation from MarkDown
files. The generated documentation is only made of HTML and CSS, without any
JavaScript.
# OPTIONS
: *-a*, *--author* `AUTHOR`
:: Will use `AUTHOR` as author name for the generated documentation. It will be
featured inside a meta tag as well as in the footer of generated pages.
: *-b*, *--buttons*
:: Will add /Previous/ and /Next/ buttons on the bottom of generated pages.
: *-C*, *--no-css*
:: Do not include *qmdoc*'s own CSS. Any custom CSS specified via `--css` will
:: still be processed.
: *-c* `FILE`, *--css* `FILE`
:: Use `FILE` as additional custom CSS. By default *qmdoc* comes with its own
:: CSS and generated pages are thus fully styled.
:: You can however add styling of your own, in which case references to the
:: specified `FILE` will be added to generated pages, alongside *qmdoc*'s own
:: CSS.
:: ! WARNING: Limitations
:: ! Note that only one CSS file can be added. If used multiple times, only the
:: ! last value of `FILE` will be used.
: *-d* `DIR`, *--destdir* `DIR`
:: Write generated pages (and CSS files) into `DIR` instead of current
:: directory.
: *--dir* `TYPE`
:: When a directory was given as argument, start either a new group (`group`)
:: or sorting group (`sort`) with the files from said directory. Defaults to
:: `sort`.
:: See [[GROUPS AND SORTING GROUPS]] for more.
: *-F* `FILE`, *--footer* `FILE`
:: Insert `FILE` as footer on every generated page. `FILE` is expected to
:: contain valid HTML code, and will be inserted as-is on top of the page's
:: content.
:: ! HINT:
:: ! You can have the content of `FILE` inserted right at the opening of the
:: ! `body` tag by using `--wide-include`
: *-H* `FILE`, *--header* `FILE`
:: Insert `FILE` as header on every generated page. `FILE` is expected to
:: contain valid HTML code, and will be inserted as-is on bottom of the page's
:: content.
:: ! HINT:
:: ! You can have the content of `FILE` inserted right before the closing of the
:: ! `body` tag by using `--wide-include`
: *-h*, *--help*
:: Show the help screen and exit.
: *-I*, *--inline-css*
:: Use inline CSS instead of external files. By default *qmdoc* will copy its
:: own CSS as `qmdoc.css` alongside the generated pages, and reference it via a
:: `<link>` tag.
:: When this option is used, the actual CSS is placed on every page inside a
:: `<style>` block, obviously leading to larger files. It might be interesting
:: when generating a single page, to obtain a self-contained HTML file without
:: any other dependencies.
:: ! INFO:
:: ! If you add custom CSS using `--css` it will also be inlined, in a separate
:: `<style>` block.
: *-i*, *--index*
:: Force index mode, that is creation of an index page containing the overall
table of contents for the entire generated documentation.
:: See [[INDEX MODE]] for more information.
: *-l* `LNG`, *--lang* `LNG`
:: Set `LNG` as language attribute, used as value for the `lang` attribute of
:: the `<html>` tag of generated pages.
: *-M* `URL`, *--man-url* `URL`
:: Use `URL` as prefix for external man-page links. That is, when a so-called
:: /man-page links/ can't be resolved internally, use `URL` as prefix for the
:: link.
::
:: For example, with `URL` set to `http://www.example.com/man/` the following
:: would result in a link to `http://www.example.com/man/foobar.1.html` :
::
:: ```md
:: See [foobar](1) for more.
:: ```
::
:: ! INFO:
:: ! The given `URL` is used as-is as prefix, to which is added the text from
:: ! the link, followed by a dot, the section number, and the `.html` extension.
:: !
:: ! It is up to you to ensure the resulting URL will be valid, e.g. make sure
:: ! it ends with a slash (`/`), an equal sign (e.g. `...&page=`) or whatever is
:: ! needed.
::
:: See [[MAN-PAGE LINKS]] for more.
: *-o*, *--overwrite*
:: Overwrite destination files without confirmation if they already exist.
: *-s* `TEXT`, *--subtitle* `TEXT`
:: Set `TEXT` as general subtitle. It will be featured right below the general
:: title (see `--title`) on the left-side of each pages (above its TOC).
: *--subdir* `TYPE`
:: When reading a directory and encountering a sub-directory, start either a new
:: group (`group`) or sorting group (`sort`) with the files from said
:: sub-directory. Defaults to `group`.
:: See [[GROUPS AND SORTING GROUPS]] for more.
: *--sharedir* `DIR`
:: Use `DIR` as directory to look for *qmdoc*'s own CSS files.
: *--sort-group* `SORT`
:: Use `SORT` as sort order when sorting groups. Can be either `title` (default)
:: to sort using the page's title, or `file` to use the file's name.
:: You can also prefix it with `d:` to use descending sort order, instead of the
:: default ascending sort order.
:: ! HINT:
:: ! You can simply use `d:` to only set descending direction.
:: !
:: ! It is also possible to abbreviate the possible values, so one could use
:: ! e.g. `--sort-group d:fi` to set descending sorting by file names.
:: See [[GROUPS AND SORTING GROUPS]] for more.
: *-T*, *--no-toc*
:: Don't write a table of contents on each page. The entire left column of
:: generated pages will not be featured (including `--title` and `--subtitle`).
:: This implies `--no-index`
: *-t* `TITLE`, *--title* `TITLE`
:: Set `TITLE` as general title. It will be featured on top of the TOC of every
:: generated pages. Defaults to "Documentation".
: *-W*, *--wide-include*
:: When using `--header` and/or `--footer` the content of the specified file is
:: included within the page's `<section>`, thus appearing on top/bottom of the
:: page's content (i.e. on the right side, "after"/next to the Table of
:: Contents).
:: When using `--wide-include` it will be inserted right after the opening of
:: the `<body>` for the header, right before its closing for the footer.
: *-X*, *--no-index*
:: Disable index mode. See [[INDEX MODE]] for more information.
# PAGE HEADER
For every file to process, *qmdoc* will check for a /page header/ in the first
lines.
From the begining of a file, every line starting with a percent sign and a space
will be considered an header line. The first line /not/ to start with the
percent sign & space will mark the begining of the content to convert.
Up to four lines are recognized by *qmdoc*, all of them are optional. You can
effectively include as many header line as you need : the first four will be
processed as described below, while others will simply be ignored.
The first line is used to set the page's title. Said title will be used for
the `<title>` tag of the page, as well as in the Table of Contents.
If not specified, the file name (including the `.html` extension) is used
instead.
## Man page mode
The three other lines are intended for use in the writing of man pages. They
consist of the following :
2. the name field
3. the version field
4. the date field
The first field (second line) is "required" in the sense that you need to
specify one in order to enable the man page mode, else all are ignored.
Other fields are optional; meaning that if you only wanted to specify a name
and date field, without version field, you would simply leave the version field
empty (i.e. leaving only the header mark), e.g:
% Page Title
% Some Name
%
% Date goes here
Once a name is present, and man page mode enabled, the other fields have default
values to be used when left unspecified :
* Version field defaults to name field
* Date field defaults to page title
### Results
Man page mode results in an additional line added on top and bottom of the page.
Each consists of three sections : left, middle and right. They are filled as
follows :
```
NAME TITLE NAME
VERSION DATE NAME
```
Lastly, the page title used in the `<title>` tag will consist of the name
field and the title field (given on first header line), concatenated with a
dash. E.g: `NAME - TITLE`
Note that on the TOC only the name field will be used.
Thusly, one can get a typical man-page look, for example when first written this
page used the following header :
```md
% qmdoc manual
% qmdoc(1)
% qmdoc 0.1.0
% 2023-01
```
# INDEX MODE
For every generated page, *qmdoc* will generate the page's TOC (table of
contents) using the different titles it contains. The resulting TOC will be
featured on the left side, alongside links to every other generated pages in the
same group.
In addition, the so-called /index mode/ will have *qmdoc* generate a global TOC
(comprised of the TOCs of all pages) and generate an `index.html` file featuring
said global TOC, as well as an alphabetical index of all pages & links.
This `index.html` will also be linked from every page, as if it was the first
generated page, titled "Table of Contents".
You can disable index mode by specifying `--no-index`. Each page will still
feature its own TOC with links to other generated pages. You can also disable
such TOCs using the `--no-toc` option.
## Customize the global TOC
By default, index mode is enabled if no `index.md` was given - and thus no
`index.html` would have been generated - or if one was given as first file to be
processed.
In the later case the file will actually be generated /last/, and some special
tags can be used :
- Special tag `<TOC>` can be used, to be replaced with the global TOC.
- Special tag `<INDEX>` can be used, to be replaced with an alphabetical index
of all pages & links processed.
! HINT:
! You can also force index mode via `--index` so that if an `index.md` was
! specified, regardless of its position, it will be processed last and support
! the special tags.
!
! Of course if none was given, *qmdoc*'s internal one will be used as usual.
# GROUPS AND SORTING GROUPS
In addition to files, it is possible to specify directories as arguments for
*qmdoc* to process. In such a case, it will read the directory's content and
process every file it contains whose name ends in `.md`
Directories are scanned recursively, meaning that any subdirectory will also be
scanned and its files be processed.
Because when reading a directory the order in which entries (files) are read is
undetermined (aka random), it is necessary to sort them. To do so, *qmdoc* uses
the notion of "groups".
## Groups
Files can be grouped together, and sorting files will be done group by group.
Every time a directory was specified on command line, a new group is created in
which all the directory's files will be put.
Similarly, when a subdirectory in encountered a new group is created as well.
By default, files will be sorted by their page's title in ascending order
This can be changed using the `--sort-group` option. Possible values are `title`
(default) and `file`, to use file names. One can also prefix the value with `d:`
to have them sorted in descending order.
! WARN: Special man-page sorting
! Note that when sorting by page's title, a special handling is done for pages
! whose titles are matching a man page, i.e. their title ends with a number
! between 0 and 9 (both included) in parenthesis.
!
! When two such pages are compared, and are not in the same section (the number
! in between the parenthesis), then pages are ordered based on their section
! number.
## Sorting groups
Two kinds of groups are actually supported : regular groups, and sorting groups.
The difference between the two only comes with regard to each page's table of
content (TOC), i.e. regular groups are an extension over sorting groups.
By default, all pages are featured on the TOC found on every generated page.
However, when groups are involved, only pages from the same group will be
featured.
! INFO:
! Note that this only applies to page's TOC, the global TOC generated via the
! `<TOC>` tag in the index includes all pages from all groups.
## Manually grouping pages
No group exists by default, allowing one to define the order in which pages will
be processed/generated via the order they're given on command-line.
However, it is possible to group files without using directories, by using
special arguments :
- Using `+sg` as argument will start a new sorting group;
- Using `+g` as argument will start a new (regular) group.
That way, one can easily specify a bunch of files to processed, and have them be
sorted.
You can use as many such arguments as needed, in whatever order needed. Note
that, however, once a (sorting) group has been added (manually or by specifying
a directory), it is not possible to specify a manual order of processing, since
every file from then on will be in a (sorting) group.
Consider the following example :
```sh
qmdoc first.md +g *.md
```
The TOC on the page from `first.md` will not include links to any other files,
similarly all other pages' TOC will not include links to the `first.md` page.
While the shell is likely to expand `*.md` in a sorted fashion, it should be
worthy to note here that because files are in a group, they will be sorted by
*qmdoc* and, by default, using their titles (not their file names).
Another example :
```sh
qmdoc first.md +sg foo*.md bar*.md +sg *.md
```
All files whose name begin with either `foo` or `bar` will be sorted/listed
together after `first.md`, all the other files will be sorted/listed on their
own afterwards.
! HINT:
! As the observant reader might have noticed, it is possible to have the same
! file appear multiple times. *qmdoc* will simply ignore any repeated
! occurrence.
# SYMLINKS
Symbolic links are handled in a special manner, in order to allow one page to
have multiple names linking to it.
## Restrictions
First off, such special handling only applies to symlinks that do /not/ contain
any slashes (`/`) in their content. In other words, they must point to a
different file, or name, within the same directory.
! HINT:
! It is therefore possible to "disable" this feature for a link by having it
! point to `./target` instead of simply `target`
In addition, this only applies to [[MAN-PAGE LINKS]] and [[INTRA-LINKS]], not
"regular" links. This is simply because in the later case you specify a target
for the link, and that target is used as-is. It is up to you to ensure it will
actually point to something that does exist.
## Handling
When a symlink without slashes is found, instead of opening/processing the file
pointed to, *qmdoc* will simply remember that any link (in any of the processed
pages) to it shall be made to the pointed page instead.
As a result, no page is actually processed/generated from such symlinks, but any
link /to/ the symlink will be properly placed, pointing to the page it points
to.
For this reason, one last limitation is in effect: If a symlink points to a
non-existent page, it will have no effect.
## Example
So, imagine you've written a small library and you want one single page
documenting two functions, because things are simpler/easier that way. What you
can do then, is have you page written under e.g. `foobar.3.md` and then have a
symlink `barfoo.3.md` pointing to it.
As a result, *qmdoc* will only generate a single file - namely `foobar.3.html` -
but if in any other pages you have a links such as `[barfoo](3)` then a link
will be made, only pointing to `foobar.3.html`, as per the symlink.
# MARKDOWN SYNTAX
*qmdoc* is using [md4c] as parser, and as such is mostly compliant with
[CommonMark specification](http://spec.commonmark.org/) version 0.30.
/Mostly/, because a set of specific extensions has been added to help with our
intended use of creating/writing documentation.
## Emphasis & the likes
The way to set emphasis and other style has been adjusted :
* Text in between stars (e.g. `*foobar*`) will be *bold*
* Text in between slashes (e.g. `/foobar/`) will be /italic/
* Text in between underscores (e.g. `_foobar_`) will be _underlined_
* Text in between tildes (e.g. `~foobar~`) will be ~striked~
* Text in between equal signs (e.g. `=foobar=`) will be =highlighted=
## Code blocks
Code blocks are supported, either by indentation or as fenced blocks, i.e.
enclosed in lines beginning with 3 tildes or more.
Fenced code blocks can have a text featured on the opening line, after the
tildes (referred to as /info string/). The first word (space-separated) is used
as indication for the "language" of the block.
This is only used by *qmdoc* to be featured in a little blue box on the top-left
corner of the block, as indication to the reader.
### Attributes
Additionaly, custom parameters can be specified, in the `key[=value]` form :
* *hl* : Enable highlighting effects. Then, any text in between `<hl>` and
`</hl>` tags will be =highlighted=, in between `<em>` and `</em>` will be in
/italic/, and in between `<b>` and `</b>` will be in *bold*.
* *from=`N`* : Enable line numbering, starting from `N`
Line numbering is also automatically enabled for any fenced code blocks /unless/
its language is set to `pre`
! HINT:
! It is of course possible to have line numbering for `pre` blocks, either by
! using another term as language, e.g. `raw`, or by adding `from=1`
!
! You can also use `from=0` to disable the line numbers, all the while keeping
! the alternate line background as well as language name being shown.
# INDENTATION
*qmdoc* also supports indented text : lines starting with a colon (`:`) will be
intended. It is possible to use more than one colon to increase the indentation.
This was for example used in the [[OPTIONS]] section, to indent option names,
and indent /more/ the descriptions.
# BOXES
Special boxes are supported, by give out informations, hints or warnings. This
is done by creating a block of text, made up of lines all beginning with an
exclamation point.
The first line is a special line, it must contain the /type/ of box to create
(default is `WARNING`) followed by a colon, and optionally a title.
Supported types are :
* `WARNING` : For warnings, default title: "Warning"
* `INFO` : For informations, default title: "Information"
* `HINT` : For hints, default title: "Hint"
* `NOTE` : For notes, default title: "Note"
If no supported type is found, the entire line is used as title for a `WARNING`
box.
## Example
To get the following box :
! Test
! This is some =warning=.
You would use this mardown source :
```md
! Test
! This is some =warning=.
```
You can of course use regular MarkDown syntax within such boxes, including
code blocks.
# MAN-PAGE LINKS
*qmdoc* will recognize special link, so-called /man-page links/, as links whose
target is nothing but a single digit from 1 to 8 (included) - and process them
differently.
For example, the following would be recognized as a man-page link:
```md
See [foobar](1) for more.
```
Such links are processed in a special manner to allow ease of man-page
creations :
- Firstly, a file name is constructed as target for the link. This file name
will be the text of the link (between brackets), then a dot, the section
number, and the `.html` extension. E.g: `foobar.1.html`
- Then, *qmdoc* checks to see if such a page has been or will be generated. If
so, an "internal" link to said page is created.
- If no such page has been nor will be generated, it checks if a prefix URL was
specified via the `--man-url` option. If so, a link constructed by using the
given prefix followed by the target file name is created.
- Else, no link is created, and *qmdoc* simply outputs what would otherwise be
the text of the link : the text of the link, followed by the section number in
between parenthesis; E.g: `foobar(1)`
Note that the text of the link will be in bold, even when no link is created.
# INTRA LINKS
In addition to regular and man-page links, *qmdoc* also recognize another kind
of links, sometimes known as "/wiki-links/". However, they have nothing to do
with wiki here, only their syntax is similar :
[[target]]
[[target|some text]]
The later form allows you to use the specified /some text/ as text for the link.
As for the link, it will point to :
* If the target is the file name of a page, minus the extension (e.g. "foobar"
for a file named `foobar.md`) then a link to said page (e.g. `foobar.html`) is
generated,
* Else, it is assumed to be a title from the current page, and a link to its
anchor is generated.
The later is what allows to easily link to a section within the page, e.g. to
link to this very section you could simply use `[[INTRA LINKS]]`.
[md4c]: https://github.com/mity/md4c