From: Marek Marecki <triviuss@gmail.com>
Date: Thu, 9 May 2013 07:07:32 +0000 (+0200)
Subject: Manual updated for posting and stream
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=8b013ef4cc4cc1da4142abd2b0429bf859afa219;p=diaspy.git

Manual updated for posting and stream
---

diff --git a/manual/posting.mdown b/manual/posting.mdown
new file mode 100644
index 0000000..5dff0a3
--- /dev/null
+++ b/manual/posting.mdown
@@ -0,0 +1,63 @@
+#### `Post()` object and posting
+
+`Post()` object is used to represent a post on D\*.
+
+----
+
+##### Posting
+
+Posting is done through a `Stream()` object method `post()`. 
+It supports posting just text, images or text and images.
+
+`Stream().post()` returns `Post()` object referring to the post 
+which have just been created.
+
+
+##### Text
+
+If you want to post just text you should call `post()` method with 
+`text` argument.
+
+    stream.post(text='Your post.')
+
+It will return `Post()` you have just created.
+
+
+##### Posting images
+
+Posting images, from back-end point of view, is a two-step process. 
+First, you have to *upload* an image to the desired pod. 
+This is done by `_photoupload()` method. 
+It will return *id* of uploaded image. 
+
+Then you have to actually post your image and this is done by appending 
+`photos` field containg the id of uploaded image to the data being 
+sent by request. This is handled by `post()` method. 
+
+`post()` has two very similar arguments used for posting photos. 
+They are `photos` - which takes id and `photo` - which takes filename. 
+
+You can post images using either of them. Even passing them side by side 
+is accepted but remember that `photos` will overwrite data set by `photo`.
+
+
+Example #1: using `photo`
+
+
+    stream.post(photo='./kitten-image.png')
+
+
+Example #2: using `photos`
+
+
+    id = stream._photoupload(filename='./kitten-image.png')
+    stream.post(photos=id)
+
+
+The effect will be the same. 
+To either call you can append `text` argument which will be posted alongside 
+the image. 
+
+----
+
+###### Manual for `diaspy`, written by Marek Marecki
diff --git a/manual/stream.mdown b/manual/stream.mdown
index eca2677..7f21f4f 100644
--- a/manual/stream.mdown
+++ b/manual/stream.mdown
@@ -2,10 +2,7 @@
 
 This object is used to represent user's stream on D\*. 
 It is returned by `Client()`'s method `get_stream()` and 
-is basically the list of posts. 
-
-It can get more functionality in future (probably it would be 
-moved from `Client()`).
+is basically a list of posts. 
 
 ----
 
@@ -55,6 +52,12 @@ Second, iterating directly over the stream contents:
         # do stuff...
 
 
+----
+
+##### Posting data to stream
+
+This is described in [`posting`](./posting.mdown) document in this manual.
+
 ----
 
 ###### Manual for `diaspy`, written by Marek Marecki