d5man/format(32)

# Definition of the D5 Manual Page Format

## 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

Manpages
• limited formatting options
• not to be edited by the user
• 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
LaTeX
• 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 instance)

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 and Grutatxt. 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 tab.
Text
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.
Escaping
\ 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.
Lists
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
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.
Sections
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).
Emphasizing
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
Shortcuts
Whenever keyboard shortcuts are to be entered, the necessary keys can be encoded like [CTRL]-[X] to display CTRLX.
Substitution
Special words and parts of text are automatically replaced whith nicer symbols for rendering. The table Symbol replacement lists all common substitutions.
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$ 23
 :)  (smiley) a ☺ b
3 e {4,5} $3\in\{3,5\}$  3 ∊ {3,5}

## Universal External Markup

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

{\img{file}{caption}}
Inserts the image attachment file file and associates the textual caption caption
{\code{language}}
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 hyphens.
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.
web_priority
Page priority ]0;1[ for website XML-sitemaps.

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 page.

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.

-1
TBD section
1
D5 Programs, Shell
2
D5 Programming languages (specification, examples)
3
D5 System specification a.k.a. D5 POSIX
4
The D5 internet
5
D5 map and telephone numbers (official catalogoues)
6
uncategorized
21
Java-API documentation
22
POSIX
23
PHP
24 … 2n
Other approved programming languages
31
Ma_Sys.ma general information (about), important Ma_Sys.ma developments, sort of preface and summary, Website special pages etc.
32
MDVL documentation (incl. recommended file formats, etc.)
33
34
Ma_Sys.ma nonprogrammatic developments (AyleidRuin and such)
35
Ma_Sys.ma Theory and Tactics, General/Standalone Documents
36
Ma_Sys.ma reviews and tests, introduction to other websites
37
Ma_Sys.ma misc articles (blog)
38
Ma_Sys.ma stories
39
Ma_Sys.ma Development notes
41
IAL
42
43
Captured temp. knowledge base (similar to ScrapBook w/ wkhtmltopdf).
44
xinfo.d5i` files (not part of the database)
5x
foreign manpages (x := section)
6x
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