{"id":18974484,"url":"https://github.com/m7a/bo-d5man2","last_synced_at":"2025-06-29T16:33:40.187Z","repository":{"id":164551899,"uuid":"223647482","full_name":"m7a/bo-d5man2","owner":"m7a","description":"Ma_Sys.ma D5Man searches and processes self-created and existing documentation with a single-user offline scenario in mind.","archived":false,"fork":false,"pushed_at":"2024-05-31T20:27:07.000Z","size":417,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-01T09:07:56.624Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m7a.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-23T20:17:48.000Z","updated_at":"2024-05-31T20:27:10.000Z","dependencies_parsed_at":"2024-05-31T21:41:34.814Z","dependency_job_id":null,"html_url":"https://github.com/m7a/bo-d5man2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m7a%2Fbo-d5man2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m7a%2Fbo-d5man2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m7a%2Fbo-d5man2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m7a%2Fbo-d5man2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m7a","download_url":"https://codeload.github.com/m7a/bo-d5man2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239972038,"owners_count":19727290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T15:15:13.613Z","updated_at":"2025-02-21T07:23:16.063Z","avatar_url":"https://github.com/m7a.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\nsection: 32\nx-masysma-name: d5man2\ntitle: Ma_Sys.ma D5Man 2\ndate: 2019/12/06 13:16:32\nlang: en-US\nauthor: [\"Linux-Fan, Ma_Sys.ma (Ma_Sys.ma@web.de)\"]\nkeywords: [\"d5man\", \"d5man2\", \"d5manapi\", \"d5mantui\"]\nx-masysma-version: 2.1.0\nx-masysma-repository: https://www.github.com/m7a/bo-d5man2\nx-masysma-website: https://masysma.net/32/d5man2.xhtml\nx-masysma-owned: 1\nx-masysma-copyright: (c) 2019--2024 Ma_Sys.ma \u003cinfo@masysma.net\u003e.\n---\nOverview\n========\n\nMa_Sys.ma D5Man 2 is a set of programs and auxiliary resources intended to build\na locally run knowledge base. It consists of the following individual\ncomponents:\n\n`d5mantui`\n:   _Terminal User Interface_ as an interactive means to query for D5Man pages.\n    See `d5mantui` for details.\nd5manexport\n:   Multiple programs to export a special instance of pandoc's Markdown by\n    invoking the `pandoc` utility (not part of D5Man). Two export scripts are\n    supplied: `d5manexportpdf` exports a single page to a printable PDF\n    document; `d5manexporthtml` exports a whole directory structure of D5Man\n    pages to a specified directory.\nAuxiliary Resources\n:   The package provides a syntax file `markdown.vim` as a replacement for VIM's\n    default Markdown style. This style makes sections more visible and is\n    loosely inspired by the style used in D5Man Legacy.\n\nThis version “D5Man 2” replaces D5Man Legacy which was an attempt to achieve\na similar outcome but in a much more sophisticated manner leading to excessive\ncomplexity.\n\nD5Man Structure and Concepts\n============================\n\nD5Man is centered around the concept of _D5Man pages_: A D5Man page is a text\nfile written in a subset of pandoc's Markdown together with a minimum amount of\nmetadata in YAML format and with optional attachment files. The details of the\nformat are described under _D5Man Format 2_.\n\n## Filesystem Structure\n\nTwo ways of organizing D5Man pages on file systems are recommended:\n\n 1. Document-Root: A directory structure which consists only of D5Man pages\n    (or other data processable by the D5Man API Server). On the top-level there\n    is one directory per _section_ and the respective sections contain\n    one ore multiple D5Man documents each.\n 2. Program-Root: A directory structure which consists of programs'\n    repositories. Here, pages are represented by the files named `README.md`\n    in the subdirectories of the root.\n\nA third option is _detached_, that is a directory unknown to the D5Man programs\nwhich contains one or more pages. Such files are not found by the D5Man API\nServer but can still be converted to PDF.\n\n### Example for a Document-Root Structure: Ma_Sys.ma Website\n\n\t/rr\n\t |\n\t +-- 31/\n\t |    |\n\t |    +-- web_about_att/\n\t |    |    |\n\t |    |    +-- ...\n\t |    |\n\t |    +-- web_news_att/\n\t |    |    |\n\t |    |    +-- ...\n\t |    |\n\t |    +-- ...\n\t |    |\n\t |    +-- web_about.md\n\t |    |\n\t |    +-- web_news.md\n\t |    |\n\t |    +-- ...\n\t |\n\t +-- ...\n\n### Example for a Program-Root Structure: Ma_Sys.ma Repositories\n\n\t/rr\n\t |\n\t +-- bo-adler32/\n\t |    |\n\t |    +-- README.md\n\t |    |\n\t |    +-- ...\n\t |\n\t +-- bo-big/\n\t |    |\n\t |    +-- big4_att/\n\t |    |    |\n\t |    |    +-- screenshot3.png\n\t |    |\n\t |    +-- README.md\n\t |    |\n\t |    +-- ...\n\t |\n\t +-- ...\n\n## Concept\n\nD5Man is designed as a sort of personal Wiki that can have a published part. To\nachieve the separation between published and private parts, different _sections_\nare used. Each page is assigned a section, which by convention is a number of\ntwo digits (i.e. ranges from 10 to 99).\n\n * Pages are created, edited and viewed in a text editor which is by default\n   configured to be [VIM](https://www.vim.org/).\n * If ready for the Internet, pages are exported to XHTML and can then be\n   uploaded to any webspace. Alternatively, if pages are to be printed, they\n   can be exported to PDF. All export uses [Pandoc](https://www.pandoc.org/)\n   internally.\n * The D5Man User Interface runs in a terminal emulator. This way, all\n   interactive parts are available from the commandline. Additionally, for\n   “browsing” large pieces of information (like e.g. an API documentation),\n   a web-based interface is desirable. Thus there is also a read-only\n   web-based interface for exactly that purpose called IAL\n   (_Information and Links_) as a separate program, see [ial(32)](ial.xhtml).\n\nA typical workflow for creating a page is as follows:\n\n 1. Create an empty page by copying from a template file (`d5man2.md`) to a\n    file in a section directory or repository's `README.md`.\n 2. Populate the file with information.\n 3. Optionally: Export the file to target format of choice and print it or\n    upload it to the Internet.\n\nTo edit or recall a page, enter a prefix of the page's name in `d5mantui` and\nonce it appears in the search results, open it by pressing ENTER.\n\n## Benefits\n\nCompared to other personal Wiki approaches, D5Man provides the following\nset of advantages:\n\n * _Terminal-only workflow_ possible. This allows for good integration into\n   an environment where most applications in use are also running in terminals.\n * Full control over _individual files_: D5Man does not write to the documents\n   below the “roots” except for creating new pages. Apart from that, writing is\n   the sole responsibility of the text editor. Additionally, pages exist as\n   dedicated files allowing existing backup procedures to be effective for\n   saving D5Man files as well.\n * _Partial Publishing_. It is possible to publish only a subset of the\n   actually present documents as to distinguish between public and private\n   information. Use of different sections for this purpose makes the distinction\n   clear at all times.\n * _Balanced Markup_ Language. D5Man Legacy proposed an own syntax. While it\n   is superior in certain aspects, it turned out to be too difficult to parse\n   correctly. Thus D5Man 2 uses a thoughtfully crafted subset of Pandoc's\n   Markdown which ensures compatibility with printed and web-based formats and\n   provides reasonably well-readable and easily editable source files.\n * _Minimality_. After a failed attempt to develop a “large” system for the\n   purpose, D5Man 2 stays minimal. At the core (Perl and Erlang parts), its\n   source code is less than 1000 lines of code!\n\n## Alternatives\n\nThere are countless approaches to do _static blogs_ or _personal wikis_.\n\n### Static website generation with Markdown\n\nClose-to-comprehensive list: \u003chttps://www.staticgen.com/\u003e, some candiates:\n[Hugo](https://gohugo.io/), [Jekyll](https://jekyllrb.com/)\n\n### Local Wikis\n\n * Dedicated wiki: [DokuWiki](https://www.dokuwiki.org/dokuwiki)\n * [Fossil SCM](https://www.fossil-scm.org/home/doc/trunk/www/index.wiki)\n   integrates a Wiki and Issue Tracker storing all data in an SQLite database.\n * [EMACS Org-Mode](https://orgmode.org/)\n\n### Using VIM as a personal notekeeping application or Wiki\n\n * with help files:\n   \u003chttps://vim.fandom.com/wiki/Add_your_note_files_to_Vim_help\u003e,\n   \u003chttps://vim.fandom.com/wiki/Keep_a_to-do_memo_file_with_links_as_in_Vim_help\u003e\n * with vimwiki: \u003chttps://github.com/vimwiki/vimwiki\u003e,\n   \u003chttps://github.com/lervag/wiki.vim\u003e\n * \u003chttps://github.com/tomtom/vikibase_vim\u003e\n\nD5Man Format 2\n==============\n\nIf you are interested in the old D5Man Legacy format, see\n[d5man/legacy(32)](d5man_legacy.xhtml). Here, a selected subset of the elements\nfrom the rich syntax described in the Pandoc documentation is presented in order\nto obtain a sensible subset. Of course, there is no technical restriction for\nsticking to this subset.\n\nD5Man's text format is expected to always be read and written in UTF-8 encoding.\n\n## Metadata\n\nA D5Man 2 Document begins with a header of following form:\n\n~~~{.yaml}\n---\nsection: 32\nx-masysma-name: d5man2\ntitle: Ma_Sys.ma D5Man 2\nlang: en-US\nauthor: [\"Linux-Fan, Ma_Sys.ma (Ma_Sys.ma@web.de)\"]\nkeywords: [\"d5man\", \"d5man2\", \"d5manapi\", \"d5mantui\", \"ial\"]\n---\n~~~\n\nThis header which follows YAML syntax is called the _metadata_ in D5Man. It\nis a set of key-value assignments of form `key: value`. All fields which do\nnot have any special meaning for Pandoc are prefixed `x-masysma-` as to indicate\nthat they are additional fields used for D5Man. The use of the fields is as\nfollows:\n\n`section` (required)\n:   Defines the _section_ this page is part of. It is not really used in its\n    Pandoc meaning (which would be the section for an actual manpage exported\n    from the document), but the concept of D5Man manpages and actual manpages\n    is similar to some extent (both provide textual information).\n`title` (required)\n:   Defines a document title (in legacy D5Man called `description`) which\n    is a single large heading to go above the document.\n`lang` (optional)\n:   Gives the language in which the document (and/or its metadata) are written.\n`author` (optional)\n:   Gives a list of authors. Syntax `[\"Linux-Fan, Ma_Sys.ma...\"]` creates a\n    YAML list with just one element in the example above.\n`keywords` (required)\n:   A list of keywords (also in YAML syntax) to assign to the page. Note that\n    D5Man API search querys consider only `x-masysma-name`, `section` and\n    `keywords` and matches case-sensitively against prefixes. It is thus\n    often useful to provide sensible subsets of the page's name in the\n    `keywords` section. In legacy D5Man, this was called `tags`.\n`date` (optional)\n:   Specifies the date of document creation in `YYYY/MM/DD HH:ii:ss` format.\n`toc` (optional)\n:   Controls the generation of a table of contents for PDF exports\n    (processed by pandoc only).\n`x-masysma-name` (required)\n:   Determines the page's name. For newly created pages, it is recommended to\n    chose names satisfying the regex `[a-z0-9_/]+`. Other names are\n    supported, but may not contain any whitespace or other characters that\n    are uncommon in file names processed by scripts (except for `/`).\n    For _Document-Root_ organizazion, the file name should be the page's\n    name with `/` replaced by `_` and an additional `.md` suffix. For tasks,\n    suffix `.hot` should be used.\n`x-masysma-task-priority` (required and only allowed for tasks)\n:   Specifies the priority of this task (cf. section _D5Man TUI Task\n    Management_). Allowed values are the following:\n    red, green, black, white, yellow, purple, delayed, considered.\n`x-masysma-task-type` (required and only allowed for tasks)\n:   Specifies the type fo this task (cf. section _D5Man TUI Task Management_).\n    Allowed values are the following: long, short, subtask, periodic.\n`x-masysma-version`, `x-masysma-copyright` (optional)\n:   Specifies a version and copyright for the document (and the program it is\n    describing). Format and use of these fields are entirely up to the user.\n`x-masysma-repository` (optional)\n:   Provides a link to the source code repository associated with the document\n    and/or the software it describes.\n`x-masysma-website` (optional)\n:   Provides a link to the respective page on the (Ma_Sys.ma) Website. This\n    allows e.g. Github users to find the Website which provides a\n    correctly exported (i.e. readable) version of the distorted view that\n    Github creates out of D5Man's Markdown files.\n`x-masysma-owned` (optional)\n:   If present, this enables the inclusion of Ma_Sys.ma Logo and Icons in\n    exported PDF files. Of course, the logos can also be replaced by different\n    ones for local usage. Or one can leave out this key to avoid the\n    use of logos in the export results altogether.\n`x-masysma-redirect` (optional)\n:   This field either gives an absolute URL (`https://...`) or a file name.\n    In case a file name is given, the given file (relative to the attachment\n    directory) is opened instead of opening the page when running from\n    D5Man TUI. All pages available through IAL need to supply this field.\n`x-masysma-download` (optional)\n:   Specify an URL for downloading a file (used for Website generation).\n`x-masysma-web-priority`, `x-masysma-web-changefreq` (optional)\n:   Defines a priority (0.0--1.0) and a change frequency (monthly, weekly etc.)\n    to be used in sitemaps generated during the XHTML export.\n    Default is priority=0.4, changefreq=monthly.\n`x-masysma-expires` (optional)\n:   Expiry date. Same format as `date`. The meaning of this field is up to\n    the user's interpretation.\n\n### Section Structure\n\nThe section structure used by the Ma_Sys.ma is as given in the following table.\n\nSec  Short Description\n---  --------------------------------------------------------------------------\n11   Documentation in the style of a classical man-page.\n21   IAL as generated from documentation\n22   IAL hand-added files\n23   IAL internal\n31   Website pages providing general website content (navigation, license, ...).\n32   Documentation for current Ma_Sys.ma developments (programs, scripts, etc.)\n33   Legacy (_currently unused_)\n34   Creative section with Mods and Stories\n35   not public: UNI notes\n37   Blog, Knowledge Base, self-contained pages, other public notes\n42   not public: user notes\n43   not public: tasks\n\n## Attachments\n\nBy convention, images included in the document are stored in a directory\ncalled the same as the page's name with (`/` replaced by `_`) and a suffix\n`_att` (instead of `.md`).\n\nFor instance, this `README.md` has name `d5man2` thus the attachments would\nbe stored in a directory `d5man2_att` next to the file. For page `d5man/legacy`,\nattachments go to `d5man_legacy_att` etc.\n\nAdditionally, images which are supplied in vector formats (SVG or PDF) are\nincluded by their file name _without extension_. This allows the LaTeX\nexport to use a PDF file and the XHTML export to use a SVG file without\nchanging the source file. Finally, D5Man's XHTML export also instantiates\na simple automatic conversion from PDF to SVG in order to avoid storing\nredundant vector graphics in the attachments directory.\n\nUnlike legacy D5Man, an explicit list of all files attached is no longer needed\nto be declared in the documents themselves.\n\n## Top-Level Structure\n\nDocuments consist of the leading metadata block (see _Metadata_) followed by\na D5Man document which consists of headings, lists, tables, code and paragraphs.\n\n## Headings\n\nD5Man proposes three levels of headings.\nThe top-level headings are underlined by equals signs.\nThe second-level headings are prefixed by `## ` (hash-hash-space).\nThe third-level headings are prefixed by `### ` (hash-hash-hash-space).\nThe following code shows all the heading styles.\n\n~~~{.markdown}\nTop-Level Heading\n=================\n\nTop-Level (e.g. introductory) content.\n\n## Second-Level Heading\n\nSecond-Level Content\n\n### Third-Level Heading aka. List Title\n\nInner Content / End of example.\n~~~\n\n## Lists\n\nD5Man has numbered, unnumbered and definition lists. Legacy D5Man also\nproposed _pro and contra_-style lists which are as of now not retained in\nD5Man 2. Unnumberd list items are prefixed by an asterisk (`*`),\nnumbered lists are prefixed by the item's number followed by a dot\n(`1.`, `2.`, etc.) and description lists' contents are prefixed by a\n`:` at the beginning of the first line of the description list's content.\nNote that for description lists, the offset from the left has to be exactly\nfour characters wide (`:   ` / colon-space-space-space on the first line;\n`    ` / space-space-space-space on the second line onwards). Here are\nexamples for the respective list types.\n\n~~~\nDescription List\n:   This is the term being described.\n    This is the second line of the term being described.\nSecond Description List Item\n:   Another item to be described.\n\n 1. First Item of a numbered list:\n    This item has an additional line in source code.\n 2. Second\n 3. Third\n 4. Fourth\n\n * Item 1 of the unnumberd list has\n   two lines in source code.\n * Item 2 has a single line.\n    * Nested Item a\n    * Nested Item b\n * Item 3\n~~~\n\n## Tables\n\nTwo distinct notations exist for tables: Tables with headings and without\nheadings. All tables start from the first character in the line and leave two\nspaces between columns.\n\nFor tables with headings, there is a single dashed line below the individual\nheadings. Example:\n\n~~~{.markdown}\nCaption 1   Caption 2\n----------  ------------\nInner Cell  Inner Cell 2\nOther Cell  Last Cell\n~~~\n\nFor tables without headings, the same dashed lines are created and put above\nand below the respective table. Leaving out the captions, the table from before\nbecomes this:\n\n~~~{.markdown}\n----------  ------------\nInner Cell  Inner Cell 2\nOther Cell  Last Cell\n----------  ------------\n~~~\n\n## Code\n\nTop-level code can be declared by either indenting the code with at least a\nsingle tab character or by enclosing it in lines with three tilde characters\n(`~~~`).\n\nExample for tilde-based code section (the source code uses indentation to\nmake this appear as code in the output document):\n\n\t~~~\n\tcode content\n\t~~~\n\nThe tilde-based notation allows for a programming language to be declared by\nreplacing the first `~~~` with `~~~{.language}` where `language` is replaced by\na programming language name as known to `pandoc`. Examples include `c`,\n`markdown` and `java`.\n\nAlternatively, here is the indented variant (the source code uses tilde\nsymbols to make this appear as code in the output document):\n\n~~~\n\tcode content\n~~~\n\n## Paragraphs and Inline Formatting\n\nParagraphs are just regular text separated by two newlines. Throughout the\ndocument's text, it is possible to use _inline formatting_ to place emphasis,\nlinks etc. It is described in the following.\n\nCode\n:   By using backtick-quotation, inline code can be expressed\n    (`` ` ``code`` ` `` displays `code`). Escaping backticks inline requires\n    them to be sourrounded by more backticks and space. See\n    [stackoverflow.com/82718](https://meta.stackexchange.com/questions/82718/)\n    for details.\nEmphasis\n:   Like the legacy D5Man format, Markdown supports emphasis by surrounding the\n    text to be emphasized with underscores e.g. `_emphasized_` yields\n    _emphasized_.\nSuperset and subset\n:   Putting something in an index works by adding tilde symbols (`~`) around\n    the part to be lowered, e.g. `H~2~O` for H~2~O. Elevating parts of a\n    word is possible by surrounding it with hat symbols (`^`) e.g.\n    `10^2^` for 10^2^\nLinks\n:   Links to URLs or other pages are of format `[shortcut name](URL)`\n    e.g. `[Example Page](http://www.example.com/)` gives\n    [Example Page](http://www.example.com/).\n    If a link is given by URL only, it is given in angled-brackets like this:\n    `\u003chttp://www.example.com\u003e` gives \u003chttp://www.example.com\u003e.\n    To link to another D5Man page, its XHTML name needs to be given:\n    `[d5man/legacy(32)](d5man_legacy.xhtml)` gives\n    [d5man/legacy(32)](d5man_legacy.xhtml). By convention, the link to another\n    page is labelled by that page's name followed by its section in parentheses.\n    To link to pages in other sections, one needs to prefix `../SECTION` to\n    the link's target due to the D5Man directory structure being organized in\n    sections (even if it was originally a Program-Root structure, D5Man export\n    always generates files as if they were part of a Document-Root structure).\n    Note that unlike in legacy D5Man, links are expected to only work for the\n    XHTML export. Navigating the hypertext directly inside the editor is no\n    longer a supported use case.\nMath\n:   Inline Math is only supported for the PDF exports and can be expressed by\n    LaTeX' single-dollar notation, e.g. `$\\binom{1}{1}$` becomes\n    $\\binom{1}{1}$.\n\nFor qotation and symbols, legacy D5Man used some automatic replacement\nlogic. With the new version, this feature is no longer available, thus the use\nof UTF-8 symbols is suggested. On some Linux systems, quotation is easily\navailable by [ALTGR]-[V] (`„`), [ALTGR]-[B] (`“`) and [ALTGR]-[N] (`”`).\n\nForced spaces (aka. non-breaking spaces) can be inserted by using the respective\nunicode symbols. As described by\n[Thomas Peklak](https://coderwall.com/p/07mtla/insert-non-breaking-space-in-vim),\na single non-breaking space can be entered in VIM by pressing\n[CTRL]-[K] [SPACE] [SPACE]. Similarly, a forced half-space can be entered by\nusing the sequence [CTRL]-[V] [U] [2] [0] [2] [F].\n\nArrows are best inserted by using their UTF-8 symbols. The paragraph below\nshows a few examples, see \u003chttp://xahlee.info/comp/unicode_arrows.html\u003e for\na more comprehensive treatise.\n\nArrows: ← → ↑ ↓ ⇐ ⇒ ⇔\n\n## Images\n\nThe general syntax for images is `![CAPTION](FILE)`. By convention, `FILE` is\ngiven relative to the page's file and if it is associated directly to the page,\nthen it is placed in a directory with the page's name concatenated with a\ntrailing `_att`.\n\nFor instance, an attachment `test.png` for this very page would be loaded by\nspecifying `![Test](d5man2_att/test.png)`.\n\nNote that for `.svg` and `.pdf` files the extension of the image file name is\nnormally not given in order to allow an automatic detection by pandoc/LaTeX to\ntake place.\n\nCompiling and Installing D5Man 2\n================================\n\nD5Man 2 requires an Erlang OTP runtime and a suitable Perl interpreter as well\nas a selection of Perl modules. A declaration of all dependencies for an\ninstallation on a Debian stable system can be found in file `build.xml`.\n\nOnly the Erlang-based `d5mantui` requires external dependencies and needs to be\ncompiled, all other D5Man 2 components are scripts and run without compilation\nor further processing. As a build dependency, `mdvl-cecho` (or alternatively\n`cecho` as commented-out in `rebar.config`) is required. You can get\nthe build instructions for package `mdvl-cecho` here:\n\u003chttps://github.com/m7a/lp-cecho\u003e.\n\nPrior to attempting to run D5Man TUI, adjust its config file at\n`d5mantui4/config/sys.config` to refer to your local paths!\n\nTo compile the individual parts, it might be sufficient to call `make`\nin directory `d5mantui4`. After this has succeeded, all components are on disk.\nTo generate an installable Debian package, `ant` and the usual build tools for\nDebian packages are required. One can then build the package by invoking\n`ant package` in the repository's top-level directory.\n\n`d5mantui`\n==========\n\nThe D5Man Terminal User Interface (TUI) displays query results interactively in\nthe terminal while typing the query. Additionally, it contains functions to\nbuild a basic _Task Management_ system on top of D5Man.\n\n## Synopsis\n\n\td5mantui [query]\n\n## Configuration\n\nD5Man TUI can be configured through the `sys.config` file. The default\nconfiguration looks as follows:\n\n~~~{.erlang}\n[{d5mantui4, [\n\t{db_roots,       [\"/data/main/119_man_rr\", \"/data/main/120_mdvl_rr\"]},\n\t{command_editor, [\"/usr/bin/vim\"]},\n\t{newpage_root,   \"/data/main/119_man_rr\"}\n]},\n{kernel, [{error_logger, {file, \"/tmp/d5mantui4.log\"}}]}\n].\n~~~\n\n_Users must change this config prior to using D5man TUI_!\n\nThe meaning of the properties is as follows:\n\n`db_roots`\n:   Declares a list of directories to consult for D5Man pages. They can be\n    either in _Document-Root_ or _Program-Root_ organization. All the pages\n    found below the respective roots will be available for querying.\n`newpage_root`\n:   Specifies the directory in which new pages are created.\n`command_editor`\n:   Configures the Editor to use. It is recommended to use a terminal-based\n    editor which creates a new instance upon invocation of this command.\n`error_logger` file\n:   Configures a log to write errors to. In event of a D5Man TUI crash, please\n    delete this file, reproduce the issue and then send the contents of this\n    log file to the Ma_Sys.ma for analysis.\n\n## Usage\n\nThe screen could e.g. look as follows:\n\n~~~\n─────────────────────────────[ Ma_Sys.ma D5Man Terminal User Interface 4.0.0 ]──\n\n [                                                                            ]\n\n─────────────────────────────────────────────────────────────[ Query Results ]──\n\n   11 adler32         31 web/news                32 kbdcheck\n   11 bin2bmp         31 web/programs            32 lz4_ada\n   11 ma_capsblinker  32 big4                    32 ma_inventory\n   11 ma_open_cl_info 32 blake3_ada              32 masysmaci/build\n   11 ma_sitecopy     32 bruteforce3             32 masysmaci/main\n   11 maartifact      32 conf-cli                32 masysmaci/pkgsync\n   11 maerct          32 conf-gui                32 matrix_screensaver\n   11 mahalt          32 d5man/legacy            32 maxbupst\n   11 maloadmon       32 decode_girocode         32 megasync\n   11 syssheet        32 gamuhr                  32 pressed_keys\n   31 keysigning      32 i3bar                   32 progress\n   31 web/about       32 ial                     32 scanning\n   31 web/creative    32 image_viewer            32 screenindex\n   31 web/gpl         32 internet-enable-disable 32 shellscripts\n   31 web/knowledge   32 java-nostalgic-tools    32 ssd-optimization\n   31 web/main        32 jmbb                    32 tar_ada\n\n 1       2New    3       4All    5       6Docs   7Tasks  8-DLY   9-Sub   0Quit \n~~~\n\nThe first line is a prompt where the user can enter any query that will be used\nto find pages. The list below displays the search results and can be scrolled\nwith [UP] and [DOWN] arrows on the keyboard. Upon pressing [ENTER], the selected\npage is opened.\n\nAll commandline arguments to `d5manqtui` are treated as an input for the\nprompt. If the initial query (as given on the commandline) yields exactly one\nresult, the TUI will not be displayed and the respective page will be opened\ndirectly.\n\nFunction keys can be used as described in the following subsections.\n\n### [F2] -- New Page/Task\n\nOne can press [F2] to create a new page. To do this, the input at the prompt\nneeds to be in format `SECTION NAME` i.e. the new page's section followed by its\nname. D5Man TUI then clears the prompt.\n\nIn case of a regular page, it directly asks for a space-separated list of\ntags to assign to the page. Common tags are displayed in the _Query Results_\nwhile this mode is active. After pressing [ENTER], a predefined template is\ncopied to a new file and opened it in the configured editor.\n\nIf SECTION is set to 43 then metadata about the task is also queried from the\nprompt (press [ENTER] to continue) and afterwards a task rather than a page is\nbe created.\n\nThis function only supports Document-Root organization for creating new files.\n\n### [F4] -- All\n\nDisplays all results for the given query (default). Queries will return tasks\nas well as documents depending on which matches the input string.\n\n### [F6] -- Docs\n\nHides tasks from the result list.\n\n## [F7], [F8], [F9] -- D5Man TUI Task Management\n\nSince package version 1.0.54, D5Man provides some basic means to manage\n“tasks”, i.e. TODO lists or issues or the like. The idea behind this scheme is\nto leverage the Markdown format and D5Man's querying capabilities for management\nof tasks. Two distinct dimensions are considered to organize tasks:\n\n 1. The _task type_ specifies if this task is long, short, periodic or a\n    subtask. The order of display is: periodic, then long, then short.\n 2. The _task priority_ specifies how important a task is by assinging colors\n    (purple, red, yellow, green, black, white). The use of the colors is up to\n    the user. Instead of a color a task can also be in state _considered_ or\n    _delayed_: Considered means that it should be kept in mind but is not\n    assigned any priority (think: very low priority) and _delayed_ means that it\n    may be hidden because it is not expected to be worked on any time soon\n    (e.g. not in the current week).\n\nD5Man assings the file extension `.hot` to task files to distinguish them from\ndocuments and all tasks are placed and expected to be in section 43. D5Man\nautomatically finds tasks in Document-Root structures' section 43. Also, it\nscans the directories in Program-Root structures for `TODO.hot` files and adds\nthem to the tasks to consider.\n\nThe `x-masysma-name` field is expected to be set to a short identifier (e.g.\ncode and number or similar) whereas the `title` is expected to summarize the\nmatter of the task.\n\n### [F8] -- DLY\n\nBy default, tasks of priority _delayed_ are displayed. [F8] is a tristate toggle\nthat displays the action that is going to happen when pressing it:\n\n 1. `8-DLY` -- First press [F8] to hide (-) the delayed tasks from the view\n    and display only non-delayed tasks.\n 2. `8=DLY` -- Press [F8] again to display only (=) delayed tasks\n 3. `8+DLY` -- Press [F8] again to add non-delayed tasks (+) to the view again\n    (returns to the initial state).\n\n### [F9] -- Subtasks\n\nBy default, tasks of type _subtask_  are displayed. [F9] is a tristate toggle\nthat displays the action that is going to happen when pressing it:\n\n 1. `9-Sub` -- First press [F9] to hide (-) the subtasks from the view and\n    display only long/short/periodic ones.\n 2. `9=Sub` -- Press [F9] again to display only (=) subtasks.\n 3. `9+Sub` -- Press [F9] again to add non-subtasks (+) to the view again\n    (returns to the initial state).\n\n## Change History\n\nBefore the current revision (D5Man TUI 4), there was an implementation\nconsisting of a daemon (`d5manapi`) and a client (`d5mantui` perl script / v.3).\nThis had some advantages but was mostly much more complex than the current\nimplementation.\n\nThe new D5Man TUI 4 is close to a rewrite of the old functionality and thus\ndoesn't run fully stable yet. See `xdev/d5mantui3.pl` and `xdev/d5manapi` for\nthe old variants of these components.\n\n`d5manexportpdf`\n================\n\n## Name\n\n`d5manexportpdf` -- Script to export D5Man 2 Pandoc Markdown to PDF\n\n## Synopsis\n\n\td5manexportpdf INPUT.md\n\n## Description\n\nThis invokes `pandoc` on the provided filename `INPUT.md` and writes the export\nresult to `INPUT.md.pdf` (i.e. adds extension `.pdf` to the input file name).\nNote that due to hardcoded paths, this script only works if D5Man 2 is installed\n(e.g. as a Debian package).\n\nThe script deliberately contains almost no logic at all.\nThis allows it to be ported to other scripting languages like Windows Batch.\nAdditionally, a “regular” pandoc invocation can serve as a fallback if D5Man 2\nis not available.\n\n## Example\n\n\td5manexportpdf README.md\n\nThis should produce a nicely readable PDF for any instructions supplied as\npart of Ma_Sys.ma repositories.\n\n## Troubleshooting export issues\n\nIf the export fails during the invocation of `pdflatex`, it will most likely\ngenerate a meaningless error message. Here is a regex for finding unicode\nchars which might not be supported:\n\n\t/[^\\x00-\\x7F]\n\nSource: \u003chttps://stackoverflow.com/questions/16987362/how-to-get-vim-to-highlight-non-ascii-characters\u003e\n\n`d5manexporthtml`\n=================\n\n## Name\n\n`d5manexporthtml` -- Export D5Man 2 roots to multiple XHTML pages\n\n## Synopsis\n\n\td5manexporthtml -o DESTDIR -i ROOT[,ROOT...] [-s SECTION[,SECTION...]] [-m PDF2SVG] [-u URLPREFIX] [-- PANDOCOPTIONS...]\n\n## Description\n\nD5Man 2's HTML export exports a selection of sections from (optionally multiple)\nroot directories to a given output directory structure. The output structure\nresembles a Document-Root structure independently of whether the given `ROOT`\ndirectories are Document-Root or Program-Root organized.\n\nIn addition to the exported XHTML pages, a `sitemap.xml` and `.htaccess` files\nare generated to allow hosting the result structure online. PDF attachments are\nautomatically converted to SVG.\n\n## Options\n\n`-o DESTDIR`\n:   Configures the output directory to be `DESTDIR`\n`-i ROOT[,ROOT...]`\n:   Configures a comma-separated list of input directories.\n    (As a result, it is currently impossible to process directories which\n    contain comma as part of their name)\n`-s SECTION[,SECTION...]`\n:   Specifies a list of sections to export.\n    If this is not given, the default value of 11,31,32,33,34,37,38,39 will\n    be used.\n`-m PDF2SVG`\n:   Specifies the path to a `pdf2svg` executable. On Debian systems, package\n    `pdf2svg` can be installed and then the default `/usr/bin/pdf2svg` will\n    be sufficient. In other cases, it might be necessary to create an auxiliary\n    script that invokes Inkscape or another tool capable of converting PDF to\n    SVG. The `pdf2svg` is expected to take the input PDF file as its first\n    parameter and the output SVG file as its second parameter.\n`-u URLPREFIX`\n:   Defines a prefix to be used for sitemap generation. By default, it is set\n    to `\u0026masysma_url_prefix;` which will most likely _not work_. In case the\n    generated sitemap is of interest, this parameter needs to be given and\n    have an URL value. The Ma_Sys.ma Website uses\n    `-u https://masysma.lima-city.de`, for instance.\n`-- PANDOCOPTIONS...`\n:   After the double dashes, an arbitrary number of pandoc options can be\n    given which are passed directly to the `pandoc` command. Most users will\n    want to specify a `--template=...` here in order to obtain a nicely\n    formatted page up to their liking.\n\n## Ma_Sys.ma Variables\n\nUsing this script, the invocation of `pandoc` is passed the following additional\nvariables:\n\n`x-masysma-source`\n:   Set to the Markdown source code file name for the current page.\n`x-masysma-meta-revised`\n:   Set to the pages last modification in UTC (`YYYY-mm-dd HH:ii:ss`)\n`x-masysma-revised-human`\n:   Set to the pages last modification in local timezone (`YYYY/mm/dd HH:ii:ss`)\n\n## Examples\n\nAs an example, consider downloading some of the Ma_Sys.ma Repositories into\na common directory tree to obtain a structure as shown above in section\n_Example for a Program-Root Structure: Ma_Sys.ma Repositories_.\n\nThen, you could create an XHTML export of their contents as follows:\n\n\t$ mkdir /tmp/test\n\t$ d5manexporthtml -o /tmp/test -i /rr\n\nBelow the output directory `/tmp/test`, this will create a document-root\nstructure of output files like this:\n\n\t/tmp/test\n\t |\n\t +-- 11/\n\t |    |\n\t |    +-- maloadmon_att/\n\t |    |    |\n\t |    |    +-- ...\n\t |    |\n\t |    +-- ...\n\t |\n\t +-- 32/\n\t |    |\n\t |    +-- d5man2.md\n\t |    |\n\t |    +-- d5man2.xhtml\n\t |    |\n\t |    +-- ...\n\t |\n\t +-- ...\n\nOpening `d5man2.xhtml` one can see the XHTML representation of this very page,\nit might look as follows:\n\n![Excerpt from exporting this very page to XHTML (beginning of the page\nshown)](d5man2_att/exportpreview)\n\nWithout further options, exporting uses the template supplied with pandoc.\nIf you want to use this for your own purposes, it makes sense to derive an own\ntemplate for customization.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm7a%2Fbo-d5man2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm7a%2Fbo-d5man2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm7a%2Fbo-d5man2/lists"}