ficd/mailfmt
1
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions

updated metadata

Browse source
This commit is contained in:
Daniel Fichtinger 2025-07-13 02:51:22 -04:00
parent f75f0bfe83
commit 9c6ae12284
2 changed files with 36 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

78
README.md
View file

@ -1,12 +1,12 @@
<h1>Mail Format</h1>
`mailfmt` is a simple plain text email formatter. It's designed to ensure
consistent paragraph spacing while preserving markdown syntax, email headers,
sign-offs, and signature blocks.
consistent paragraph spacing while preserving markdown syntax, email
headers, sign-offs, and signature blocks.
By default, the command accepts its input on `stdin` and prints to `stdout`.
This makes it well suited for use as a formatter with a text editor like Kakoune
or Helix.
By default, the command accepts its input on `stdin` and prints to
`stdout`. This makes it well suited for use as a formatter with a text
editor like Kakoune or Helix.
<!--toc:start-->
@ -16,7 +16,6 @@ or Helix.
- [Output Example](#output-example)
- [Markdown Safety](#markdown-safety)
- [Aerc Integration](#aerc-integration)
- [Contributing](#contributing)
<!--toc:end-->
@ -33,15 +32,17 @@ or Helix.
- Markdown-style code blocks.
- Usenet-style signature block at EOF.
- Sign-offs.
- If specified, output can be made safe for passing to a Markdown renderer.
- Use case: piping the output to `pandoc` to write a `text/html` message. See
[Markdown Safety](#markdown-safety).
- If specified, output can be made safe for passing to a Markdown
renderer.
- Use case: piping the output to `pandoc` to write a `text/html`
message. See [Markdown Safety](#markdown-safety).
## Installation
`mailfmt` is intended for use as a standaole tool. The package is available on
PyPI as `mailfmt`. I recommend using [uv](https://github.com/astral-sh/uv) or
`pipx` to install it so the `mailfmt` command is available on your path:
`mailfmt` is intended for use as a standaole tool. The package is
available on PyPI as `mailfmt`. I recommend using
[uv](https://github.com/astral-sh/uv) or `pipx` to install it so the
`mailfmt` command is available on your path:
```sh
uv tool install mailfmt
@ -53,12 +54,6 @@ Verify that the installation was successful:
mailfmt --help
```
The tool doesn't currently have any dependencies. Therefore, you can just
download and execute the
[mailfmt](https://git.sr.ht/~ficd/mailfmt/tree/main/item/mailfmt.py) script
directly. However, dependencies may be introduced later, so I recommend
installing with a Python package manager.
## Usage
```
@ -85,8 +80,7 @@ options:
-o, --output OUTPUT Output file. (default: STDOUT)
Author : Daniel Fichtinger
License: ISC
Contact: daniel@ficd.ca
Contact: daniel@ficd.sh
```
## Output Example
@ -109,8 +103,7 @@ Daniel
--
Daniel
sr.ht/~ficd
daniel@ficd.ca
daniel@ficd.sh
```
After:
@ -132,23 +125,24 @@ Daniel
--
Daniel
sr.ht/~ficd
daniel@ficd.ca
daniel@ficd.sh
```
## Markdown Safety
In some cases, you may want to generate an HTML email. Ideally, you'd want the
HTML to be generated directly from the plain text message, and for _both_
versions to be legible and have the same semantics.
In some cases, you may want to generate an HTML email. Ideally, you'd want
the HTML to be generated directly from the plain text message, and for
_both_ versions to be legible and have the same semantics.
Although `mailfmt` was written with Markdown markup in mind, its intended output
is still the `text/plain` format. If you pass its output directly to a Markdown
renderer, line breaks in sign-offs and the signature block won't be preserved.
Although `mailfmt` was written with Markdown markup in mind, its intended
output is still the `text/plain` format. If you pass its output directly
to a Markdown renderer, line breaks in sign-offs and the signature block
won't be preserved.
If you invoke `mailfmt --markdown-safe`, then `\` characters will be appended to
mark line breaks that would otherwise be squashed, making the output suitable
for conversion into HTML. Here's an example of one such pipeline:
If you invoke `mailfmt --markdown-safe`, then `\` characters will be
appended to mark line breaks that would otherwise be squashed, making the
output suitable for conversion into HTML. Here's an example of one such
pipeline:
```bash
cat message.txt | mailfmt --markdown-safe | pandoc -f markdown -t html
@ -174,24 +168,20 @@ Daniel \
-- \
Daniel \
sr.ht/~ficd \
daniel@ficd.ca \
daniel@ficd.sh \
```
## Aerc Integration
For integration with `aerc`, consider adding the following to your `aerc.conf`:
For integration with `aerc`, consider adding the following to your
`aerc.conf`:
```ini
[multipart-converters]
text/html=mailfmt --markdown-safe | pandoc -f markdown -t html --standalone
```
When you're done writing your email, you can call the `:multipart text/html`
command to generate a `multipart/alternative` message which includes _both_ your
original `text/plain` _and_ the newly generated `text/html` content.
## Contributing
Please send patches, requests, and concerns to my
[public inbox](https://lists.sr.ht/~ficd/public-inbox).
When you're done writing your email, you can call the
`:multipart text/html` command to generate a `multipart/alternative`
message which includes _both_ your original `text/plain` _and_ the newly
generated `text/html` content.

4
pyproject.toml
View file

@ -1,6 +1,6 @@
[project]
name = "mailfmt"
version = "1.0.2"
version = "1.0.3"
description = "Heuristic plain text email formatter."
readme = "README.md"
authors = [
@ -13,7 +13,7 @@ license-files = ["LICENSE"]
keywords = ["email", "formatter", "cli"]
[project.urls]
Repository = "https://git.sr.ht/~ficd/mailfmt"
Repository = "https://git.ficd.sh/ficd/mailfmt"
[project.scripts]
mailfmt = "mailfmt:main"