7

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:

I know that the .dtx/.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 .dtx/.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 .dtx/.ins option.

  • Do you mean the inline/in-package documentation? – user31729 May 10 '15 at 21:07
  • @ChristianHupfer Well, I assume that user documentation should not be inline. So partly I'm interested in how to produce that. But I'm also asking whether code should be commented inline, separately documented or documented in the user documentation. Basically, I have no idea how best to document a package. I have a method for font packages but those seem different - the code is much the same from package to package, and the differences are scattered in a bunch of different files so nothing but inline seems to make much sense there. – cfr May 10 '15 at 21:10
  • probably I'd say same as I said in this almost dup question tex.stackexchange.com/questions/226869/… – David Carlisle May 10 '15 at 21:11
  • 2
    the dtx is the source, the .sty is extracted from that. – David Carlisle May 10 '15 at 21:24
  • 2
    @cfr yes or more typically type make or l3build or something – David Carlisle May 10 '15 at 23:09
5

Don't rule out the .dtx method just yet :) With a nice makefile crafted for the occasion, your .sty is only a few keystrokes (and a few seconds) away. I use such a makefile for all of my LaTeX packages; see an example here.

I favour the .dtx approach because it gives you colocation of documentation and code. I can't remember where I read/heard it, but comments can be thought of as code that never gets tested. Code that is never tested tends to become incorrect, over time. Keeping the documentation and the code it's meant to describe close together minimises the risk that the former deviates from the latter.

(One of these days, I swear I'll read my copy of Don Knuth's Literate Programming to make all this clearer in my mind.)

Your Answer

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

Not the answer you're looking for? Browse other questions tagged or ask your own question.