4

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:

  1. 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?
  2. 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, \ProvidesPackage any \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)?
  3. 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.
  4. Should \RequirePackage go in the <package> tag section along with \ProvidesPackage?
  5. Do I still use the macro environment 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 macrocode)?

P.S. The only guide/tutorial on .dtx files I found (apart from the ltxdoc, doc and docstrip documentation) was by Scott Pakin, here, any additional resources would be of help.

  • On point (2): it's up to you what you 'skip' using \iffalse, and in any case the line numbers are to help the reader of the PDF but not necessarily meant to match up with lines in the .sty (otherwise you'd just read the .sty). – Joseph Wright Jun 30 '16 at 6:06
  • Same for point (3): if you have a .dtx the assumption is people will read the PDF or the raw source, not the .sty. So you can subdivide using \section or whatever: you don't need meta-comments in the .sty. – Joseph Wright Jun 30 '16 at 6:07
  • see also this tex.stackexchange.com/q/226869/1090 – David Carlisle Jun 30 '16 at 6:44
  • Thanks, @JosephWright, I guess I was mostly wondering whether it is better practice to include every line of the source code so the user would never have to refer to the .sty file (and matching line numbers won't matter), or it is better to include the most important macros and try to match line number, so a user interested in studying/modifying the code can more easily find the place in the .sty file. It sounds to me the first option is probably better. – Aayla Secura Jun 30 '16 at 10:05

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.