| author | Olivier Brunel
<jjk@jjacky.com> 2023-01-12 19:57:26 UTC |
| committer | Olivier Brunel
<jjk@jjacky.com> 2023-01-12 19:57:26 UTC |
| parent | 0d1937e6f15d9a4738693d7186edc81571a12920 |
| doc/qmdoc.1.md | +414 | -0 |
diff --git a/doc/qmdoc.1.md b/doc/qmdoc.1.md new file mode 100644 index 0000000..c2aa7c7 --- /dev/null +++ b/doc/qmdoc.1.md @@ -0,0 +1,414 @@ +% qmdoc manual +% qmdoc(1) +% qmdoc 0.0.0 + +# NAME + +qmdoc - Quick markdown documentation generator + +# SYNOPSIS + +*qmdoc* [`OPTION`..] `FILE`.. + +# 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. + + +: *-F* `FILE`, *--footer* `FILE` + +:: Insert `FILE` as footer on every generated page. `FILE` is expected to +:: contain valid HTML code, and will be inserted right before a page's `</body>` +:: tag. + + +: *-H* `FILE`, *--header* `FILE` + +:: Insert `FILE` as header on every generated page. `FILE` is expected to +:: contain valid HTML code, and will be inserted right after a page's `<body>` +:: tag. + + +: *-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). + + +: *-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. + + +: *-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 order they were processed. + +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. + +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. + +## 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 an special tag +`<TOC>` can be used, to be replaced by the global TOC. The rest of the page is +of course processed as usual. + +! 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 `<TOC>` tag. +! +! Of course if none was given, *qmdoc*'s internal one will be used as usual. + + +# 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. +* *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` + + +# 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)` + + +# 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