From 642630fea10490e3bbe214652142c51c7787de46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 23 Jun 2014 17:51:36 +0200
Subject: Add a multipart intro chapter to the guide

---
 guide/multipart_intro.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++
 guide/toc.md             |  2 +-
 2 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 guide/multipart_intro.md

diff --git a/guide/multipart_intro.md b/guide/multipart_intro.md
new file mode 100644
index 0000000..dde4099
--- /dev/null
+++ b/guide/multipart_intro.md
@@ -0,0 +1,53 @@
+Introduction to multipart
+=========================
+
+Multipart originates from MIME, an Internet standard that
+extends the format of emails. Multipart messages are a
+container for parts of any content-type.
+
+For example, a multipart message may have a part
+containing text and a second part containing an
+image. This is what allows you to attach files
+to emails.
+
+In the context of HTTP, multipart is most often used
+with the `multipart/form-data` content-type. This is
+the content-type you have to use when you want browsers
+to be allowed to upload files through HTML forms.
+
+Multipart is of course not required for uploading
+files, it is only required when you want to do so
+through HTML forms.
+
+Structure
+---------
+
+A multipart message is a list of parts. Parts may
+contain either a multipart message or a non-multipart
+content-type. This allows parts to be arranged in a
+tree structure, although this is a rare case as far
+as the Web is concerned.
+
+Form-data
+---------
+
+In the normal case, when a form is submitted, the
+browser will use the `application/x-www-form-urlencoded`
+content-type. This type is just a list of keys and
+values and is therefore not fit for uploading files.
+
+That's where the `multipart/form-data` content-type
+comes in. When the form is configured to use this
+content-type, the browser will use one part of the
+message for each form field. This means that a file
+input field will be sent in its own part, but the
+same applies to all other kinds of fields.
+
+A form with a text input, a file input and a select
+choice box will result in a multipart message with
+three parts, one for each field.
+
+The browser does its best to determine the content-type
+of the files it sends this way, but you should not
+rely on it for determining the contents of the file.
+Proper investigation of the contents is recommended.
diff --git a/guide/toc.md b/guide/toc.md
index db10317..9787f0a 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -39,7 +39,7 @@ REST
 Multipart
 ---------
 
- *  Understanding multipart
+ *  [Introduction to multipart](multipart_intro.md)
  *  [Multipart requests](multipart_req.md)
  *  Multipart responses
 
-- 
cgit v1.2.3