Do you want to make a pull request?
That's great, but please make any documentation additions or changes only in README.md!
The file doc/perlsubst.txt is generated automatically from README.md. I haven't yet made the script and auxiliary files which do that public, because I first need to rework the documentation for my runpandoc wrapper, which is used in the conversion, after a major update, but I will make them public as soon as that is done.
Please note that any text in README.md with Markdown **strong-emphasis** will become a vimdoc *tag-target* and any text with Markdown *ordinary-emphasis* will become a vimdoc |hot-link|!