d5man/format(32) Language: English

Definition of the D5 Manual Page Format

----------------------------------------------------------------------[ Meta ]--

name		d5man/format
section		32
description	Definition of the D5 Manual Page Format
tags		d5man format
compliance	public
lang		en
creation	2013/11
expires		2018/12
version		1.3.0

----------------------------------------------------------------[ Motivation ]--

Manpages can be considered one of the most efficient, useful and most reliable
way of storing textual information. Their features, however, are severely
limited making Manpages a bad choice for information to be displayed online or
in print form. Also, Manpages are designed to be distributed as part of a
program package which means that there is no workflow to edit them immediately
and efficiently.

Apart from Manpages there are LaTeX and XHTML documents each of which is
designed to be either used for printing or for the web. Although both of those
are useful means of storing information, especially XHTML as webbrowsers are
almost omnipresent, they remain limited to specific target devices and have
their own disadvantages.

The D5Man format has been designed to overcome many of the existing limitations.
For each format, the major disadvantages are listed below

 - limited formatting options
 - not to be edited by the user
 - unreadable markup language
 - sections are designed to be used specifically with UNIX systems

Websites (XHTML+CSS)
 - no simple means of rendering (Webbrowser with 300 MiB or more RAM required)
 - focuses too hard on layout, too little on content
 - the markup is not nice to read

 - rendering on textual devices is theorethically possible but there exist few
   tools to handle this situation
 - not useful for web based applications
 - difficult to process automatically (consider multiple pdfLaTeX runs for

Concerning the difficult readability of known markup formats, many alternatives
have emerged. Among the most popular is Markdown which is focused on websites.
Among the best of these formats are
reStructuredText(http://docutils.sourceforge.net/rst.html) and
Grutatxt(http://triptico.com/docs/grutatxt_markup.html). While both of them are
really good, there are minor disadvantages: reStructuredText can become
difficult to read once links are involved and Grutatxt is a bit too simple for
the task.

Extracting the best experiences from all these formats, the D5Man format has
been developed.

The following ideas have been taken from the other formats
 * a readable markup language (mainly taken from Grutatxt)
 * a means of controlling typrographic specialities like half spaces and forced
   spaces (from LaTeX)
 * a predefined document structure (inspired by Manpages)
 * sectioning after topic (taken from the Manpages)
 * advanced metadata (taken from XHTML compare `<meta .../>`)

Using this combination, the following new features have become possible
 * D5Man Pages can be rendered nicely in
    * Browsers (like XHTML)
    * Terminals (like Manpages)
    * and printed on paper (like LaTeX)
 * D5Man Pages can be edited WYSIWYG as the format is so readable the user can
   be trusted to view it directly.
    * This is further enhanced using syntax highlighting
 * Unlike Manpages or anything else, we do not even need an own program to read
   the files: VIM can do the job very well and if it is not at hand, any text
   editor may do.

-------------------------------------------------------------[ Main Elements ]--

If you want to get an idea what the D5Man format markup looks like, just check
the source code of this very page.

	A D5-Manpage starts with metadata in a key-value syntax with a tab
	separator. Tabs can be repeated as is necessary for a suitable
	representation in your editor. Configure your editor to use 8 spaces per
	Text can be entered without special attention. `\`` can be used to
	encode inline code, commands and filenames (just about any single words
	you would typeset in teletype font). Quotation is entered the same way
	as in LaTeX.
	`\\` is used to escape characters if necessary. This allows ```{`'' and
	similar characters to be entered directly. Be aware that escaping
	basically tells the parser to just ``ignore'' any functionality this
	character might have. Thus, if you want to write a text and make
	an immediate note in parenthes you only need to excape the
	first character, because that is the one the parser uses to find links.
	Example: ``HTML\(5) expert''.
External Markup
	Although often unreadable, a plaintext-like markup format can not avoid
	interfacing with other markup languages: Using the ``LaTeX''-Brackets
	`{` and `}` one can encapsulate LaTeX and XML using `{< ` and ` >}`
	(note that the first has a tailing, the second a leading space). If
	the TeX Math-Mode is entered immediately after the opening bracket,
	it can also be processed for website generation.
Raw text (``Code'')
	Text which is indented from the left and not part of a list or table is
	considered raw text. The initial level of indentation will be removed
	and the text will otherwise be left untouched.
	Links can be made in several forms. You can either link to a D5-Manpage
	by entering the name and section in brackets without a separating space.
	Otherwise you enter the text you want to link and then give the URL in
	brackets and as a third possibility you can just use `url(http://...)`
	to link to a specific URL.
	There are four types of lists which can be nested, except for
	description lists: You can create unordered lists prepending the `*`
	character to your text. Lists are nested via suitable indentation.
	Numbered lists use numbers and a `.` to number the elements just like
	expect them to be used and definition lists are simply a term followed
	by a newline and an indented description. The fourth type of list is a
	so-called ``pro-contra'' list which you create by using appropriate `+`
	and `-` signs as your list bullet. Nesting description lists with a
	single element and unordered lists is so common that such lists are
	specially treated and called ``titled'' lists. All list types except for
	description lists have to be indented.
	Tables use `o` to mark the top and bottom rule and `+` to create a mid
	line. Fields are separated with two spaces. Check ``Symbol replacement''
	for an example table.
	A section consists of `-` signs from the very beginning of a line then
	a `[`, a space, the section title another space and a terminating
	`]--\\n`. You can also create one level of subsections by creating a
	line of text which is underlined with dashes (just like the old
	Ma_Sys.ma Note Format).
	Put emphasis on important text by surrounding it with underscores (`_`).
	Emphasis is not recognized _inside_ a word because you need to be able
	to enter things like ``Dev_Swap'', ``Ma_Zentral'' or ``Ma_Sys.ma''
	Whenever keyboard shortcuts are to be entered, the necessary keys can
	be encoded like `[CTRL]-[X]` to display [CTRL]-[X].
	Special words and parts of text are automatically replaced whith nicer
	symbols for rendering. The table ``Symbol replacement'' lists all common
Space control
	Just like in LaTeX, you can enter forced half spaces using `\\,` and
	forced spaces using `~`.

	  Symbol replacement
	  Text         LaTeX                Symbol
	  `...`        `\\dots`             ...
	  `=>`         `$\\Rightarrow$`     =>
	  `->`         `$\\rightarrow$`     ->
	  `<-`         `$\\leftarrow$`      <-
	  `2^3`        `$2^3$`              2^3
	  ` :) `       (smiley)             a :) b
	  `3 e {4,5}`  `$3\\in\\{3,5\\}$ `  3 e \{3,5\}

-------------------------------------------------[ Universal External Markup ]--

The external markup described in this section is recognized by all renderers
except for WYSIWYG.

	Inserts the image attachment file `file` and associates the textual
	caption `caption`
	Helps the renderer to understand the source code language of following
	codes, i.\,e. enables syntax highlighting.
	Math-mode-only is also specially recognized.

---------------------------------------------------------------[ Meta fields ]--

After the fields, a meta section may contain any number of LaTeX commands
which are executed before any other LaTeX is processed. If the commands are
all written between `<` and `>` symbols, they are processed as XHTML instead.

`name` (REQ)
	An internal name for the page. Use `[0-9a-z_/]+` only.
	Imported pages are allowed to also use upper case letters, dots and
`section` (REQ)
	A numeric meta field to define the `d5man` section. Use `-1` for TBD.
`description` (REQ)
	A plaintext description which may not contain control sequences.
`tags` (REQ)
	Associates tags (form `[0-9a-z_]+`) separated with spaces.
	Tags are used to find the document through the different D5Man search
	functions like the UI, generated websites and `d5manquery`.
`encoding` (RC)
	Either `utf8` (`UTF-8`, `utf-8`) or `ascii` (`ASCII`). Defaults to
	`utf8`. _WARNING_ The field exists for future usage and reader
	information but is not evaluated by any D5Man applications which are all
	programmed to support UTF-8 and UTF-8 only
`compliance` (REQ)
	One of (becoming more and more public) `qqvx`, `qqv`, `secret`,
	`restricted`, `confidential`, `personal`, `internal`, `prerelease`,
	`informal`, `public`. Informal and public texts are allowed to be
	published on the internet. Prerelease texts are designed to be published
	sooner or later, internal texts may be shared but not be publicly
	available on the internet, personal texts might be shared but should not
	be included in IAL or Ma_Zentral DVDs, restricted texts are not to be
	shared, secret texts need special care and the two levels below _must_
	be encrypted.
	Repeat: public and informal are online, internal are in Ma_Zentral and
	MDVL, the rest not.
`lang` (REQ)
	The language the text is written in. This may either be `en` for English
	or `de` for German. The possibility to use `it` and `fr` is planned.
`creation` (RC)
	Time of creation (`YYYY[/MM[/DD [HH:mm[:ss]]]]`).
`copyright` (OPT)
	A copyright statement. The copyright statement may span across multiple
	lines (with the same indentation).
`version` (OPT)
	Version information in any application-specific format.
`expires` (OPT)
	Expiration date. Expiration is not defined as the document becoming
	automatically obsolete, but rather intended to be a sort of
        ``review required''. Interpretation and usage are up to the user.
	Expired documents can be queried with `d5manquery -e`
`location` (OPT)
	Redirects D5Man to another page. This may be a `file://` URL which is
	then opened with the default browser. _TODO N IMPL_
`attachments` (OPT)
	Space separated list of files considered attachments. These may be
	useful for enhancing websites and LaTeX targets w/ resource files.
`web_freq` (OPT)
	Change Frequency (always, hourly, daily, weekly, monthly, yearly, never)
	for website XML-sitemaps.
	Page priority ]0;1[ for website XML-sitemaps.

-----------------------------------------------------------[ Download Fields ]--

In addition to the fields listed above, there are some fields which are
specially designed to be used in conjunction with the Website export to
specify a ``download'' attached to a page. Unlike an `attachment`, these
downloads are given by URL and not by relative resource. Thus, these fields
are useful for external mirror links as well. Download URLs may not contain
spaces (use URL-encoding if spaces are required).

Finally, pages can support multiple downloads by giving them numbers starting
from 0 or 1 (a digit appended to all download field names, like e.g. `download1`
and `dlink1` for the second download etc.). If this feature is used, all
downloads must be ordered by their number, i.e. all fields for `download1`
occur before any field for `download2` etc. As download numbers are digits,
a maximum of ten downloads (0-9) is supported per page. If the number is
omitted (as is useful for only a single download), the number 0 is assumed.

Downloads can also be ``imported/linked'' from other pages by referencing their
page name and the download name (as given in the table). These references'
numbers are ignored and they do not count to the limit of ten downloads per

	  Additional Fields for Website Downloads
	  Field       Description
	  `dref`      Reference other download in form `page(section)/name`
	  `download`  Declares a download (internal name)
	  `ddescr`    Download description / title (UI name)
	  `dlink`     Target URL (or JavaScript link etc.)
	  `dsize`     Download size in KiB
	  `dchck`     Time last checked (format like `creation` field)
	  `dver`      Download version (human readable format)
	  `dchcksm`   SHA-256 of download contents

------------------------------------------------------------------[ Sections ]--

These `d5man`-Sections are already defined.

_TODO_ 32/33/34/35/36 need to be distributed differently. The number of
sections should be reduced so that useful and less useful texts are collected
in different sections. The difference between MDVL documentation and Ma_Sys.ma
Programs should mostly be eleminated as all important Ma_Sys.ma Programs except
for Ma_Zentral are part of MDVL and even that should somehow be merged into a
single platform.

	TBD section
	D5 Programs, Shell
	D5 Programming languages (specification, examples)
	D5 System specification a.k.a. D5 POSIX
	The D5 internet
	D5 map and ``telephone numbers'' (official catalogoues)

	Java-API documentation
24 ... 2n
	Other approved programming languages

	Ma_Sys.ma general information (``about''), important Ma_Sys.ma
	developments, sort of preface and summary, Website special pages etc.
	MDVL documentation (incl. recommended file formats, etc.)
	Ma_Sys.ma programs, scripts, readme files
	Ma_Sys.ma nonprogrammatic developments (AyleidRuin and such)
	Ma_Sys.ma Theory and Tactics, General/Standalone Documents
	Ma_Sys.ma reviews and tests, introduction to other websites
	Ma_Sys.ma misc articles (``blog'')
	Ma_Sys.ma stories
	Ma_Sys.ma Development notes

	Useful reading and user notes
	Captured temp. knowledge base (similar to ScrapBook w/ `wkhtmltopdf`).
	`xinfo.d5i` files (not part of the database)

	foreign manpages (x := section)

	reserved empty schema

Real D5 Manpages do not exist on earth => The single-letter sections are
reserved to be used by UNIX manpages.

New Scheme (see above)
 * -1 TBD
 * 1--8: Normal UNIX manpages, 11--18: same
 * 21..28 large pieces of documentation (IAL), 29 other IAL
 * 31 Ma_Sys.ma Website and general information
 * 32 MDVL & Ma_Zentral
 * 33 Legacy
 * 34 Mods
 * 35 (not public: UNI notes)
 * 37 blog
 * 38 stories
 * 39 dev. notes
 * 42 user notes
 * other sections remain underspecified

Zum Seitenanfang