I'm sure this must be a duplicate but the questions I've found don't quite address the question I have.
Related questions include:
- How to modify package documentation
- How to document style files for the use of author and collaborators
- Automatic linking of keywords in TikZ documentation
I know that the
.ins formula is the traditional method, but I do not want to use a method which requires me to re-extract the
.sty file, for example, in order to test it every time I make a change. I know I can automate this using
make or whatever but the time and faff would drive me nuts.
[I've also seen people suggest that it may not be the best option any more. For example, people point out that the existence of compressed archives makes the inclusion of documentation in the same file as the code less of an advantage, or say that well-commented code with separate user documentation is a better option than an integrated approach.]
So my question is how best to document the code of a package qua code if not using the
.ins approach. Note that I know almost nothing about documenting or even typesetting code. I have typeset a very, very little code just using a
verbatim environment or whatever. Once.
Should the code just be documented in the source file via comments? Or should it be typeset somehow? Or...?
EDITED in light of David Carlisle's comments to exclude the