Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

I have many style files (and one or two class files) that I've written in my local texmf tree. Most were simple things that got me out of some trouble and which I put in to a style file in case I needed them again. One or two are quite complicated (probably unnecessarily).

My thinking is that I should add some documentation to these files. Mainly for myself: although my reasoning for defining stuff the way I did was perfectly clear when I did it, it may not be so clear next year when I try to use it again (or, worse, try to modify it again). Also for others since I do sometimes share these files, either with collaborators or with anyone who says, "Hey, that's neat! How did you do that?". But definitely not for uploading to CTAN.

So I'd like to add some basic documentation to these files. As it is just for myself, I don't feel that I want to do too much, so what I'd like is a system that is as close to the following parameters as possible:

  1. It should be "in file": I want to be able to add the documentation for a command right where the command is defined.
  2. The format should be readable when not compiled: this is a corollary of the above, since if I want to be able to read it there and then, I don't want to have to compile it first.
  3. But it should be compilable so that I can send it to someone else if I want to and they don't have to wade through the style/class file to find the documentation.
  4. However, the compiled form doesn't have to be all that pretty.

Is there such a system? Searching for 'documentation' on CTAN is like searching for snow in Norway - there's plenty of it but, to an outsider, it's hard to figure out what is the right type of snow. If there isn't a system that does what I describe, I'd be happy to hear of others' experiences in trying to do this (I'd be happy to hear them anyway, in fact).

share|improve this question
    
Related question: How does one publish/promote a new package? –  Martin Scharrer Mar 12 '11 at 11:02

1 Answer 1

up vote 16 down vote accepted

The standard is the DTX format where you put the documentation as comments around your code. Normally in the comment all code is wrapped in macrocode environments and macros again in macro environment. It is then compiled using the ltxdoc class which uses the doc package.

See more information about DTX at the TeX FAQ: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=dtx

Example:

% \begin{macro}{\mymacro}
% Some explanation
%   \begin{macrocode}
\def\mymacro#1#2{%
  \relax
  \dosomething
%   \end{macrocode}
% Explain the next part of the macro
%   \begin{macrocode}
  \domore
  \expandafter\some\code
}
%   \end{macrocode}
% \end{macro

Note that you can autogenerate a DTX file from any package or other code file using the sty2dtx script.

share|improve this answer
    
Docstrip really is the way to go here. And, you can use docstrip-style comments in any tex file just for your own use. –  Matthew Leingang Mar 9 '11 at 12:02
2  
    
My assumption had been that the DTX system was too complicated for my simple use, but looking more closely at the tutorial, I see that it might be okay. I particularly like the idea of literate programming. –  Loop Space Mar 9 '11 at 12:14
    
@Andrew: If you only want to add the DTX environments around your code use the following: sty2dtx -c code_only.sty commented_code.sty, you can add the rest of the DTX file later. The resulting file can still be loaded as package. –  Martin Scharrer Mar 9 '11 at 12:37
    
@Andrew: It's funny that the Tex world, home of Knuth's sophisticated web-weaving approach to literate programming, used such a simple-minded system for Latex. –  Charles Stewart Mar 10 '11 at 18:09

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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