1008: document the format of uri.string and uri.post

src/protocol/uri.h

@@ -22,7 +22,13 @@ struct string;
 /* TODO: We should probably add path+query members instead of data. */
 
 struct uri {
-	/* The start of the uri (and thus start of the protocol string). */
+	/** The start of the URI (and thus start of the protocol %string).
+	 * The format of the whole %string is like:
+	 * "http6://elinks.cz/dir/file?query#frag" ::POST_CHAR post_data "\0"
+	 *
+	 * The post_data is not really %part of the URI but ELinks keeps it
+	 * in the same %string and can then distinguish between cache entries
+	 * for different POST requests.  See uri.post for its syntax.  */
 	unsigned char *string;
 
 	/* The internal type of protocol. Can _never_ be PROTOCOL_UNKNOWN. */
@@ -40,9 +46,27 @@ struct uri {
 	 * It can never be NULL but can have zero length. */
 	unsigned char *data;
 	unsigned char *fragment;
-	/* @post can contain some special encoded form data, used internally
-	 * to make form data handling more efficient. The data is marked by
-	 * POST_CHAR in the uri string. */
+
+	/** POST data attached to the URI.  If uri.string contains a
+	 * ::POST_CHAR, then @c post points to the following
+	 * character.  Otherwise NULL.  The syntax of the POST data
+	 * is:
+	 *
+	 * [content-type '\\n']
+	 * (hexadecimal-byte | ::FILE_CHAR file-name ::FILE_CHAR)*
+	 *
+	 * - If content-type is present, ELinks sends "Content-Type: ",
+	 *   content-type, and CRLF in the head of the POST request.
+	 *
+	 * - Each hexadecimal-byte is a byte for the body of the POST
+	 *   request.  It is encoded as two lower-case hexadecimal
+	 *   digits, most significant first.  For example, "0a" for
+	 *   ::ASCII_LF.
+	 *
+	 * - file-name is the name of a file that ELinks should send
+	 *   to the server.  It is in the charset accepted by open(),
+	 *   and not encoded.  Therefore, file names that contain
+	 *   ::FILE_CHAR cannot be used.  */
 	unsigned char *post;
 
 	/* @protocollen should only be usable if @protocol is either

src/viewer/text/form.c

@@ -869,7 +869,35 @@ add_boundary(struct string *data, struct boundary_info *boundary)
 }
 
 
-/** @todo FIXME: shouldn't we encode data at send time (in http.c) ? --Zas */
+/** Format a multipart/form-data body for a POST request.
+ *
+ * @param ses
+ *   Display an info_box() in the terminal of this session if an error
+ *   occurs.
+ * @param[in] l
+ *   List of values to be sent to the server.
+ * @param[out] data
+ *   Append the body here.  This is in the same format as uri.post,
+ *   except this never has a Content-Type at the beginning, and the
+ *   literal parts are not encoded in hexadecimal.  Therefore the
+ *   result would be ambiguous without @a bfs.
+ * @param[out] boundary
+ *   A random boundary %string, and a list of offsets where the
+ *   boundary was used, so that the caller can in principle change the
+ *   %string and update all of its uses if the original one conflicts
+ *   with some of the submitted values.  However, the caller does not
+ *   do that nowadays because reading through the attached files would
+ *   be too expensive.  It just assumes the boundary is random enough.
+ * @param[out] bfs
+ *   List of offsets of names of files to be uploaded.  This is how
+ *   the caller knows which occurrences of ::FILE_CHAR in @a data
+ *   should be encoded and which ones should not.
+ * @param[in] cp_from
+ *   Codepage of the submitted-value strings in @a l.
+ * @param[in] cp_to
+ *   Codepage wanted by the server.
+ *
+ * @todo FIXME: shouldn't we encode data at send time (in http.c) ? --Zas */
 static void
 encode_multipart(struct session *ses, LIST_OF(struct submitted_value) *l,
 		 struct string *data, struct boundary_info *boundary,
@@ -888,9 +916,9 @@ encode_multipart(struct session *ses, LIST_OF(struct submitted_value) *l,
 		add_crlf_to_string(data);
 
 		/** @bug FIXME: name is not encoded.
-		 * from RFC 1867:
+		 * From RFC 1867:
 		 * multipart/form-data contains a series of parts.
-		 * Each part is expected to contain a content-disposition
+		 * Each %part is expected to contain a content-disposition
 		 * header where the value is "form-data" and a name attribute
 		 * specifies the field name within the form,
 		 * e.g., 'content-disposition: form-data; name="xxxxx"',