1## README23A man page generator with support for the [mdoc] format build using [Skribilo].45### Idea67Apparently, writing man pages (i.e., [roff]) by hand is not particularly popular among programmers these days.8Therefore, the majority of people use an intermediate language through a man page generator, such as [scdoc] or [asciidoc].9Existing tooling in this regard outputs man pages in the [`man(7)`][man] format instead of the [`mdoc(7)`][mdoc] format.10In 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.11Unfortunately, due to the lack of support for [mdoc] in existing man page generators, the format is not as widely adopted as it should be.12This projects attempts to address that by implementing a man page generator with [mdoc] support.1314Adding [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.15Instead of yet again implementing our own intermediate language, this project attempts to build on an existing *extensible markup language*.16Specifically, this project builds upon [Skribilo] which is itself inspired by [Skribe] and builds upon the [Scheme] programming language.1718### Contributions1920Technically, in Skribilo terms, this projects makes two contributions:21221. A markup *package* which extends the Skribe language with custom *Skribe expressions* to allow using mdoc's semantics markups in Skribe documents.232. 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.2425### Status2627This is a proof of concept which is not directly usable in the current state.28It illustrates some of the benefits of building man page tooling on top of a extensible markup language.29However, there are some caveat in this regard which are specific to Skribilo and the Skribe language:3031* 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.32* 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.3334A prerequisite for continued success of this project would therefore probably be making some contributions to Skribilo.35For example, implementing [pollen]-like input syntax that is easy to write (like Outline syntax) but still supports extensibility through custom expressions.3637### Usage Example3839Run the following commands from the repository root:4041 $ export GUILE_LOAD_PATH="$(pwd)/src"42 $ skribilo -t mdoc example.scm4344### License4546This program is free software: you can redistribute it and/or modify it47under the terms of the GNU General Public License as published by the48Free Software Foundation, either version 3 of the License, or (at your49option) any later version.5051This program is distributed in the hope that it will be useful, but52WITHOUT ANY WARRANTY; without even the implied warranty of53MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General54Public License for more details.5556You should have received a copy of the GNU General Public License along57with this program. If not, see <https://www.gnu.org/licenses/>.5859[mdoc]: https://man.openbsd.org/mdoc.760[roff]: https://man.openbsd.org/roff.761[man]: https://man.openbsd.org/man.762[scdoc]: https://git.sr.ht/~sircmpwn/scdoc63[asciidoc]: https://asciidoc.org/64[Skribilo]: https://www.nongnu.org/skribilo65[Skribilo engine]: https://www.nongnu.org/skribilo/doc/user-14.html#engines66[Skribilo markup]: https://www.nongnu.org/skribilo/doc/user-4.html#std-markups67[Skribilo figures]: https://www.nongnu.org/skribilo/doc/user-30.html#section342468[Skribilo images]: https://www.nongnu.org/skribilo/doc/user-31.html#section368769[Skribilo colors]: https://www.nongnu.org/skribilo/doc/user-29.html#subsection323070[Skribilo outline]: https://www.nongnu.org/skribilo/doc/user-3.html#outline-syntax71[Skribilo gemtext]: https://www.nongnu.org/skribilo/doc/user-3.html#gemtext-syntax72[Skribe]: https://doi.org/10.1017/S095679680500557573[Scheme]: https://www.scheme.org/74[pollen]: https://docs.racket-lang.org/pollen/quick-tour.html#%28part._.Pollen_markup%29