branch: elpa/gptel
commit 3fdcb2256a0365f4608be0c1bf8406619c53938e
Author: Karthik Chikmagalur <karthikchikmaga...@gmail.com>
Commit: Karthik Chikmagalur <karthikchikmaga...@gmail.com>
README: Restructure FAQ
* README.org (FAQ): Restructure and add headers. Add FAQ item on
transient menu spawning extra windows (#583, #656).
---
README.org | 65 +++++++++++++++++++++++++++++++++++++++-----------------------
1 file changed, 41 insertions(+), 24 deletions(-)
diff --git a/README.org b/README.org
index b5f8bb7f79..e156647a42 100644
--- a/README.org
+++ b/README.org
@@ -121,14 +121,18 @@ gptel uses Curl if available, but falls back to the
built-in url-retrieve to wor
- [[#rewrite-refactor-or-fill-in-a-region][Rewrite, refactor or fill in a
region]]
- [[#extra-org-mode-conveniences][Extra Org mode conveniences]]
- [[#faq][FAQ]]
- -
[[#i-want-to-use-gptel-in-a-way-thats-not-supported-by-gptel-send-or-the-options-menu][I
want to use gptel in a way that's not supported by =gptel-send= or the options
menu]]
+ - [[#chat-buffer-ui][Chat buffer UI]]
-
[[#i-want-the-window-to-scroll-automatically-as-the-response-is-inserted][I
want the window to scroll automatically as the response is inserted]]
-
[[#i-want-the-cursor-to-move-to-the-next-prompt-after-the-response-is-inserted][I
want the cursor to move to the next prompt after the response is inserted]]
- [[#i-want-to-change-the-formatting-of-the-prompt-and-llm-response][I
want to change the formatting of the prompt and LLM response]]
+ -
[[#how-does-gptel-distinguish-between-user-prompts-and-llm-responses][How does
gptel distinguish between user prompts and LLM responses?]]
+ - [[#transient-menu-behavior][Transient menu behavior]]
-
[[#i-want-the-transient-menu-options-to-be-saved-so-i-only-need-to-set-them-once][I
want the transient menu options to be saved so I only need to set them once]]
+ - [[#using-the-transient-menu-leaves-behind-extra-windows][Using the
transient menu leaves behind extra windows]]
- [[#can-i-change-the-transient-menu-key-bindings][Can I change the
transient menu key bindings?]]
- -
[[#how-does-gptel-distinguish-between-user-prompts-and-llm-responses][How does
gptel distinguish between user prompts and LLM responses?]]
-
[[#doom-emacs-sending-a-query-from-the-gptel-menu-fails-because-of-a-key-conflict-with-org-mode][(Doom
Emacs) Sending a query from the gptel menu fails because of a key conflict
with Org mode]]
+ - [[#miscellaneous][Miscellaneous]]
+ -
[[#i-want-to-use-gptel-in-a-way-thats-not-supported-by-gptel-send-or-the-options-menu][I
want to use gptel in a way that's not supported by =gptel-send= or the options
menu]]
-
[[#chatgpt-i-get-the-error-http2-429-you-exceeded-your-current-quota][(ChatGPT)
I get the error "(HTTP/2 429) You exceeded your current quota"]]
- [[#why-another-llm-client][Why another LLM client?]]
- [[#additional-configuration][Additional Configuration]]
@@ -1124,15 +1128,7 @@ You can declare the gptel model, backend, temperature,
system message and other
** FAQ
#+html: <details><summary>
-**** I want to use gptel in a way that's not supported by =gptel-send= or the
options menu
-#+html: </summary>
-
-gptel's default usage pattern is simple, and will stay this way: Read input in
any buffer and insert the response below it. Some custom behavior is possible
with the transient menu (=C-u M-x gptel-send=).
-
-For more programmable usage, gptel provides a general =gptel-request= function
that accepts a custom prompt and a callback to act on the response. You can use
this to build custom workflows not supported by =gptel-send=. See the
documentation of =gptel-request=, and the
[[https://github.com/karthink/gptel/wiki/Defining-custom-gptel-commands][wiki]]
for examples.
-
-#+html: </details>
-#+html: <details><summary>
+*** Chat buffer UI
**** I want the window to scroll automatically as the response is inserted
#+html: </summary>
@@ -1155,7 +1151,6 @@ To be minimally annoying, gptel does not move the cursor
by default. Add the fo
You can also call =gptel-end-of-response= as a command at any time.
-
#+html: </details>
#+html: <details><summary>
**** I want to change the formatting of the prompt and LLM response
@@ -1167,6 +1162,18 @@ Anywhere in Emacs: Use =gptel-pre-response-hook= and
=gptel-post-response-functi
#+html: </details>
#+html: <details><summary>
+**** How does gptel distinguish between user prompts and LLM responses?
+#+html: </summary>
+
+gptel uses
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Text-Properties.html][text-properties]]
to watermark LLM responses. Thus this text is interpreted as a response even
if you copy it into another buffer. In regular buffers (buffers without
=gptel-mode= enabled), you can turn off this tracking by unsetting
=gptel-track-response=.
+
+When restoring a chat state from a file on disk, gptel will apply these
properties from saved metadata in the file when you turn on =gptel-mode=.
+
+gptel does /not/ use any prefix or semantic/syntax element in the buffer (such
as headings) to separate prompts and responses. The reason for this is that
gptel aims to integrate as seamlessly as possible into your regular Emacs
usage: LLM interaction is not the objective, it's just another tool at your
disposal. So requiring a bunch of "user" and "assistant" tags in the buffer is
noisy and restrictive. If you want these demarcations, you can customize
=gptel-prompt-prefix-alist= and = [...]
+
+#+html: </details>
+*** Transient menu behavior
+#+html: <details><summary>
**** I want the transient menu options to be saved so I only need to set them
once
#+html: </summary>
@@ -1191,24 +1198,24 @@ Or see this
[[https://github.com/karthink/gptel/wiki/Commonly-requested-features
#+html: </details>
#+html: <details><summary>
-**** Can I change the transient menu key bindings?
+**** Using the transient menu leaves behind extra windows
#+html: </summary>
-Yes, see =transient-suffix-put=. This changes the key to select a
backend/model from "-m" to "M" in gptel's menu:
-#+begin_src emacs-lisp
-(transient-suffix-put 'gptel-menu (kbd "-m") :key "M")
-#+end_src
+If using gptel's transient menus causes new/extra window splits to be created,
check your value of =transient-display-buffer-action=.
[[https://github.com/magit/transient/discussions/358][See this discussion]] for
more context.
+
+If you are using Helm, see
[[https://github.com/magit/transient/discussions/361][Transient#361]].
+
+In general, do not customize this Transient option unless you know what you're
doing!
#+html: </details>
#+html: <details><summary>
-**** How does gptel distinguish between user prompts and LLM responses?
+**** Can I change the transient menu key bindings?
#+html: </summary>
-gptel uses
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Text-Properties.html][text-properties]]
to watermark LLM responses. Thus this text is interpreted as a response even
if you copy it into another buffer. In regular buffers (buffers without
=gptel-mode= enabled), you can turn off this tracking by unsetting
=gptel-track-responses=.
-
-When restoring a chat state from a file on disk, gptel will apply these
properties from saved metadata in the file when you turn on =gptel-mode=.
-
-gptel does /not/ use any prefix or semantic/syntax element in the buffer (such
as headings) to separate prompts and responses. The reason for this is that
gptel aims to integrate as seamlessly as possible into your regular Emacs
usage: LLM interaction is not the objective, it's just another tool at your
disposal. So requiring a bunch of "user" and "assistant" tags in the buffer is
noisy and restrictive. If you want these demarcations, you can customize
=gptel-prompt-prefix-alist= and = [...]
+Yes, see =transient-suffix-put=. This changes the key to select a
backend/model from "-m" to "M" in gptel's menu:
+#+begin_src emacs-lisp
+(transient-suffix-put 'gptel-menu (kbd "-m") :key "M")
+#+end_src
#+html: </details>
#+html: <details><summary>
@@ -1224,6 +1231,16 @@ Two solutions:
(transient-suffix-put 'gptel-menu (kbd "RET") :key "<f8>")
#+end_src
+#+html: </details>
+*** Miscellaneous
+#+html: <details><summary>
+**** I want to use gptel in a way that's not supported by =gptel-send= or the
options menu
+#+html: </summary>
+
+gptel's default usage pattern is simple, and will stay this way: Read input in
any buffer and insert the response below it. Some custom behavior is possible
with the transient menu (=C-u M-x gptel-send=).
+
+For more programmable usage, gptel provides a general =gptel-request= function
that accepts a custom prompt and a callback to act on the response. You can use
this to build custom workflows not supported by =gptel-send=. See the
documentation of =gptel-request=, and the
[[https://github.com/karthink/gptel/wiki/Defining-custom-gptel-commands][wiki]]
for examples.
+
#+html: </details>
#+html: <details><summary>
**** (ChatGPT) I get the error "(HTTP/2 429) You exceeded your current quota"
@@ -1246,7 +1263,7 @@ Other Emacs clients for LLMs prescribe the format of the
interaction (a comint s
2. Integration with org-mode, not using a walled-off org-babel block, but as
regular text. This way the model can generate code blocks that I can run.
#+html: </details>
-#+html: <details><summary>
+
** Additional Configuration
:PROPERTIES:
:ID: f885adac-58a3-4eba-a6b7-91e9e7a17829
