Clean up protocol docs

docs/source/Concepts/Messagepath.md

@@ -116,7 +116,7 @@ This will be converted to a `commandtuple` looking like this:
 ### outputfuncs 
 
 ```{sidebar}
-`outputfuncs` are tightly coupled to the protocol and you usually don't need to touch them, unless you are adding a new protocol entirely.
+`outputfuncs` are tightly coupled to the protocol and you usually don't need to touch them, unless you are [adding a new protocol](./Protocols.md) entirely.
 ```
 Since `msg()` is aware of which [Session](../Components/Sessions.md) to send to, the outgoing `commandtuple` is always end up pointed at the right client. 
 

docs/source/Concepts/Protocols.md

@@ -1,50 +1,28 @@
-# Custom Protocols
+# Protocols
-
-
-*Note: This is considered an advanced topic and is mostly of interest to users planning to implement
-their own custom client protocol.*
-
-
-A [PortalSession](../Components/Sessions.md#portal-and-server-sessions) is the basic data object representing an
-external
-connection to the Evennia [Portal](../Components/Portal-And-Server.md) -- usually a human player running a mud client
-of some kind.  The way they connect (the language the player's client and Evennia use to talk to
-each other) is called the connection *Protocol*. The most common such protocol for MUD:s is the
-*Telnet* protocol. All Portal Sessions are stored and managed by the Portal's *sessionhandler*.
-
-It's technically sometimes hard to separate the concept of *PortalSession* from the concept of
-*Protocol* since both depend heavily on the other (they are often created as the same class). When
-data flows through this part of the system, this is how it goes
 
 ```
-# In the Portal
+            Internet│ Protocol
-You <-> 
+            ┌─────┐ │ | 
-  Protocol + PortalSession <-> 
+┌──────┐    │Text │ │  ┌──────────┐    ┌────────────┐   ┌─────┐
-    PortalSessionHandler <->
+│Client◄────┤JSON ├─┼──┤outputfunc◄────┤commandtuple◄───┤msg()│
-      (AMP) <-> 
+└──────┘    │etc  │ │  └──────────┘    └────────────┘   └─────┘
-        ServerSessionHandler <->
+            └─────┘ │
-          ServerSession <->
+                    │Evennia
-            InputFunc  
 ```
 
-(See the [Message Path](./Messagepath.md) for the bigger picture of how data flows through Evennia). The
+The _Protocol_ describes how Evennia sends and receives data over the wire to the client. Each connection-type (telnet, ssh, webclient etc) has its own protocol. Some protocols may also have variations (such plain-text Telnet vs Telnet SSL). 
-parts that needs to be customized to make your own custom protocol is the `Protocol + PortalSession`
-(which translates between data coming in/out over the wire to/from Evennia internal representation)
-as well as the `InputFunc` (which handles incoming data).
 
-## Adding custom Protocols
+See the [Message Path](./Messagepath.md) for the bigger picture of how data flows through Evennia.
+
+In Evennia, the `PortalSession` represents the client connection. The session is told to use a particular protocol. When sending data out, the session must provide an "Outputfunc" to convert the generic `commandtuple` to a form the protocol understands. For ingoing data, the server must also provide suitable [Inputfuncs](../Components/Inputfuncs.md) to handle the instructions sent to the server.
+
+## Adding a new Protocol
 
 Evennia has a plugin-system that add the protocol as a new "service" to the application.
 
-Take a look at `evennia/server/portal/portal.py`, notably the sections towards the end of that file.
+To add a new service of your own (for example your own custom client protocol) to the Portal or Server, expand  `mygame/server/conf/server_services_plugins` and `portal_services_plugins`. 
-These are where the various in-built services like telnet, ssh, webclient etc are added to the
-Portal (there is an equivalent but shorter list in `evennia/server/server.py`).
-
-To add a new service of your own (for example your own custom client protocol) to the Portal or
-Server, look at  `mygame/server/conf/server_services_plugins` and `portal_services_plugins`. By
-default Evennia will look into these modules to find plugins. If you wanted to have it look for more
-modules, you could do the following:
 
+To expand where Evennia looks for plugins, use the following settings: 
 ```python
     # add to the Server
     SERVER_SERVICES_PLUGIN_MODULES.append('server.conf.my_server_plugins')
@@ -52,23 +30,18 @@ modules, you could do the following:
     PORTAL_SERVICES_PLUGIN_MODULES.append('server.conf.my_portal_plugins')
 ```
 
-When adding a new connection you'll most likely only need to add new things to the
+> When adding a new client connection you'll most likely only need to add new things to the Portal-plugin files.
-`PORTAL_SERVICES_PLUGIN_MODULES`.
 
-This module can contain whatever you need to define your protocol, but it *must* contain a function
+The plugin module must contain a function `start_plugin_services(app)`, where the `app` arguments refers to the Portal/Server application itself. This is called by the Server or Portal when it starts up. It must contatin all startup code needed. 
-`start_plugin_services(app)`. This is called by the Portal as part of its upstart. The function
-`start_plugin_services` must contain all startup code the server need.  The `app` argument is a
-reference to the Portal/Server application itself so the custom service can be added to it. The
-function should not return anything.
 
-This is how it looks:
+Example: 
 
 ```python
     # mygame/server/conf/portal_services_plugins.py
 
     # here the new Portal Twisted protocol is defined
     class MyOwnFactory( ... ):
-       [...]
+       # [...]
 
     # some configs
     MYPROC_ENABLED = True # convenient off-flag to avoid having to edit settings all the time
@@ -93,14 +66,15 @@ This is how it looks:
 Once the module is defined and targeted in settings, just reload the server and your new
 protocol/services should start with the others.
 
-## Writing your own Protocol
+### Writing your own Protocol
 
-Writing a stable communication protocol from scratch is not something we'll cover here, it's no
+```{important}
-trivial task. The good news is that Twisted offers implementations of many common protocols, ready
+This is considered an advanced topic.
-for adapting.
+```
 
-Writing a protocol implementation in Twisted usually involves creating a class inheriting from an
+Writing a stable communication protocol from scratch is not something we'll cover here, it's no trivial task. The good news is that Twisted offers implementations of many common protocols, ready for adapting. 
-already existing Twisted protocol class and from `evennia.server.session.Session` (multiple
+
+Writing a protocol implementation in Twisted usually involves creating a class inheriting from an already existing Twisted protocol class and from `evennia.server.session.Session` (multiple
 inheritance), then overloading the methods that particular protocol uses to link them to the
 Evennia-specific inputs.
 
@@ -212,28 +186,11 @@ To send data out through this protocol, you'd need to get its Session and then y
     session.msg(text="foo")
 ```
 
-The message will pass through the system such that the sessionhandler will dig out the session and
+The message will pass through the system such that the sessionhandler will dig out the session and check if it has a `send_text` method (it has). It will then pass the "foo" into that method, which
-check if it has a `send_text` method (it has). It will then pass the "foo" into that method, which
 in our case means sending "foo" across the network.
 
 ### Receiving data 
 
-Just because the protocol is there, does not mean Evennia knows what to do with it. An
+Just because the protocol is there, does not mean Evennia knows what to do with it. An [Inputfunc](../Components/Inputfuncs.md) must exist to receive it. In the case of the `text` input exemplified above, Evennia alredy handles this input - it will parse it as a Command name followed by its inputs. So handle that you need to simply add a cmdset with commands on your receiving Session (and/or the Object/Character it is puppeting). If not you may need to add your own Inputfunc (see the [Inputfunc](../Components/Inputfuncs.md) page for how to do this.
-[Inputfunc](../Components/Inputfuncs.md) must exist to receive it. In the case of the `text` input exemplified above,
-Evennia alredy handles this input - it will parse it as a Command name followed by its inputs. So
-handle that you need to simply add a cmdset with commands on your receiving Session (and/or the
-Object/Character it is puppeting). If not you may need to add your own Inputfunc (see the
-[Inputfunc](../Components/Inputfuncs.md) page for how to do this.
 
-These might not be as clear-cut in all protocols, but the principle is there. These four basic
+These might not be as clear-cut in all protocols, but the principle is there. These four basic components - however they are accessed - links to the *Portal Session*, which is the actual common interface between the different low-level protocols and Evennia. 
-components - however they are accessed - links to the *Portal Session*, which is the actual common
-interface between the different low-level protocols and Evennia.
-
-## Assorted notes
-
-To take two examples, Evennia supports the *telnet* protocol as well as *webclient*, via ajax or
-websockets. You'll find that whereas telnet is a textbook example of a Twisted protocol as seen
-above, the ajax protocol looks quite different due to how it interacts with the
-webserver through long-polling (comet) style requests. All the necessary parts
-mentioned above are still there, but by necessity implemented in very different
-ways. 

docs/source/Contribs/Contrib-Character-Creator.md

@@ -1,9 +1,9 @@
 # Character Creator
 
-Commands for managing and initiating an in-game character-creation menu.
-
 Contribution by InspectorCaracal, 2022
 
+Commands for managing and initiating an in-game character-creation menu.
+
 ## Installation
 
 In your game folder `commands/default_cmdsets.py`, import and add

docs/source/Contribs/Contribs-Guidelines.md

@@ -44,7 +44,7 @@ Evennia has a [contrib](./Contribs-Overview.md) directory which contains optiona
 
     It's often a good idea to import useful resources in `__init__.py` to make it easier to import them.
 - Your code should abide by the [Evennia Style Guide](../Coding/Evennia-Code-Style.md). Write it to be easy to read.
-- Your contribution _must_ be covered by [unit tests](../Coding/Unit-Testing.md). Put your tests in a module `tests.py` under your contrib folder (as seen above) - Evennia will find them automatically.
+- Your contribution _must_ be covered by [unit tests](../Coding/Unit-Testing.md). Put your tests in a module `tests.py` under your contrib folder (as seen above) - Evennia will find them automatically. Use a folder `tests/` to group your tests if there are many of them across multiple modules.
 -  The `README.md` file will be parsed and converted into a document linked from [the contrib overview page](./Contribs-Overview.md). It needs to be on the following form:
 
     ```markdown

docs/source/Contribs/Contribs-Overview.md

@@ -542,9 +542,9 @@ It is a common design pattern in RPGs, particularly action games.
 
 ### `character_creator`
 
-_Commands for managing and initiating an in-game character-creation menu._
+_Contribution by InspectorCaracal, 2022_
 
-Contribution by InspectorCaracal, 2022
+Commands for managing and initiating an in-game character-creation menu.
 
 [Read the documentation](./Contrib-Character-Creator.md) - [Browse the Code](evennia.contrib.rpg.character_creator)