Improve documentation of creating directives with pending

The text that describes how to use the transformation phase in the implementation of a directive is rather glib and simply directs the reader to study the code for the contents directive which does contain the details of how this is done, but is not ideally documented not brings the reader up in steps like the rest of the document does. I would like to contribute a small tutorial as to how this is done when I have the chance if no-one else can take this on.