General ⇒ Automating sty and doc generation

[erwann]

Please help modify the pieces of code in CAPITAL letters to make this work.

code.sty:

Code: Select all

%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{foo}
\usepackage{xparse}
 \ExplSyntaxOn
%    \end{macrocode}
% Some internal:
% \begin{macro}{NAME} 
%    \begin{macrocode}
\cs_new:Npn \ewann_impl:n #1 { (#1) }
%    \end{macrocode}
% \end{macro}
%    \begin{macrocode}
 \ExplSyntaxOn
%    \end{macrocode}

Replacing NAME by \ewann_impl doesn't work (the undescore)

man.tex:

Code: Select all

\documentclass{ltxdoc}
\usepackage{creatdtx}
\usepackage{amsfonts}

\begin{document}

\title{foo}
\author{erwann}
\maketitle

% \section{Introduction}
%
% The intro
%
%\section{Install}
%
% Copy |THISPACKAGE.sty| to any path looked by the \LaTeX engine.
%
%\section{Usage}
%
%\DescribeMacro{\usepackage} 
% \cmd{\usepackage}\oarg{options}|{|\meta{path}|foo}| loads THISPACKAGE
% with options OPTIONS.
%
% \DescribeMacro{\foo}NOINDENT\cs{foo}\marg{arg1}\marg{arg2} does something with ARG1 and ARG2
%
%
\end{document}

Evidently, I would like THISPACKAGE to be automatically replaced by foo. The other missing bits have to do with formatting. For example, ARG1 should be like \marg{arg1} without the brackets.

From directory foo:

Code: Select all

$ makedtx.pl -author "erwann" -dir src -src "code\.sty=>foo.sty" -doc src/man.tex foo

Then, typeset foo.ins, foo.dtx.

[erwann]

Ancillary question: I see

Code: Select all

^^A

pop up in some of ctan's dtx. What is it, what pckg is it using?

[erwann]

Partial answers:

If I need to describe

Code: Select all

\themacro\oarg{X}\marg{Y}

I would say "option \meta{X} is... and argument \meta{Y} is ..." (see ltxdoc.pdf).

However, if the option is of the form key=val, using \meta won't look right. I don't know how to typeset these for sure (if someone would like to clarify...), but I guess it would be like this:

Code: Select all

\NewDocumentCommand\metakeyval{mm}{ % key = <value> 
	#1=$\langle$#2$\rangle$
}

\NewDocumentCommand\metakeydefault{mm}{ % key = value (the default one)
	#1=#2
}

Then

Code: Select all

\themacro\metakeyval{|X|}{x}\marg{Y}
\themacro\metakeyvaldefault{|X|}{|x|}\marg{Y}

I have a hunch the `verbatim-ization' of the key and default value could be taken care of within the macro using xparse's argument preprocessor. Yes?

I've seen equivalents to \DescribeMacro for options in cls skdoc, lt3doc, and pkg dtxdescribe, amongst others, but they don't work in this setup (makedtx). Here's the way I do it:

Code: Select all

\usepackage{marginnote}

\marginnote{\raggedleft\meta{X}} \noindent Option that controls ...

\marginnote{\raggedleft\cs{name}} \noindent \cs{name} expands to...