{"id":27760900,"url":"https://github.com/nmeum/skribilo-mdoc","last_synced_at":"2026-01-24T03:31:48.457Z","repository":{"id":287709883,"uuid":"965563124","full_name":"nmeum/skribilo-mdoc","owner":"nmeum","description":"A man page generator with support for the mdoc format build using Skribilo","archived":false,"fork":false,"pushed_at":"2025-04-13T12:49:40.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-29T12:09:54.170Z","etag":null,"topics":["documentation","man-pages","mdoc","skribilo"],"latest_commit_sha":null,"homepage":"","language":"Scheme","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nmeum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2025-04-13T12:48:38.000Z","updated_at":"2025-04-13T12:49:49.000Z","dependencies_parsed_at":"2025-04-13T13:47:01.671Z","dependency_job_id":null,"html_url":"https://github.com/nmeum/skribilo-mdoc","commit_stats":null,"previous_names":["nmeum/skribilo-mdoc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nmeum/skribilo-mdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fskribilo-mdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fskribilo-mdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fskribilo-mdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fskribilo-mdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmeum","download_url":"https://codeload.github.com/nmeum/skribilo-mdoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmeum%2Fskribilo-mdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28710111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T23:51:44.727Z","status":"online","status_checked_at":"2026-01-24T02:00:06.909Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["documentation","man-pages","mdoc","skribilo"],"created_at":"2025-04-29T12:09:52.863Z","updated_at":"2026-01-24T03:31:48.443Z","avatar_url":"https://github.com/nmeum.png","language":"Scheme","funding_links":[],"categories":[],"sub_categories":[],"readme":"## README\n\nA man page generator with support for the [mdoc] format build using [Skribilo].\n\n### Idea\n\nApparently, writing man pages (i.e., [roff]) by hand is not particularly popular among programmers these days.\nTherefore, the majority of people use an intermediate language through a man page generator, such as [scdoc] or [asciidoc].\nExisting tooling in this regard outputs man pages in the [`man(7)`][man] format instead of the [`mdoc(7)`][mdoc] format.\nIn my view, the latter is vastly superior because it supports various semantic macros which can be used by viewers to, for example, identify command-line flags.\nUnfortunately, due to the lack of support for [mdoc] in existing man page generators, the format is not as widely adopted as it should be.\nThis projects attempts to address that by implementing a man page generator with [mdoc] support.\n\nAdding [mdoc] support to existing intermediate languages (e.g., the markdown-inspired [scdoc]) is challenging, as—due to lack of extensibility features in Markdown—we cannot easily add custom markup for mdoc's semantic macros.\nInstead of yet again implementing our own intermediate language, this project attempts to build on an existing *extensible markup language*.\nSpecifically, this project builds upon [Skribilo] which is itself inspired by [Skribe] and builds upon the [Scheme] programming language.\n\n### Contributions\n\nTechnically, in Skribilo terms, this projects makes two contributions:\n\n1. A markup *package* which extends the Skribe language with custom *Skribe expressions* to allow using mdoc's semantics markups in Skribe documents.\n2. An [Skribilo engine] which allows rendering Skribilo documents in the [mdoc] format. Such documents can use Skribilo's [standard markup][Skribilo markup] (e.g., for bold text) as well as the custom markup provided by the aforementioned mdoc-specfic markup package.\n\n### Status\n\nThis is a proof of concept which is not directly usable in the current state.\nIt illustrates some of the benefits of building man page tooling on top of a extensible markup language.\nHowever, there are some caveat in this regard which are specific to Skribilo and the Skribe language:\n\n* Skribilo focuses largely on document generation (e.g. with HTML or LaTex) and a lot of its [standard markup][Skribilo markup] cannot be easily translated to the [mdoc] format (e.g. [figures][Skribilo figures], [images][Skribilo images], or [colors][Skribilo colors]). Therefore, only a subset of the standard markup can be supported in the [mdoc] engine, which feels unsatisfactory.\n* While Skribilo supports different input formats, apart from the Scheme-based Skribe language (e.g., [Outline syntax][Skribilo outline] or [Gemtext][Skribilo gemtext]), extensible markup with custom expressions is only supported in the Skribe language. This is somewhat unfortunate as, in my view, Skribe documents are quite verbose and not as enjoyable to write as documents in Outline syntax.\n\nA prerequisite for continued success of this project would therefore probably be making some contributions to Skribilo.\nFor example, implementing [pollen]-like input syntax that is easy to write (like Outline syntax) but still supports extensibility through custom expressions.\n\n### Usage Example\n\nRun the following commands from the repository root:\n\n\t$ export GUILE_LOAD_PATH=\"$(pwd)/src\"\n\t$ skribilo -t mdoc example.scm\n\n### License\n\nThis program is free software: you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation, either version 3 of the License, or (at your\noption) any later version.\n\nThis program is distributed in the hope that it will be useful, but\nWITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General\nPublic License for more details.\n\nYou should have received a copy of the GNU General Public License along\nwith this program. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n[mdoc]: https://man.openbsd.org/mdoc.7\n[roff]: https://man.openbsd.org/roff.7\n[man]: https://man.openbsd.org/man.7\n[scdoc]: https://git.sr.ht/~sircmpwn/scdoc\n[asciidoc]: https://asciidoc.org/\n[Skribilo]: https://www.nongnu.org/skribilo\n[Skribilo engine]: https://www.nongnu.org/skribilo/doc/user-14.html#engines\n[Skribilo markup]: https://www.nongnu.org/skribilo/doc/user-4.html#std-markups\n[Skribilo figures]: https://www.nongnu.org/skribilo/doc/user-30.html#section3424\n[Skribilo images]: https://www.nongnu.org/skribilo/doc/user-31.html#section3687\n[Skribilo colors]: https://www.nongnu.org/skribilo/doc/user-29.html#subsection3230\n[Skribilo outline]: https://www.nongnu.org/skribilo/doc/user-3.html#outline-syntax\n[Skribilo gemtext]: https://www.nongnu.org/skribilo/doc/user-3.html#gemtext-syntax\n[Skribe]: https://doi.org/10.1017/S0956796805005575\n[Scheme]: https://www.scheme.org/\n[pollen]: https://docs.racket-lang.org/pollen/quick-tour.html#%28part._.Pollen_markup%29\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmeum%2Fskribilo-mdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmeum%2Fskribilo-mdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmeum%2Fskribilo-mdoc/lists"}