#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

#See Also

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

#Compiling

#Requirements

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

#Building

First clone the repository:

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

You can then build directly with Alire:

alr build

Or build and install manually:

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.

#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 sanitize input before rendering to HTML; one should not host untrusted/unknown documents as arbitrary HTML can be inserted.

#Copyright

Copyright (C) 2022-2023 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/.