mirror of
https://github.com/torvalds/linux.git
synced 2024-11-25 21:51:40 +00:00
Documentation/email-clients.txt: convert it to ReST markup
As this file is mentioned at the development-process/ book, let's convert it to ReST markup. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
Jonathan Corbet
parent
cc68fd957f
commit
06ad636710
@ -1,23 +1,27 @@
|
||||
.. _email_clients:
|
||||
|
||||
Email clients info for Linux
|
||||
======================================================================
|
||||
============================
|
||||
|
||||
Git
|
||||
----------------------------------------------------------------------
|
||||
These days most developers use `git send-email` instead of regular
|
||||
email clients. The man page for this is quite good. On the receiving
|
||||
end, maintainers use `git am` to apply the patches.
|
||||
---
|
||||
|
||||
If you are new to git then send your first patch to yourself. Save it
|
||||
as raw text including all the headers. Run `git am raw_email.txt` and
|
||||
then review the changelog with `git log`. When that works then send
|
||||
These days most developers use ``git send-email`` instead of regular
|
||||
email clients. The man page for this is quite good. On the receiving
|
||||
end, maintainers use ``git am`` to apply the patches.
|
||||
|
||||
If you are new to ``git`` then send your first patch to yourself. Save it
|
||||
as raw text including all the headers. Run ``git am raw_email.txt`` and
|
||||
then review the changelog with ``git log``. When that works then send
|
||||
the patch to the appropriate mailing list(s).
|
||||
|
||||
General Preferences
|
||||
----------------------------------------------------------------------
|
||||
-------------------
|
||||
|
||||
Patches for the Linux kernel are submitted via email, preferably as
|
||||
inline text in the body of the email. Some maintainers accept
|
||||
attachments, but then the attachments should have content-type
|
||||
"text/plain". However, attachments are generally frowned upon because
|
||||
``text/plain``. However, attachments are generally frowned upon because
|
||||
it makes quoting portions of the patch more difficult in the patch
|
||||
review process.
|
||||
|
||||
@ -25,7 +29,7 @@ Email clients that are used for Linux kernel patches should send the
|
||||
patch text untouched. For example, they should not modify or delete tabs
|
||||
or spaces, even at the beginning or end of lines.
|
||||
|
||||
Don't send patches with "format=flowed". This can cause unexpected
|
||||
Don't send patches with ``format=flowed``. This can cause unexpected
|
||||
and unwanted line breaks.
|
||||
|
||||
Don't let your email client do automatic word wrapping for you.
|
||||
@ -54,57 +58,63 @@ mailing lists.
|
||||
|
||||
|
||||
Some email client (MUA) hints
|
||||
----------------------------------------------------------------------
|
||||
-----------------------------
|
||||
|
||||
Here are some specific MUA configuration hints for editing and sending
|
||||
patches for the Linux kernel. These are not meant to be complete
|
||||
software package configuration summaries.
|
||||
|
||||
Legend:
|
||||
TUI = text-based user interface
|
||||
GUI = graphical user interface
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Legend:
|
||||
|
||||
- TUI = text-based user interface
|
||||
- GUI = graphical user interface
|
||||
|
||||
Alpine (TUI)
|
||||
************
|
||||
|
||||
Config options:
|
||||
In the "Sending Preferences" section:
|
||||
|
||||
- "Do Not Send Flowed Text" must be enabled
|
||||
- "Strip Whitespace Before Sending" must be disabled
|
||||
In the :menuselection:`Sending Preferences` section:
|
||||
|
||||
- :menuselection:`Do Not Send Flowed Text` must be ``enabled``
|
||||
- :menuselection:`Strip Whitespace Before Sending` must be ``disabled``
|
||||
|
||||
When composing the message, the cursor should be placed where the patch
|
||||
should appear, and then pressing CTRL-R let you specify the patch file
|
||||
should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file
|
||||
to insert into the message.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Claws Mail (GUI)
|
||||
****************
|
||||
|
||||
Works. Some people use this successfully for patches.
|
||||
|
||||
To insert a patch use Message->Insert File (CTRL+i) or an external editor.
|
||||
To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`)
|
||||
or an external editor.
|
||||
|
||||
If the inserted patch has to be edited in the Claws composition window
|
||||
"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be
|
||||
"Auto wrapping" in
|
||||
:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be
|
||||
disabled.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Evolution (GUI)
|
||||
***************
|
||||
|
||||
Some people use this successfully for patches.
|
||||
|
||||
When composing mail select: Preformat
|
||||
from Format->Paragraph Style->Preformatted (Ctrl-7)
|
||||
from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`)
|
||||
or the toolbar
|
||||
|
||||
Then use:
|
||||
Insert->Text File... (Alt-n x)
|
||||
:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`)
|
||||
to insert the patch.
|
||||
|
||||
You can also "diff -Nru old.c new.c | xclip", select Preformat, then
|
||||
paste with the middle button.
|
||||
You can also ``diff -Nru old.c new.c | xclip``, select
|
||||
:menuselection:`Preformat`, then paste with the middle button.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Kmail (GUI)
|
||||
***********
|
||||
|
||||
Some people use Kmail successfully for patches.
|
||||
|
||||
@ -120,11 +130,12 @@ word-wrapped and you can uncheck "word wrap" without losing the existing
|
||||
wrapping.
|
||||
|
||||
At the bottom of your email, put the commonly-used patch delimiter before
|
||||
inserting your patch: three hyphens (---).
|
||||
inserting your patch: three hyphens (``---``).
|
||||
|
||||
Then from the "Message" menu item, select insert file and choose your patch.
|
||||
Then from the :menuselection:`Message` menu item, select insert file and
|
||||
choose your patch.
|
||||
As an added bonus you can customise the message creation toolbar menu
|
||||
and put the "insert file" icon there.
|
||||
and put the :menuselection:`insert file` icon there.
|
||||
|
||||
Make the composer window wide enough so that no lines wrap. As of
|
||||
KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending
|
||||
@ -139,86 +150,96 @@ as inlined text will make them tricky to extract from their 7-bit encoding.
|
||||
|
||||
If you absolutely must send patches as attachments instead of inlining
|
||||
them as text, right click on the attachment and select properties, and
|
||||
highlight "Suggest automatic display" to make the attachment inlined to
|
||||
make it more viewable.
|
||||
highlight :menuselection:`Suggest automatic display` to make the attachment
|
||||
inlined to make it more viewable.
|
||||
|
||||
When saving patches that are sent as inlined text, select the email that
|
||||
contains the patch from the message list pane, right click and select
|
||||
"save as". You can use the whole email unmodified as a patch if it was
|
||||
properly composed. There is no option currently to save the email when you
|
||||
are actually viewing it in its own window -- there has been a request filed
|
||||
at kmail's bugzilla and hopefully this will be addressed. Emails are saved
|
||||
as read-write for user only so you will have to chmod them to make them
|
||||
:menuselection:`save as`. You can use the whole email unmodified as a patch
|
||||
if it was properly composed. There is no option currently to save the email
|
||||
when you are actually viewing it in its own window -- there has been a request
|
||||
filed at kmail's bugzilla and hopefully this will be addressed. Emails are
|
||||
saved as read-write for user only so you will have to chmod them to make them
|
||||
group and world readable if you copy them elsewhere.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Lotus Notes (GUI)
|
||||
*****************
|
||||
|
||||
Run away from it.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Mutt (TUI)
|
||||
**********
|
||||
|
||||
Plenty of Linux developers use mutt, so it must work pretty well.
|
||||
Plenty of Linux developers use ``mutt``, so it must work pretty well.
|
||||
|
||||
Mutt doesn't come with an editor, so whatever editor you use should be
|
||||
used in a way that there are no automatic linebreaks. Most editors have
|
||||
an "insert file" option that inserts the contents of a file unaltered.
|
||||
an :menuselection:`insert file` option that inserts the contents of a file
|
||||
unaltered.
|
||||
|
||||
To use ``vim`` with mutt::
|
||||
|
||||
To use 'vim' with mutt:
|
||||
set editor="vi"
|
||||
|
||||
If using xclip, type the command
|
||||
If using xclip, type the command::
|
||||
|
||||
:set paste
|
||||
before middle button or shift-insert or use
|
||||
|
||||
before middle button or shift-insert or use::
|
||||
|
||||
:r filename
|
||||
|
||||
if you want to include the patch inline.
|
||||
(a)ttach works fine without "set paste".
|
||||
(a)ttach works fine without ``set paste``.
|
||||
|
||||
You can also generate patches with ``git format-patch`` and then use Mutt
|
||||
to send them::
|
||||
|
||||
You can also generate patches with 'git format-patch' and then use Mutt
|
||||
to send them:
|
||||
$ mutt -H 0001-some-bug-fix.patch
|
||||
|
||||
Config options:
|
||||
|
||||
It should work with default settings.
|
||||
However, it's a good idea to set the "send_charset" to:
|
||||
However, it's a good idea to set the ``send_charset`` to::
|
||||
|
||||
set send_charset="us-ascii:utf-8"
|
||||
|
||||
Mutt is highly customizable. Here is a minimum configuration to start
|
||||
using Mutt to send patches through Gmail:
|
||||
using Mutt to send patches through Gmail::
|
||||
|
||||
# .muttrc
|
||||
# ================ IMAP ====================
|
||||
set imap_user = 'yourusername@gmail.com'
|
||||
set imap_pass = 'yourpassword'
|
||||
set spoolfile = imaps://imap.gmail.com/INBOX
|
||||
set folder = imaps://imap.gmail.com/
|
||||
set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
|
||||
set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
|
||||
set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
|
||||
# .muttrc
|
||||
# ================ IMAP ====================
|
||||
set imap_user = 'yourusername@gmail.com'
|
||||
set imap_pass = 'yourpassword'
|
||||
set spoolfile = imaps://imap.gmail.com/INBOX
|
||||
set folder = imaps://imap.gmail.com/
|
||||
set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
|
||||
set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
|
||||
set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
|
||||
|
||||
# ================ SMTP ====================
|
||||
set smtp_url = "smtp://username@smtp.gmail.com:587/"
|
||||
set smtp_pass = $imap_pass
|
||||
set ssl_force_tls = yes # Require encrypted connection
|
||||
# ================ SMTP ====================
|
||||
set smtp_url = "smtp://username@smtp.gmail.com:587/"
|
||||
set smtp_pass = $imap_pass
|
||||
set ssl_force_tls = yes # Require encrypted connection
|
||||
|
||||
# ================ Composition ====================
|
||||
set editor = `echo \$EDITOR`
|
||||
set edit_headers = yes # See the headers when editing
|
||||
set charset = UTF-8 # value of $LANG; also fallback for send_charset
|
||||
# Sender, email address, and sign-off line must match
|
||||
unset use_domain # because joe@localhost is just embarrassing
|
||||
set realname = "YOUR NAME"
|
||||
set from = "username@gmail.com"
|
||||
set use_from = yes
|
||||
# ================ Composition ====================
|
||||
set editor = `echo \$EDITOR`
|
||||
set edit_headers = yes # See the headers when editing
|
||||
set charset = UTF-8 # value of $LANG; also fallback for send_charset
|
||||
# Sender, email address, and sign-off line must match
|
||||
unset use_domain # because joe@localhost is just embarrassing
|
||||
set realname = "YOUR NAME"
|
||||
set from = "username@gmail.com"
|
||||
set use_from = yes
|
||||
|
||||
The Mutt docs have lots more information:
|
||||
|
||||
http://dev.mutt.org/trac/wiki/UseCases/Gmail
|
||||
|
||||
http://dev.mutt.org/doc/manual.html
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Pine (TUI)
|
||||
**********
|
||||
|
||||
Pine has had some whitespace truncation issues in the past, but these
|
||||
should all be fixed now.
|
||||
@ -226,12 +247,13 @@ should all be fixed now.
|
||||
Use alpine (pine's successor) if you can.
|
||||
|
||||
Config options:
|
||||
- quell-flowed-text is needed for recent versions
|
||||
- the "no-strip-whitespace-before-send" option is needed
|
||||
|
||||
- ``quell-flowed-text`` is needed for recent versions
|
||||
- the ``no-strip-whitespace-before-send`` option is needed
|
||||
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Sylpheed (GUI)
|
||||
**************
|
||||
|
||||
- Works well for inlining text (or using attachments).
|
||||
- Allows use of an external editor.
|
||||
@ -241,50 +263,50 @@ Sylpheed (GUI)
|
||||
- Adding addresses to address book doesn't understand the display name
|
||||
properly.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Thunderbird (GUI)
|
||||
*****************
|
||||
|
||||
Thunderbird is an Outlook clone that likes to mangle text, but there are ways
|
||||
to coerce it into behaving.
|
||||
|
||||
- Allow use of an external editor:
|
||||
The easiest thing to do with Thunderbird and patches is to use an
|
||||
"external editor" extension and then just use your favorite $EDITOR
|
||||
"external editor" extension and then just use your favorite ``$EDITOR``
|
||||
for reading/merging patches into the body text. To do this, download
|
||||
and install the extension, then add a button for it using
|
||||
View->Toolbars->Customize... and finally just click on it when in the
|
||||
Compose dialog.
|
||||
:menuselection:`View-->Toolbars-->Customize...` and finally just click on it
|
||||
when in the :menuselection:`Compose` dialog.
|
||||
|
||||
Please note that "external editor" requires that your editor must not
|
||||
fork, or in other words, the editor must not return before closing.
|
||||
You may have to pass additional flags or change the settings of your
|
||||
editor. Most notably if you are using gvim then you must pass the -f
|
||||
option to gvim by putting "/usr/bin/gvim -f" (if the binary is in
|
||||
/usr/bin) to the text editor field in "external editor" settings. If you
|
||||
are using some other editor then please read its manual to find out how
|
||||
to do this.
|
||||
option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in
|
||||
``/usr/bin``) to the text editor field in :menuselection:`external editor`
|
||||
settings. If you are using some other editor then please read its manual
|
||||
to find out how to do this.
|
||||
|
||||
To beat some sense out of the internal editor, do this:
|
||||
|
||||
- Edit your Thunderbird config settings so that it won't use format=flowed.
|
||||
Go to "edit->preferences->advanced->config editor" to bring up the
|
||||
thunderbird's registry editor.
|
||||
- Edit your Thunderbird config settings so that it won't use ``format=flowed``.
|
||||
Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up
|
||||
the thunderbird's registry editor.
|
||||
|
||||
- Set "mailnews.send_plaintext_flowed" to "false"
|
||||
- Set ``mailnews.send_plaintext_flowed`` to ``false``
|
||||
|
||||
- Set "mailnews.wraplength" from "72" to "0"
|
||||
- Set ``mailnews.wraplength`` from ``72`` to ``0``
|
||||
|
||||
- "View" > "Message Body As" > "Plain Text"
|
||||
- :menuselection:`View-->Message Body As-->Plain Text`
|
||||
|
||||
- "View" > "Character Encoding" > "Unicode (UTF-8)"
|
||||
- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)`
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
TkRat (GUI)
|
||||
***********
|
||||
|
||||
Works. Use "Insert file..." or external editor.
|
||||
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Gmail (Web GUI)
|
||||
***************
|
||||
|
||||
Does not work for sending patches.
|
||||
|
||||
@ -295,5 +317,3 @@ although tab2space problem can be solved with external editor.
|
||||
|
||||
Another problem is that Gmail will base64-encode any message that has a
|
||||
non-ASCII character. That includes things like European names.
|
||||
|
||||
###
|
||||
|
||||
Loading…
Reference in New Issue
Block a user