1

I would like to be able to add something to the documentation of a package in dtx format but using \OnlyDescription.

I don't want the Implementation section, but somewhere on the package code I want to add a comment to be written to the documentation.

Neither starting the line with %<driver> nor with % results in appending this line to the package documentation, I guess because the driver section at the beginning of dtx file ends with \end{document}, so everything after this line is ignored.

There is a solution moving \end{document} or \StopEventually to a different place?

The purpose is writing TO-DO notes with the package todo regarding something to be done in the code, but would be good if all these notes appears in the documentation after the change history, for example. I don't include the code section in the documentation (\OnlyDescription). MWE:

% \iffalse meta-comment
% ...
%<*internalbatchfile>
\begingroup
%</internalbatchfile>
%<*batchfile>
\input docstrip.tex
\nopreamble
\keepsilent
\askforoverwritefalse
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
%</batchfile>
%<batchfile>\endbatchfile
%<*internalbatchfile>
\endgroup
%</internalbatchfile>
%<*driver>
\ProvidesFile{test.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
%<package>\ProvidesPackage{test}[2015/03/28 v1.00 Test package]
%<*driver>
\documentclass{ltxdoc}
\OnlyDescription
\begin{document}
 \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% \CheckSum{0}
% \section{doc begins}
% \StopEventually{}
%    \begin{macrocode}
%<*package>
\relax
% **Here** I would like to add something to the documentation here between 'package' tags.
%</package>
%    \end{macrocode}
%\Finale
  • 1
    I think we need a MWE: I don't really see what you are after here. – Joseph Wright Mar 29 '15 at 8:24
  • Just added the MWE. – Emilio Lazo Mar 29 '15 at 16:50
  • What I'm missing here is why you have \StopEventually{} before the stuff you want in the doc part: the whole point of \StopEventually{} to mark the end of the 'documentation'. You can happily have DocStrip guards before it or even set them up for out-of-order code extraction. Perhaps that's what you need: I can provide a demo :-) – Joseph Wright Mar 29 '15 at 16:53
  • For example moving \StopEventually{} to the end, just before \Finale? This way the whole code is written to the pdf documentation... or how? – Emilio Lazo Mar 29 '15 at 16:59
  • You can split the code part: doesn't all have to be in one block, all before or all after \StopEventually{}. I'm still not really seeing the issue here! Perhaps pop into chat: this might need a bit of discussion! – Joseph Wright Mar 29 '15 at 17:01
3

This does what you want. Make sure the two final lines of the .dtx are

% \Finale
% \starttodo

Here is the code

% \iffalse meta-comment
% Time-stamp: <29-03-2015 22:35:13 CEST>
% http://tex.stackexchange.com/q/235680/4686
%<*internalbatchfile>
\begingroup
%</internalbatchfile>
%<*batchfile>
\input docstrip.tex
\nopreamble
\keepsilent
\askforoverwritefalse
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
%</batchfile>
%<batchfile>\endbatchfile
%<*internalbatchfile>
\endgroup
%</internalbatchfile>
%<*driver>
\ProvidesFile{testspecial.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
%<package>\ProvidesPackage{testspecial}[2015/03/28 v1.00 Test package]
%<*driver>
\documentclass{ltxdoc}
%\OnlyDescription
\begin{document}
 \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% \long\def\stoptodo#1\starttodo {}%
% \long\def\starttodo#1\stoptodo {}%
% \makeatletter
% \def\endorgo #1{\ifx #1\endinput\expandafter\stoptodo
%                  \else #1\expandafter\@gobble\fi}%
% \makeatother
% \CheckSum{0}
% \section{doc begins}
% This is the documentation for this package.
%
% \StopEventually{\endorgo}
%
% \section{implementation begins}
% The code required years of efforts. Finally I found this:
% \starttodo
% IMPORTANT NOTE TO MYSELF! Try to enhance the package with some features.
% \stoptodo
%    \begin{macrocode}
%<*package>
\relax
%    \end{macrocode}
% And after a few more years I got that:
% \starttodo
% SECOND IMPORTANT NOTE TO MYSELF: at least try.
% \stoptodo
%    \begin{macrocode}
\endinput
%</package>
%    \end{macrocode}
% \Finale
% \starttodo

Here is the result without \OnlyDescription:

enter image description here

and the result with \OnlyDescription:

enter image description here

  • I'll try your code! The package urges us and the TeX engine to relax. Isn't a good recommendation? ;-) – Emilio Lazo Mar 29 '15 at 21:05
  • It works, but not always... We can't put the to-do code in any place, for example inside a group {}. If we define a command in the package, the to-do note must be written before or after the definition because it can't be placed between the braces! – Emilio Lazo Mar 30 '15 at 6:09

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.