Are there guides on conventions when it comes to writing documentation for a package (especially one in a .dtx file as opposed to a separate document). I finished my first non-trivial package and wanted to upload it to CTAN, for which I'd like to write a good standard documentation, but I am unclear about a few points:
- In the .dtx file, should the section about implementation include ALL (every single line) of the code. If not, how can I put code that will go into the .sty file but not in the documentation, should I put it in an iffalse block?
- I noticed that the line numbering in the macrocode environments only counts lines that appear as verbatim in the documentation, so the first few lines of the .sty (declaring the TeX format,
\RequirePackage) are going to offset this. Presumably the whole point of global line numbering is so that the user can jump to that line in the .sty file and find what they are looking for. How can I manually shift the current line number when needed (presumably it's kept in a counter)?
- Is it considered bad practice to include blank lines and commented lines (such as
------- INTERNAL MACRO DEFINITIONS -------to help visually partition the .sty), of course excluding them from the documentation (see point 1)? These would of course mess up the line numbering, so see point 2.
\RequirePackagego in the
<package>tag section along with
- Do I still use the
macroenvironment to document the implementation of parts that are for example defining tikz styles? If so, what do I put as the "macro" name, just leave it blank or not use any environment (just put text and
P.S. The only guide/tutorial on .dtx files I found (apart from the
docstrip documentation) was by Scott Pakin, here, any additional resources would be of help.