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.

Community
  • 1
cfr
  • 198,882
  • Do you mean the inline/in-package documentation? –  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 http://tex.stackexchange.com/questions/226869/what-to-put-into-the-dtx-file/226873#226873 – David Carlisle May 10 '15 at 21:11
  • @DavidCarlisle How do you maintain code if it is in a .dtx? That is, how does it stay in sync with a .sty, for example? I've never really understood how it works. I found a question about using sty2dtx but that doesn't explain what you do if you later change the .sty file, presumably having filled out details in the .dtx file in the meantime. – cfr May 10 '15 at 21:17
  • 2
    the dtx is the source, the .sty is extracted from that. – David Carlisle May 10 '15 at 21:24
  • @cfr see the readme of a new package that went to ctan today: https://github.com/davidcarlisle/dpctex/tree/master/elocalloc the sty isn't on ctan at all, you get the dtx and extract the package from it (essentially just removing comments in this case) – David Carlisle May 10 '15 at 21:26
  • @DavidCarlisle I know how to extract a .sty from a .dtx but if you make all changes to the .dtx, then you have to re-extract the .sty every time to test a change? – cfr May 10 '15 at 23:07
  • 2
    @cfr yes or more typically type make or l3build or something – David Carlisle May 10 '15 at 23:09
  • @DavidCarlisle I guess I'll rule out the .dtx method, then ;). Would definitely drive me nuts. – cfr May 10 '15 at 23:11
  • @cfr in the usual case you can simply use the dtx file as the .sty (ie call it .sty) that of course was the original idea, that it's just a package with comments. the stripping of comments was just for speed. – David Carlisle May 10 '15 at 23:13
  • With the advent of ZIP archives, I'm somewhat of the opinion that the dtx approach is becoming archaic. I have a few packages that use the dtx approach, but more recently, I just put the documentation in a tex file, separate from the sty file. It all gets bundled in a zip archive and shipped off to CTAN. – Steven B. Segletes May 14 '15 at 02:39
  • The answer is probably: it depends. I'm not sure that my method is the “most” efficient way: I write code and manual separately using a custom class for the manual. – cgnieder May 15 '15 at 08:28
  • Might be interesting: LJR uses separate sty and TeX file in functional package, then use some \dochighinput command to typeset the source code (with code highlighting I guess) and extract documentation etc.. – user202729 Aug 08 '22 at 07:13

1 Answers1

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.)

jub0bs
  • 58,916