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'm trying to learn how to use .dtx files, docstrip etc to produce both package code and documentation from a single file. My primary source of information so far has been Joseph Wright's model dtx file and the accompanying blog post.

I've got started allright, and I can successfully output some code to the style file as well as documentation for that code in a pdf. However, I'd like the pdf to not contain the actual implementation - at least not in the same place as where I describe my macros. However, I still want to keep documentation and implementation together in the .dtx file.

After reading the The doc and shortvrb packages (pdf, link from Google search) I've tried adding \OnlyDescription to both the preamble and the document of the driver part of the .dtx, but it didn't make any difference (that I could observe in my pdf, anyway).

I'd be perfectly fine with (almost prefer) delaying the output of the verbatim package implementation to the very end of the documentation, if that's possible. However, it is not a requirement - I mainly want to ensure that the code is not intermingled with the documenation text in the pdf.

Example

I have the following few lines in my .dtx file (ignore the text - it's in Swedish, anyway...)

%\section{Paket som används}
%\textsf{fstil} använder sig av funktionalitet från följande paket:
%\begin{description}
%\item[\textsf{fontenc}, med option \textsf{T1}] Använder den modernare teckenkodningen T1, vilken t.ex. underlättar för specialtecken som åäö.
%    \begin{macrocode}
\RequirePackage[T1]{fontenc}
%    \end{macrocode}
%\end{description}

In my pdf, this outputs as

Paket som används}

fstil använder sig av funktionalitet från följande paket:

    fontenc, med option T1 Använder den modernare teckenkodningen T1, vilken t.ex. underlättar för
    specialtecken som åäö.
    1 \RequirePackage[T1]{fontenc}

I'd like to either move the last line, with the verbatim code, to the end of the document, or remove it completely.

share|improve this question
2  
you might look for an existing package that puts user documentation up front, and relegates the implementation to the back. you can use texdoc <pkgname> to look at the output; almost any package that can deliver documentation as latex output will have a .dtx file in the source area of tex live. –  barbara beeton Jan 22 '13 at 16:05
1  
Are you looking for \StopEventually? This is usually used to mark the end of the 'user' part of the documentation, as long as \OnlyDescription is also set in the preamble of the driver part of the .dtx. ('Eventually' here is a mistranslation, as the intent was more '\StopPerhaps`.) –  Joseph Wright Jan 28 '13 at 21:46
add comment

1 Answer

AFAIK, most package documentation actuall has one section consisting of user interface documentation (options, user-level commands) and one section containing the implementation details of the package (with useful comments, documented side effects of internal macros, and so on). The documentation of e.g. amstext, fixmath or microtype illustrate this.

Larger packages tend to either have a separate document for documentation (biblatex doesn't have a .dtx file IIRC, and glossaries has a separate glossaries-user manual in addition to the documented code in glossaries.pdf) or to hide the implementation part by running the \OnlyDescription macro in the preamble and issuing the \StopEventually macro before the implementation section.


Re-reading the question properly, I see that this isn't what you want. I think that if you depart from the docstrip model and do what for instance skdoc does (e.g. use verbatim to save the code in a token list and/or file), you could defer the actual printing of the code to a later stage, or omit it completely. The relevant code of that implementation is on lines 736–853 of skdoc.dtx, but it would have to be modified.

Briefly, what you'd do is:

  1. Don't use dtx files or docstrip.
  2. Define a token list for each output file (this is what \DeclareFile of skdoc does).
  3. Create an environment based on verbatim that in addition to (or instead of) printing the contents appends them to the appropriate token list (skdoc@verbatim in skdoc, which is easily patched to discard the text instead of printing it).
  4. At the end of the document, save the contents of the token list to the appropriate file (lines 773–783 of skdoc.dtx).
  5. Possibly define a macro that prints the token list like verbatim does (but leaves it intact). I don't know how to do this.
share|improve this answer
    
Do you have a good example of how to use skdoc somewhere? skdoc itself seems to be setup with docstrip... –  Tomas Lycken Feb 2 '13 at 1:29
    
My other packages (skrapport, skmath and download) use it. –  You Feb 2 '13 at 10:28
    
This still isn't really what I'm looking for - you still have a section of documentaion of all functionality, written all in comments, followed by a chapter with the implementation and some comments. That still means I have to update in two places if I make a change, albeit the two places are still in the same file now instead of a .sty file and a .tex file (as it was before I tried docstrip). I want the documentation of the package options as it appears in the documentation pdf intermingled with the implementation, the documentation of each macro with the macro, definition etc. –  Tomas Lycken Feb 2 '13 at 22:35
    
As I explained in my answer, with modification of the method used in skdoc you can get what you want. Unless I've misunderstood. –  You Feb 3 '13 at 10:13
add comment

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.