updated metadata

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

View file

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

View file

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