Add breadcrumbs. Format markdown files to char width 100

docs/source/Command-Duration.md

@@ -58,7 +58,8 @@ This syntax will not "freeze" all commands.  While the command is "pausing",
 
 ## The more advanced way with utils.delay
 
-The `yield` syntax is easy to read, easy to understand, easy to use.  But it's not that flexible if you want more advanced options.  Learning to use alternatives might be much worth it in the end.
+The `yield` syntax is easy to read, easy to understand, easy to use.  But it's not that flexible if
+you want more advanced options.  Learning to use alternatives might be much worth it in the end.
 
 Below is a simple command example for adding a duration for a command to finish.
 
@@ -93,20 +94,40 @@ class CmdEcho(default_cmds.MuxCommand):
         self.caller.msg(string)
 ```
 
-Import this new echo command into the default command set and reload the server. You will find that it will take 10 seconds before you see your shout coming back. You will also find that this is a *non-blocking* effect; you can issue other commands in the interim and the game will go on as usual. The echo will come back to you in its own time. 
+Import this new echo command into the default command set and reload the server. You will find that
+it will take 10 seconds before you see your shout coming back. You will also find that this is a
+*non-blocking* effect; you can issue other commands in the interim and the game will go on as usual.
+The echo will come back to you in its own time.
 
 ### About utils.delay()
 
-`utils.delay(timedelay, callback, persistent=False, *args, **kwargs)` is a useful function.  It will wait `timedelay` seconds, then call the `callback` function, optionally passing to it the arguments provided to utils.delay by way of *args and/or **kwargs`. 
+`utils.delay(timedelay, callback, persistent=False, *args, **kwargs)` is a useful function.  It will
+wait `timedelay` seconds, then call the `callback` function, optionally passing to it the arguments
+provided to utils.delay by way of *args and/or **kwargs`.
 
-> Note: The callback argument should be provided with a python path to the desired function, for instance `my_object.my_function` instead of `my_object.my_function()`. Otherwise my_function would get called and run immediately upon attempting to pass it to the delay function.
-If you want to provide arguments for utils.delay to use, when calling your callback function, you have to do it separatly, for instance using the utils.delay *args and/or **kwargs, as mentioned above.
+> Note: The callback argument should be provided with a python path to the desired function, for
+instance `my_object.my_function` instead of `my_object.my_function()`. Otherwise my_function would
+get called and run immediately upon attempting to pass it to the delay function.
+If you want to provide arguments for utils.delay to use, when calling your callback function, you
+have to do it separatly, for instance using the utils.delay *args and/or **kwargs, as mentioned
+above.
 
-> If you are not familiar with the syntax `*args` and `**kwargs`, [see the Python documentation here](https://docs.python.org/2/tutorial/controlflow.html#arbitrary-argument-lists).
+> If you are not familiar with the syntax `*args` and `**kwargs`, [see the Python documentation
+here](https://docs.python.org/2/tutorial/controlflow.html#arbitrary-argument-lists).
 
-Looking at it you might think that `utils.delay(10, callback)` in the code above is just an alternative to some more familiar thing like `time.sleep(10)`. This is *not* the case. If you do `time.sleep(10)` you will in fact freeze the *entire server* for ten seconds! The `utils.delay()`is a thin wrapper around a Twisted [Deferred](http://twistedmatrix.com/documents/11.0.0/core/howto/defer.html) that will delay execution until 10 seconds have passed, but will do so asynchronously, without bothering anyone else (not even you - you can continue to do stuff normally while it waits to continue).
+Looking at it you might think that `utils.delay(10, callback)` in the code above is just an
+alternative to some more familiar thing like `time.sleep(10)`. This is *not* the case. If you do
+`time.sleep(10)` you will in fact freeze the *entire server* for ten seconds! The `utils.delay()`is
+a thin wrapper around a Twisted
+[Deferred](http://twistedmatrix.com/documents/11.0.0/core/howto/defer.html) that will delay
+execution until 10 seconds have passed, but will do so asynchronously, without bothering anyone else
+(not even you - you can continue to do stuff normally while it waits to continue).
 
-The point to remember here is that the `delay()` call will not "pause" at that point when it is called (the way `yield` does in the previous section). The lines after the `delay()` call will actually execute *right away*. What you must do is to tell it which function to call *after the time has passed* (its "callback"). This may sound strange at first, but it is normal practice in asynchronous systems. You can also link such calls together as seen below:
+The point to remember here is that the `delay()` call will not "pause" at that point when it is
+called (the way `yield` does in the previous section). The lines after the `delay()` call will
+actually execute *right away*. What you must do is to tell it which function to call *after the time
+has passed* (its "callback"). This may sound strange at first, but it is normal practice in
+asynchronous systems. You can also link such calls together as seen below:
 
 ```python
 from evennia import default_cmds, utils
@@ -148,7 +169,8 @@ class CmdEcho(default_cmds.MuxCommand):
         self.caller.msg("... %s ..." % self.args.lower())
 ```
 
-The above version will have the echoes arrive one after another, each separated by a two second delay. 
+The above version will have the echoes arrive one after another, each separated by a two second
+delay.
 
     > echo Hello!
     ... HELLO!
@@ -157,9 +179,19 @@ The above version will have the echoes arrive one after another, each separated
 
 ## Blocking commands
 
-As mentioned, a great thing about the delay introduced by `yield` or `utils.delay()` is that it does not block. It just goes on in the background and you are free to play normally in the interim. In some cases this is not what you want however. Some commands should simply "block" other commands while they are running. If you are in the process of crafting a helmet you shouldn't be able to also start crafting a shield at the same time, or if you just did a huge power-swing with your weapon you should not be able to do it again immediately. 
+As mentioned, a great thing about the delay introduced by `yield` or `utils.delay()` is that it does
+not block. It just goes on in the background and you are free to play normally in the interim. In
+some cases this is not what you want however. Some commands should simply "block" other commands
+while they are running. If you are in the process of crafting a helmet you shouldn't be able to also
+start crafting a shield at the same time, or if you just did a huge power-swing with your weapon you
+should not be able to do it again immediately.
 
-The simplest way of implementing blocking is to use the technique covered in the [Command Cooldown](Command-Cooldown) tutorial. In that tutorial we implemented cooldowns by having the Command store the current time. Next time the Command was called, we compared the current time to the stored time to determine if enough time had passed for a renewed use. This is a *very* efficient, reliable and passive solution. The drawback is that there is nothing to tell the Player when enough time has passed unless they keep trying.
+The simplest way of implementing blocking is to use the technique covered in the [Command
+Cooldown](Command-Cooldown) tutorial. In that tutorial we implemented cooldowns by having the
+Command store the current time. Next time the Command was called, we compared the current time to
+the stored time to determine if enough time had passed for a renewed use. This is a *very*
+efficient, reliable and passive solution. The drawback is that there is nothing to tell the Player
+when enough time has passed unless they keep trying.
 
 Here is an example where we will use `utils.delay` to tell the player when the cooldown has passed:
 
@@ -203,15 +235,22 @@ class CmdBigSwing(default_cmds.MuxCommand):
         self.caller.msg("You regain your balance.")
 ```    
 
-Note how, after the cooldown, the user will get a message telling them they are now ready for another swing. 
+Note how, after the cooldown, the user will get a message telling them they are now ready for
+another swing.
 
-By storing the `off_balance` flag on the character (rather than on, say, the Command instance itself) it can be accessed by other Commands too. Other attacks may also not work when you are off balance. You could also have an enemy Command check your `off_balance` status to gain bonuses, to take another example.
+By storing the `off_balance` flag on the character (rather than on, say, the Command instance
+itself) it can be accessed by other Commands too. Other attacks may also not work when you are off
+balance. You could also have an enemy Command check your `off_balance` status to gain bonuses, to
+take another example.
 
 ## Abortable commands
 
-One can imagine that you will want to abort a long-running command before it has a time to finish. If you are in the middle of crafting your armor you will probably want to stop doing that when a monster enters your smithy. 
+One can imagine that you will want to abort a long-running command before it has a time to finish.
+If you are in the middle of crafting your armor you will probably want to stop doing that when a
+monster enters your smithy.
 
-You can implement this in the same way as you do the "blocking" command above, just in reverse. Below is an example of a crafting command that can be aborted by starting a fight: 
+You can implement this in the same way as you do the "blocking" command above, just in reverse.
+Below is an example of a crafting command that can be aborted by starting a fight:
 
 ```python
 from evennia import utils, default_cmds
@@ -304,11 +343,18 @@ class CmdAttack(default_cmds.MuxCommand):
         # [...]
 ```
 
-The above code creates a delayed crafting command that will gradually create the armour. If the `attack` command is issued during this process it will set a flag that causes the crafting to be quietly canceled next time it tries to update.
+The above code creates a delayed crafting command that will gradually create the armour. If the
+`attack` command is issued during this process it will set a flag that causes the crafting to be
+quietly canceled next time it tries to update.
 
 ## Persistent delays
 
-In the latter examples above we used `.ndb` storage. This is fast and easy but it will reset all cooldowns/blocks/crafting etc if you reload the server. If you don't want that you can replace `.ndb` with `.db`. But even this won't help because the `yield` keyword is not persisent and nor is the use of `delay` shown above. To resolve this you can use `delay` with the `persistent=True` keyword. But wait! Making something persistent will add some extra complications, because now you must make sure Evennia can properly store things to the database.
+In the latter examples above we used `.ndb` storage. This is fast and easy but it will reset all
+cooldowns/blocks/crafting etc if you reload the server. If you don't want that you can replace
+`.ndb` with `.db`. But even this won't help because the `yield` keyword is not persisent and nor is
+the use of `delay` shown above. To resolve this you can use `delay` with the `persistent=True`
+keyword. But wait! Making something persistent will add some extra complications, because now you
+must make sure Evennia can properly store things to the database.
 
 Here is the original echo-command reworked to function with persistence: 
 ```python
@@ -345,7 +391,13 @@ class CmdEcho(default_cmds.MuxCommand):
 ```
 
 Above you notice two changes: 
-- The callback (`echo`) was moved out of the class and became its own stand-alone function in the outermost scope of the module. It also now takes `caller` and `args` as arguments (it doesn't have access to them directly since this is now a stand-alone function).
-- `utils.delay` specifies the `echo` function (not `self.echo` - it's no longer a method!) and sends `self.caller` and `self.args` as arguments for it to use. We also set `persistent=True`. 
+- The callback (`echo`) was moved out of the class and became its own stand-alone function in the
+outermost scope of the module. It also now takes `caller` and `args` as arguments (it doesn't have
+access to them directly since this is now a stand-alone function).
+- `utils.delay` specifies the `echo` function (not `self.echo` - it's no longer a method!) and sends
+`self.caller` and `self.args` as arguments for it to use. We also set `persistent=True`.
 
-The reason for this change is because Evennia needs to `pickle` the callback into storage and it cannot do this correctly when the method sits on the command class. Now this behave the same as the first version except if you reload (or even shut down) the server mid-delay it will still fire the callback when the server comes back up (it will resume the countdown and ignore the downtime).  
+The reason for this change is because Evennia needs to `pickle` the callback into storage and it
+cannot do this correctly when the method sits on the command class. Now this behave the same as the
+first version except if you reload (or even shut down) the server mid-delay it will still fire the
+callback when the server comes back up (it will resume the countdown and ignore the downtime).