{"id":17703388,"url":"https://github.com/randoragon/tmac-rnd","last_synced_at":"2026-03-19T01:49:59.552Z","repository":{"id":176069853,"uuid":"363745742","full_name":"randoragon/tmac-rnd","owner":"randoragon","description":"Randoragon's personal, general-purpose neatroff macro package","archived":false,"fork":false,"pushed_at":"2024-02-17T14:45:36.000Z","size":1625,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-06T08:32:29.816Z","etag":null,"topics":["markup","neatroff","text-processing","troff"],"latest_commit_sha":null,"homepage":"","language":"Roff","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/randoragon.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-05-02T20:41:26.000Z","updated_at":"2023-12-14T18:05:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"fa781d2d-0db3-40bc-973c-fb5c698b72a1","html_url":"https://github.com/randoragon/tmac-rnd","commit_stats":null,"previous_names":["randoragon/tmac-rnd"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randoragon%2Ftmac-rnd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randoragon%2Ftmac-rnd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randoragon%2Ftmac-rnd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/randoragon%2Ftmac-rnd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/randoragon","download_url":"https://codeload.github.com/randoragon/tmac-rnd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246413244,"owners_count":20773053,"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":["markup","neatroff","text-processing","troff"],"created_at":"2024-10-24T20:22:52.086Z","updated_at":"2026-01-08T14:36:34.061Z","avatar_url":"https://github.com/randoragon.png","language":"Roff","funding_links":[],"categories":[],"sub_categories":[],"readme":"# troff rnd macros\n\n**NOTE** This is an abandoned project. I ditched the troff/neatroff world,\nbecause there were just too many inconveniencing factors along the way, despite\nthe many positives.\n\n## Table of Contents\n\n1. [Description](https://github.com/Randoragon/tmac-rnd#description)\n2. [Features](https://github.com/Randoragon/tmac-rnd#features)\n    - [Differences with vanilla ms](https://github.com/Randoragon/tmac-rnd#differences-with-vanilla-ms)\n    - [New Headings](https://github.com/Randoragon/tmac-rnd#new-headings)\n    - [Lists](https://github.com/Randoragon/tmac-rnd#lists)\n    - [Media Macros](https://github.com/Randoragon/tmac-rnd#media-macros)\n    - [Table of Contents](https://github.com/Randoragon/tmac-rnd#table-of-contents-1)\n    - [Fonts](https://github.com/Randoragon/tmac-rnd#fonts)\n    - [Document Profiles](https://github.com/Randoragon/tmac-rnd#document-profiles)\n3. [Dependencies](https://github.com/Randoragon/tmac-rnd#dependencies)\n4. [Installation](https://github.com/Randoragon/tmac-rnd#installation)\n\n## Description\n\n`rnd` is a general-purpose macro package for troff that is based on\nthe old `ms` macros originally used by Bell Labs, with numerous\nextensions, additions and modifications.\n\nThe package aims to provide a flexible interface with many settings\nthat globally affect the document (inspired by the `mm` macros), but\nunlike `mm` it enables the user to override most defaults on an\nindividual basis.\n\nThe `rnd` macros serve as my primary tool for writing documents in\ntroff, and as such I reserve the right to change them in any way I\nwant to fit into my personal workflow. At no point should this\nmacro package be considered \"complete\", for the same reasons.\n\nThe macro package is written with Ali Gholami Rudi's Neatroff\nimplementation of roff in mind and it relies on many extended\ncontructs that Neatroff introduces. To learn more about Neatroff you\ncan start [here](https://litcave.rudi.ir/neatroff.pdf).\n\n## Features\n\n### Differences with vanilla ms\n\n1. Removed the following macros:\n    - TM, IM, MF, MR, LT, RP, TR\n    - UX, US\n    - MH, PY, AW\n    - S1, S2, S3, SY, CS\n2. Removed the following registers:\n    - IM, MN, CS, ST\n3. Modified the following macros:\n    - TL, AU, AI, BX (visual tweaks)\n    - SH, NH\n    - FP\n4. Added the following macros:\n    - **headings:** SHs, NHs, Hs, SHo, NHo, Ho, NHf, HE, H{\n    - **lists:** BL, AL, LI, LE\n    - **media:** PDF, URL\n    - **toc:** toc.init, toc.chapter, toc.section, TOC, CP\n    - **fonts:** FC\n    - **profile:** note, report, book, fmt\n5. Reserved the following number registers:\n    - **headings:** SH, SH1..SH5, NH1..NH5, HE, \\_s, \\_a, \\_f\n    - **lists:** LV, Lv, LT1..LT9, LD0..LD9, LO1..LO9, LS1..LS9, Ls1..Ls9, LC1..LC9, Li\n    - **toc:** TM\n    - **profile:** DT\n    - **misc:** \\_d, \\_o, \\_maxw, \\_w, \\_h, \\_i, \\_u, NT\n6. Reserved the following string names:\n    - **headings:** SH1..SH5, NH1..NH5, \\_a\n    - **media:** def\\_col\\_url, col\\_url, \\_col\n    - **toc:** \\_s, HP\n7. Reserved the following environment names:\n    - \\_toc\n8. Changed font names recognized by the FP macro\n    - for a full list of names refer to `tmac.main`, the list might change with time\n\n### New Headings\n\nThe new heading syntax comes in 2 forms which look as follows:\n\n    .SH [options] \u003clevel\u003e text...\n    .NH [options] \u003clevel\u003e text...\n\n**or**\n\n    .SH [options] \u003clevel\u003e\n    text...\n    .HE \u003ctoc name\u003e\n    .NH [options] \u003clevel\u003e\n    text...\n    .HE \u003ctoc name\u003e\n\nThe second form exists in case you want to have a URL in your\nheading, or any other advanced formatting that can't be done\nin-line. There is one caveat: the second form does not support\nthe *u* option (options are explained below).\n\n*toc name* is the name displayed in a table of contents. Only\nheadings of the second form require it to be specified separately\nin the `HE` macro, because for headings of the first form, the\ntext is taken directly from the `NH` or `SH` macro.\n\n#### Options\n\n*options* is a single word composed of lowercase letters of the\nfollowing form:\n\n    [l|c|r][b][i][u]\n\n- *l*, *c*, *r* denote adjustment to the left, center or right\n- *b* denotes **emboldening**\n- *i* denotes *italics*\n- *u* denotes \u003cu\u003eunderline\u003c/u\u003e\n\nOptions can be skipped, in which case the default settings will\nbe used. The default option strings for each level of section\nand numbered headings are stored in `SH1..SH5` and `NH1..NH5`\nstrings. You can change these defaults easily with `SHo`, `NHo`\nand `Ho` macros:\n\n    .SHo cb b bi i i\n    .NHo cb b bi i i\n    .Ho  cb b bi i i\n\nThe above macros change level one headings to be centered and\nbold, level 2 headings to be bold, level 3 to be bold and italic,\nand level 4 and 5 headings to be italic. You can override these\ndefaults in each individual heading invocation, though.\n\n#### Point size\n\nHeadings have configurable point sizes per level. The point size\nof each level is stored in `SH1..SH5` for section headings and\nin `NH1..NH5` for numbered headings. You can easily set these\nregisters to desired values using the new `SHs`, `NHs` and `Hs`\nmacros:\n\n    .SHs 16 15 14 13 12\n    .NHs 16 15 14 13 12\n    .Hs  16 15 14 13 12\n\n`Hs` sets the same point sizes for both `SH` and `NH`, it's just\na shorthand for calling `SHs` and `NHs` with the same arguments.\nYou can omit up to 4 arguments to initialize the remaining values\nto the last one. The following 2 lines do the same thing:\n\n    .NHs 14 13 12 12 12\n    .NHs 14 13 12\n\nThis functionality is inspired by the `mm` macros.\n\nFor numbered headings, you can also set number formats for each\nlevel separately with the `NHf` macro, e.g.:\n\n    .NHf A a i 1 1\n\nEmpty or missing arguments will be silently ignored. By default,\nall formats are set to arabic (1).\n\n#### Named references\n\nFor all headings, a Neatroff **named reference** is automatically\ncreated, for the purpose of generating tables of contents.\n\nFor numbered headings, the reference name matches the current\nchapter prefix (*toc prefix*) followed by the heading \"prefix\".\nFor example, if you start a new chapter with prefix \"1\", a\nnumbered heading \"1. Example\" will have the reference\n`#h11.`, while a heading with prefix \"A.3.ii. Nested Example\"\nwithin a chapter prefixed \"B\" will have the reference `#hBA.3.ii.`\n(**note the trailing periods!**). If a heading appears outside\nof a chapter, the *toc prefix* part is an empty string (i.e.\nit should be skipped).\n\nSection headings don't have prefixes, so they are enumerated\nnormally, i.e. `#h1`, `#h2` and so on (**no trailing period!**).\nThe rules for chapter prefixes are the same as with numbered\nheadings.\n\n### Lists\n\nLists are much inspired by the `mm` macros. You can start a\nnew list with the following macros, for bulleted and enumerated\nlists respectively:\n\n    .BL [symbol] [indent] [offset] [spacing]\n    .AL [format] [indent] [offset] [spacing]\n\n- *symbol* is `\\(bu` by default, but any non-empty string is valid\n- *format* is transparently passed to `.af` for different number\nformatting\n- *indent* is additional indentation, set to `4n` by default\n- *offset* is indentation added to all prior indentation to separate\nthe symbol/number from the item body. Set to `4n` by default\n- *spacing* is vertical distance added inbetween all list items.\nBy default it's equal to `0`, which results in simple line breaks.\n\nAfter initializing a list, each list item can be added with\n\n    .LI [symbol] [indent] [offset]\n\nFollowed by the body of the item.\nThe arguments for `LI` are identical to those of `BL` (except\n*spacing*), and they serve as an optional override that affects\nonly a particular item.\n\nAt the end, the list must be terminated with\n\n    .LE\n\nLists can be nested up to 9 levels.\n\n### Media Macros\n\nPDF images can be embedded with\n\n    .PDF \u003cadjust\u003e \u003cpath\u003e \u003cwidth\u003e \u003cheight\u003e [scale]\n\n- *adjust* - `l`, `c`, `r` or a number denoting indentation\n- *path* - path to the image file\n- *width* - width of the image\n- *height* - height of the image\n- *scale* - scaling factor in 1/1000, 1000 is the maximum available width\n\nThe scaling mechanism works in the following way:  \nIf *scale* is not supplied, the image will aim to be originally-sized, but\ncapped at maximum on-page width (the maximum width is computed as\n`\\n(.l-\\n(.i`). If *scale* is supplied, 1000 denotes the maximum width.\n\nHyperlinks can be embedded with\n\n    .URL \u003cdestination\u003e [text] [text2]\n\nWhere *destination* is the URI, *text* is displayed as a clickable, followed\nby non-clickable *text2* (similar to how additional parameters are handled\nin `.B` and `.I` macros).\nIf *text* is an empty string (or omitted), *destination* is used instead.  \nBy default, all URLs have a custom color stored in the `def_col_url`\nstring. If you want a different color, you should temporarily define the\n`col_url` string. `def_col_url` should be treated as a read-only resource.\n\n### Table of Contents\n\nAll headings can be automatically included into the ToC.\nYou can control which headings get added by changing the value\nof the `TM` register which denotes the largest heading number\nto be included, and is equal to 2 by default (which means\nheadings of level 1 and 2 will be included).\n\nOther than headings, you can define new chapters with `CP`:\n\n    .CP \u003con-page name\u003e \u003ctoc prefix\u003e [toc name]\n\nEach chapter will break to a new page, disable the top header\nof that page and replace it with a nice caption.\n\n- *on-page name* is the text that will be printed on the page\n- *toc prefix* is typically a short string that will appear\nin ToC to the left of the chapter name, typically it's the\nchapter number, or something like \"A\", \"B\", \"C\" for appendices\n- *toc name* is an optional alternate title for the ToC\n\nSometimes you might want to display full text \"Chapter 1 - Title\"\non the page, but in the ToC you want a format like \"1. Title\".\nThe *toc name* argument lets you override *on-page name* for\nthose purposes. If you don't specify *toc name*, *on-page name*\nwill be used by default.\n\nChapters automatically create named references of the form\n`#c1`, `#c2`, `#c3` and so on. These references are used when\ngenerating the table of contents.\n\nThe ToC can be printed anywhere within the document, any number\nof times, without the need to wait for headings/chapters to accumulate.\nTo print the ToC, you must supply the **exact line**:\n\n    .TOC\n\nThis convenient functionality is made possible by utilizing the\n`stderr` stream as intermediary output instead of relying on diversions.\nHowever, this comes at a cost:\n\n- An external script must be used to capture and parse `stderr`, then\nmerge it into the original document and recompile.\n- Please take a look at the `ntmake` script within this repository\nto see how you can build the document with ToC.\n- **If you don't plan on using .TOC, you can compile as normal,\nwithout any complications!**\n\n### Fonts\n\nThe `FP` macro has been modified with new font names. It is up to the user to\nensure that appropriate font description files have been provided to neatroff\n(inside the devutf directory).\n\nThere is a slight change in convention - `FP` changes the \"main\" fonts, while\na new macro - `FC` changes constant width fonts. These two have been separated\nto make adding features like code blocks easier.\n\nThe default layout of font positions is as follows:\n\npos  | font\n:--- | :---\n1    | R\n2    | I\n3    | B\n4    | BI\n5    | CR\n6    | CI\n7    | CB\n8    | CX\n\nThe first 4 positions are controlled by `FP`, the last 4 by `FC`.\n\n### Document Profiles\n\nIn order to provide minimal support for different document\ntypes, there are a couple of macros that control the global\nconfiguration. All of these should be invoked as one of the\nfirst macros (if not first).\n\n    .note\n    .report\n    .book\n\n1. `note` is the default profile which aims to provide\nsane defaults for writing quick notes, akin to markdown.\n2. `report` is for writing technical reports.\n3. `book` is for writing simple books.\n\n#### Brief profiles comparison\n\nFeature | `note` | `report` | `book`\n---: | :---: | :---: | :---:\npage numbering | | ✗ | ✗\nseparate cover page | | ✗ | ✗\n`.TOC` causes page break | | ✗ | ✗\n`.CP` causes page break | | ✗ | ✗\n\nThe `book` and `report` produce slightly different output\nvisually in some aspects. For example, a new chapter in a\nreport starts from the top of the page, whereas in a book\nthere is additional spacing from the top of the page and\nthe chapter name point size is slightly bigger, etc.\n\n## Dependencies\n\n`rnd` relies on the following packages provided by Neatroff:\n\n- `mpost`: URLs\n- `msdisp`: display macros\n- `mskeep`: keep blocks (needed by display macros)\n\nThese macros are **not** sourced by `rnd`, and you have to\nmanually specify `-mpost`, `-msdisp` and `-mskeep` when compiling.\nNeatroff automatically ships with these though, so there\nshouldn't be a problem.\n\n## Installation\n\nTo keep maintenance and writing new extensions easy and sane, the\npackage is split across multiple files, as seen in the `src`\ndirectory. However, multiple macro files are too inconvenient to\ncarry around, so the Makefile within this repository can stitch\nall files scattered in `src` into a **single, complete form**.\n\nTo build the file containing all macros, run:\n\n    make\n\nThis will create a new `tmac.rnd` file in the base directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandoragon%2Ftmac-rnd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frandoragon%2Ftmac-rnd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frandoragon%2Ftmac-rnd/lists"}