Hot answers tagged

28

My package tcolorbox provides another possible answer for the question. It allows to place the source code before or after the output. With version 2.20, source and output can be set side-by-side. The output can be placed inside a colored box or outside, before the source or after the source. \documentclass{article} \usepackage[skins,listings]{tcolorbox} \...


25

I made a package tkzexample that I use for all my documentation. I upload yesterday on ctan a new version (you need to wait several days before see it) but without documentation actually ( I have a little work to do to finish the doc. The main macro is based on the \codeexampleof T. Tantau. Till gave me permission to use and modify the macro. \codeexample ...


22

The best way to understand what happens when TeX reads a .dtx file to to work through slowly and track the lines. I'll use your example with a few minor modifications (to fix what seem to be mistakes and to add some useful illustration.) I'm going to assume we are running latex <myfile>.dtx as this particular one is 'self extracting' under such ...


16

I use TeXworks for editing .dtx files: I'll explain how I set it up. On Windows, the 'vanilla' TeXworks stores its settings in C:\Users\<user>\TeXworks\configuration (Windows 7)/ C:\Documents and Settings\<user>\TeXworks\configuration (Windows XP). There, you will find a file called syntax-patterns.txt, which is best edited using TeXworks itself ...


15

The starting point for having a 'source' format is that it's a good idea to have code comments and it's also a good idea to have user documentation. The simplest way to do that of course is to put it all directly in the .sty file. % Some info for the user % ... % Some code comment \a \code \line That is seen a a good number of packages. The next ...


14

My answers is split in two parts: first I show how DTX files, i.e. docstrip tags, can be used to extract different parts for different language and then I discuss the issue that you have in a real DTX file for a package. In general you can use the docstrip tags <*lang1> ... </lang1> to mark all file sections which contain the text for the first ...


12

Something like % \iffalse %<*example> % \fi \begin{lstlisting} first line second line ... \end{lstlisting} % \iffalse %</example> % \fi should work, where example is an otherwise unused tag (it can be used for any such environment). The \iffalse...\fi prevents the tag from being printed; the tag itself prevents the uncommented code from being ...


12

If you look at the history of doc, then it is understandable why the current system works as it works. Initially the idea as to write a .sty file with the comments imbedded, but in a way that it would directly be processable by LaTeX. And that required putting every bit of documentation behind % signs. Only later docstrip appeared (to strip the comments ...


12

Disclaimer: I am a package developer, but solely for internal use (me/my institution; 9 packages and 3 classes so far). I have not uploaded a package to CTAN yet. Hence this is not the advice a more experienced LaTeX developer might give. I usually structure the development of my packages (which are dtx files at the end, using l3build as working environment)...


11

\DoNotIndex{\,} works by accident: \DoNotIndex changes the catcode of \ to 12 (other) and adds \,, to the list of excluded commands, the token register \index@excludelist. The second comma is the separator. Macro \ifnot@excluded then looks for the string consisting of a backslash \, the macro name part and the separator comma , in the list for a match using ...


10

VIM recognizes .dtx files out of the box.¹ It does not treat lines beginning with % and %% as comments and highlights the code correctly. In the same time, ^^A (the comment character inside the \DocInputed part of the .dtx) is recognized as a proper comment character. ¹ What else did you expect from VIM? ;-)


10

Makeindex also supports sort keys. Entries of \changes or sorted with the style file gglo.ist. There the actual char is =: \changes{v0.1=v0.001}... \changes{v0.2=v0.001}... ... \changes{v0.10=v0.010}... \changes{v0.123=v0.123}... This can also be automated, if \changes is redefined in the driver file: \makeatletter \@ifdefinable{\org@changes@}{% \let\...


10

A 'classical' (~LaTeX2.09) .dtx file contained the source and documentation for (usually) a LaTeX package, but not the instructions to extract the package from the source or to typeset the documentation. As such, latex foo.dtx would not result in useful output. To allow extracting, an installation (.ins) file was needed, and to allow typesetting a driver (....


10

In the original plan of docstrip the documented source would be in the .dtx file and a separate LaTeX "driver" document, which could be .tex except that might clash with files that are being generated, would be used to input the doc package and produce the documentation, and a third .ins file would be used with docstrip to control the generation of the files....


10

While you can start form ltxdoc and 'roll your own', the recommended approach is to use l3doc, which is the class used the the LaTeX3 team for expl3 itself. This is currently a rather large collection of hacks, but does deal correctly with things like _ in names, and also provides a richer set of documentation environments than ltxdoc. Regrettably, l3doc is ...


10

The first thing to remember is that you do not have to use the .dtx format to include comments in package code: you can just use a .sty. Assuming you do want to use .dtx to allow typesetting the code, etc., then you still may be able to use the .dtx directly. That is true if there is only a single 'target' in the source file: just comments and the 'live' ...


9

I've detailed some of how I approach this in my blog. I use the listings package along with some code adapted from the listings documentation: %\lst@RequireAspects{writefile} %\newsavebox{\LaTeXdemo@box} %\lstnewenvironment{LaTeXdemo}[1][code and example]{^^A % \global\let\lst@intname\@empty % \expandafter\let\expandafter\LaTeXdemo@end % \csname ...


9

It all depends, If you look at the latex format source latex.ltx that is a single file made up from multiple dtx files mostly for the reason you stated of easier management in source control. User documentation is tricky choice as well, for small packages it makes sense to put it in the (single) dtx but for larger suites a separate document is good, but then ...


9

After a bit of research, here is an excerpt on the reason for the 'dtx' and 'ins' format for file transfer. Why dtx at all? The first question to consider is why people bother with the dtx format. Not everyone does, and there are good arguments for and against each different approach. I could easily write an entire post just discussing the various ...


8

Write this in the preamble of your document \DeclareFontFamily{T1}{lmttc}{\hyphenchar \font-1 } \DeclareFontShape{T1}{lmttc}{m}{n} {<-> ec-lmtlc10}{} \DeclareFontShape{T1}{lmttc}{m}{it} {<->sub*lmttc/m/sl}{} \DeclareFontShape{T1}{lmttc}{m}{sl} {<-> ec-lmtlco10}{} \renewcommand{\ttdefault}{lmttc} If you need OT1-encoding, ...


8

The idiom used in the dtx files in the latex base is % \iffalse %% a comment to be copied to the .sty file % \fi The %% causes the comment to be copied to the generated files, and the \iffalse causes it to be skipped while typesetting. Or you could do % \iffalse % \begin{macrocode} % a comment % \end{macrocode} % \fi


8

You don't need to find it, it is already in the CTAN repository. It's packaged under ms -- http://ctan.org/tex-archive/macros/latex/contrib/ms if you are using TeX Live manager, just type tlmgr install ms on the terminal. Everything related to everyshi.sty will be installed, or you can also manually install the zipped 'ms' package that you have already ...


8

If ^ has its usual superscript meaning then ^^A is built-in primitive TeX syntax for the non-printing character control A (that is U+0001) 64 less than A. This is just an arbitrary character that Frank chose as being unlikely to be used elsewhere. The important thing about it in this context is that doc.sty does \catcode`\^^A=14 \AtBeginDocument{\catcode`\^^...


8

Just putting \DoNotIndex{\,} should work, no need for redundant braces. If you want to add more things that don't need to be indexed, you can simply add a comma: \DoNotIndex{\,,\addtocounter}


8

This is not really related to dtx but rather the usual "don't define conditionals in a conditional block" issue: % \ifcode % some code explanations % \begin{macrocode} \newif\ifcadre \cadretrue \renewcommand{\maketitle} { \ifcadre \framebox{title} \else if \ifcode is false then \begin{macrocode} is not executed so the block is not read verbatim ...


7

\EnableCrossrefs and \DisableCrossrefs These macros control, whether command names inside macrocode or macrocode* environments are indexed. From the documentation of package doc: 2.7 Cross-referencing all macros used \DisableCrossrefs, \EnableCrossrefs As already mentioned, every new macro name used within a macrocode or macrocode* ...


7

microtype.dtx uses the EC fonts (=Computer Modern in T1 font encoding). You need to install the scalable Type 1 variants. They are available as cm-super. Install it with the package manager.


7

AFAIK environment verbatim does not support the start of a line with a percent character as in the DTX file format. The following workaround can be done: The environment verbatim is written without the percent prefix: \begin{verbatim} \begin{exercise} Calculate $1 + 1 =$ \end{exercise} \end{verbatim} The inclusion in the files, generated by docstrip can ...


7

The wrong character table comes from the wrong setting for \endlinechar, see Ulrike's comment. The setting of \endlinechar to -1 is done in \inputencoding to prevent additional spaces by line ends and \par tokens by empty lines, if \inputencoding is used in horizontal mode. Thus this setting of \endlinechar is necessary, not a bug. Thus the question is ...


6

You have an 'unguarded' code line. If you have a line in the .dtx which does not start % and is 'outside' of the guards, it appears in every extracted file. You can see that if you look in the .sty or .ins files. So you want % \begin{macrocode} %<*package> \def\shouldNotBeInReadme{really} %</package> % \end{macrocode} or % \iffalse %<*...


Only top voted, non community-wiki answers of a minimum length are eligible