#Gemroff — Line-based markup language taking inspiration from gemtext and roff

Gemroff is a line-based markup language taking heavy inspiration from Gemtext and Roff. Gemroff is designed as a format that is rarely rendered directly, rather you write Gemroff markup and convert it to any of a wide variety of output formats.

#Features

• Render output to a variety of formats:
  • Gemtext
  • HTML
  • Plain text
  • TTY (i.e. VT100/ANSI escape codes, for terminal rendering)
• Highly compatible with Gemtext; the vast majority of extant Gemtext documents are valid Gemroff documents, with no modification required.
• Wide variety of semantic and physical markup.
• “Gracefully degrading”—some inline elements such as emphasis are stripped out or modified when rendering to formats such as gemtext that don't support it. Block elements are always preserved.
• Highly customizable output, from hard wrapping to inline markup enclosures
• Very thorough and complete documentation.

#Documentation

• gemroff(1) (markdown format)
• gemroff(5) (markdown format)
• gemroff.conf(5) (markdown format)
• gemtext(5) (markdown format)
• gemroff.conf.sample

(Markdown versions of man pages generated by mandoc(1), expect some weird conversion issues. The man pages work great so I'd recommend directly using those.)

#Library API Docs

• Gemroff
  • Gemroff.Configuring
  • Gemroff.Parsing
  • Gemroff.Rendering
  • Gemroff.Utils

#See Also

• Gemroff syntax highlighting for Vim
• Verify if a Gemtext document is a valid Gemroff document

#Compiling

NEW: you can download prebuilt and tested x86-64 Linux binary by clicking the latest builds on the CI page: https://builds.sr.ht/~nytpu/gemroff. Artifacts are only saved for 90 days so there unfortunately may be no artifacts available if there has been a gap between pushing new commits or tags. The binaries are mostly statically linked but depend on glibc.

First clone the repository:

git clone https://git.sr.ht/~nytpu/gemroff && cd gemroff

If you already have an Ada toolchain installed, or are on a *nix distribution with a functional Ada toolchain available (to my knowledge, currently Arch Linux & derivatives, Debian, and Fedora) then it is highly recommended that you build manually.

If you are on Windows, Mac OS, *BSD, or any Linux distribution without good Ada packages, then building with Alire may be much more convenient as it manages toolchains and libraries for you independent of the package manager (if your system has a package manager at all).

#Compiling Manually

#Requirements

• GPRbuild
• An Ada 2012 compiler and standard library (typically GNAT, sometimes known as GCC-Ada)
• POSIX-compatible make(1) (optional). Most makes (including GNU Make and BSD Make) support the POSIX standard.
• Ahven (For testing, optional)

#Building

git submodule update --init --recursive
make
make test  # optional
sudo make install

You may also use plain gprbuild and gprinstall commands rather than the convenience makefile.

#Compiling with Alire

#Requirements

• Alire (Automatically handles downloading and running an Ada toolchain for you)
• Ahven (Not provided in Alire, for testing, optional)
• POSIX-compatible make(1) (optional).

#Building

alr build
alr action test  # optional
sudo make alire-install

Alternately, you may manually copy bin/gemroff to your desired location within your PATH

#Contributing

The upstream URL of this project is https://git.sr.ht/~nytpu/gemroff. Send suggestions, bugs, patches, and other contributions to ~nytpu/public-inbox@lists.sr.ht or alex@nytpu.com. For help sending a patch through email, see https://git-send-email.io. You can browse the list archives at https://lists.sr.ht/~nytpu/public-inbox.

If you aren't comfortable sending a patch through email, get in touch with a link to your repo and I'll pull the changes down myself!

#Known Issues

• Gemroff does not percent-encode sensitive characters (such as ") in links when embedding them in HTML and other formats, links should be properly percent-encoded in the source text
• Output files may have an extra empty line appended (likely issue with Ada standard library).
• If multiple output files are provided (e.g. gemroff -o a.txt -o b.txt -o c.txt), then a later flag overrides the prior flag as expected, but all of the output files are opened and promptly closed again, creating empty files if they don't exist and truncating existing files.

#Copyright

Copyright (C) 2021-2024 nytpu <alex [at] nytpu.com>.

Licensed under the terms of the GNU Affero General Public License, version 3. You can view a copy of the GNU AGPL in LICENSE or at https://www.gnu.org/licenses/agpl-3.0.html.

The gemtext(5) man page, gemroff.vim, is_gemtext_gemroff.awk, and gemroff.conf.sample are dedicated to the public domain under the terms of the CC0 1.0 Universal Public Domain Dedication. You can view a copy of the CC0 1.0 in COPYING.CC0 or at https://creativecommons.org/publicdomain/zero/1.0/.