doomemacs / doomemacs/core

`set-formatter!` macro's doc seems wrong

Open
#7,762 0 comments 0 reactions 0 assignees View on GitHub
is:bug needs-triage
Dominant language
Emacs Lisp
Stars
22.7k
Forks
3.1k
Avg merge
10h 46m
Merged PRs (30d)
4

Description

### I confirm that...

- [X] I have searched the [issue tracker](https://github.com/doomemacs/doomemacs/issues), [documentation](https://docs.doomemacs.org), [FAQ](https://docs.doomemacs.org/-/faq), [Discourse](https://discourse.doomemacs.org), and [Google](https://google.com), in case this issue has already been reported/resolved.

- [X] I have read "[How to Debug Issues](https://doomemacs.org/d/how2debug)", and will use it to provide as much information about this issue as possible.

- [X] The issue can be reproduced on the **latest** available commit of Doom.

- [X] The issue can be reproduced on a stable release of Emacs, such as 27, 28, or 29. *(Unstable versions end in .50, .60, or .9x)*

### Expected behavior

When I study `set-formatter!` macro's docs in `spc-h f set-format`, I read:

> FORMATTER can be a symbol referring to another formatter, a function, string or
nested list.
> If a function, it should be a formatter function that
> `apheleia--run-formatter-function' will accept.
> If a string, it is assumed to be a shell command that the buffer's text will
> be piped to (through stdin).
> If a list, it should represent a shell command as a list of arguments. Each
> element is either a string or list (STRING ARG) where STRING is a format
> string and ARG is both a predicate and argument for STRING. If ARG is nil,
> STRING will be omitted from the vector.

so since I want my buffer to be piped to a formatter, I try:

```elisp
(after! dockerfile-mode
(set-formatter! 'dockfmt "/home/oggei/.cargo/bin/dprint fmt --stdin Dockerfile"
:modes '(dockerfile-mode)))
```

### Current behavior

response found in `*Messages*` is discouraging:

```
apheleia--run-formatters: Formatter must be a shell command or a Lisp function: dprint fmt --stdin Dockerfile
```

### Steps to reproduce

see `expected behaviour`

Solution is to use this config, which works flawlessly:

```elisp
(after! dockerfile-mode
(set-formatter! 'dockfmt '("/home/oggei/.cargo/bin/dprint" "fmt" "--stdin" "Dockerfile")
:modes '(dockerfile-mode)))
```

so everything works! :rocket: But docs seems wrong :sob: , which is really discouraging for a newcomer like me.

I'm not sure if there is a correct documentation somewhere else, or this piece should simply be rewritten, if you give me some advice I could try to send a PR, what do you think?

Thank you, regards!

### System Information

https://pastebin.com/jW2u4Ysv

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.