Updated README.md

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2016 LonamiWebs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -6,6 +6,33 @@ on the top of the file. Also don't forget to have a look to the original project
 The files without the previously mentioned notice are no longer part of TLSharp itself, or have enough modifications
 to make them entirely different.
 
+# Table of contents
+- [Why Telethon?](#why-telethon)
+- [Requirements](#requirements)
+  - [Python modules](#python-modules)
+  - [Obtaining your `API ID` and `Hash`](#obtaining-your-api-id-and-hash)
+- [Running Telethon](#running-telethon)
+- [Advanced uses](#advanced-uses)
+  - [How to add more functions to `TelegramClient`](#how-to-add-more-functions-to-telegramclient)
+  - [Tips for porting Telethon](#tips-for-porting-telethon)
+  - [Code generator limitations](#code-generator-limitations)
+- [Plans for the future](#plans-for-the-future)
+
+## Why Telethon?
+> Why should I bother with Telethon? You already mentioned [TLSharp](https://github.com/sochix/TLSharp).
+> [telegram-cli](https://github.com/vysheng/tg) has also been around for a long while. And we have the
+> [official](https://github.com/telegramdesktop/tdesktop) [clients](https://github.com/DrKLO/Telegram)!
+
+With Telethon you don't really need to know anything before using it. Create a client with your settings.
+Connect. You're ready to go.
+
+Being written on Python, Telethon can run as a script under any environment you wish, (yes,
+[Android too](https://f-droid.org/repository/browse/?fdfilter=termux&fdid=com.termux)). You can schedule it,
+or use it in any other script you have. Want to send a message to someone when you're available? Write a script.
+Do you want check for new messages at a given time and find relevant ones? Write a script.
+
+An official client has a feature which Telethon doesn't? [Implement it easily](#how-to-add-more-functions-to-telegramclient).
+
 ## Requirements
 ### Python modules
 This project requires the following Python modules, which can be installed by issuing `sudo -H pip3 install <module>` on a
@@ -22,13 +49,14 @@ can be changed later as long as I'm aware.
 head to `api/` directory and create a copy of the `settings_example` file, naming it `settings` (lowercase!).
 Then fill the file with the corresponding values (your `api_id`, `api_hash` and phone number in international format).
 
-### Running Telethon
+## Running Telethon
 First of all, you need to run the `tl_generator.py` by issuing `python3 tl_generator.py`. This will generate all the
 TLObjects from the given `scheme.tl` file. When it's done, you can run `python3 main.py` to start the interactive example.
 
-## How to add more functions to TelegramClient
+## Advanced uses
+### How to add more functions to `TelegramClient`
 As of now, you cannot call any Telegram function unless you first write it by hand under `tl/telegram_client.py`. Why?
-Every Telegram function (or _request_) work in its own way. In some, you may only be interested in a single result field,
+Every Telegram function (or _Request_) work in its own way. In some, you may only be interested in a single result field,
 and in others you may need to format the result in a different way. However, a plan for the future is to be able to call
 any function by giving its `namespace.name` and passing the arguments. But until that happens, to add a new function do:
 
@@ -55,12 +83,29 @@ open the file and see what the result will look like. Alternatively, you can sim
 Be warned that there may be more than one different type on the results. This is due to Telegram's polymorphism,
 for example, a message may or not be empty, etc.
 
-## Plans for the future
-If everything works well, this probably ends up being a Python package :)
+_Hint: You could even write your own class based on `TelegramClient` and add more features._
 
-But as of now, and until that happens, help is highly appreciated!
+### Tips for porting Telethon
+First of all, you need to understand how the `scheme.tl` (`TL` language) works. Every object definition is written as follows:
 
-## Code generator limitations
+`name#id argument_name:argument_type = CommonType`
+
+This means that in a single line you know what the `TLObject` name is. You know it's unique ID,
+and you know what arguments it has. It really isn't that hard to write a generator for generating code to any platform!
+
+The generated code should also be able to _encode_ the `Request` into bytes, so they can be sent over the network.
+This isn't a big deal either, because you know how the `TLObject`'s are made.
+
+Once you have your own [code generator](tl_generator.py), start by looking at the
+[first release](https://github.com/LonamiWebs/Telethon/releases/tag/v0.1) of Telethon.
+The code there is simple to understand, easy to read and hence easy to port. No extra useless features.
+Only the bare bones. Perfect for starting a _new implementation_.
+
+P.S.: I may have lied a bit. The `TL` language is not that easy. But it's not that hard either.
+You're free to sniff the `parser/` files and learn how to parse other more complex lines.
+Or simply use that code and change the [SourceBuilder](parser/source_builder.py)!
+
+### Code generator limitations
 The current code generator is not complete, yet adding the missing features would only over-complicate an already hard-to-read code.
 Some parts of the `.tl` file _should_ be omitted, because they're "built-in" in the generated code (such as writing booleans, etc.).
 
@@ -77,3 +122,8 @@ In order to make sure that all the generated files will work, please make sure t
 
 Also please make sure to rename `updates#74ae4240 ...` to `updates_tg#74ae4240 ...` or similar to avoid confusion between
 the `updates` folder and the `updates.py` file!
+
+## Plans for the future
+If everything works well, this probably ends up being a Python package :)
+
+But as of now, and until that happens, help is highly appreciated!