How to write L TEX Packages? Xue Ruini June 15, 2007

How to write LATEX Packages?
Xue Ruini
Department of Computer Science and Technology
Tsinghua University
Beijing, China
June 15, 2007
Introduction
doc and docstrip
Solutions
What’s LATEX package?
Packages
collections of commands, a.k.a template
cls \documentclass{thuthesis}
sty \usepackage{geometry}
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
Solutions
Why so many @?
TEX catecode
16 categories
11: letter; 12: other
only letters in macro name
reduce naming conflictins
\makeatletter and \makeatother
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
Solutions
Before going on
some knowledge on TEX, especially on macro
some reading on LATEX 2ε source
experiences on some useful packages
hyperref, gemoetry, footmisc, amsmath...
This is really a long march, but not a game play!
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
Solutions
Structure
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesClass{thuthesis}
[2007/05/13 3.0 Tsinghua University Thesis Template]
%\ProvidesPackage{thutils}
% [2007/05/13 3.0 Tsinghua University Thesis Template]
% codes body
\endinput
requests
name
extra information
code body
any legal TEX code!
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
Solutions
How to document your codes?
Write them directly
write your codes (@ trick)
write your documentation
I am lazy to search the documentation and update it
Hell is the other people!
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
doc and docstrip
literate programming
mix the code and the documentation
Thanks to Frank Mittelbach etc.
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
What’s doc?
a package to document your package through some convenient
commands
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
How does doc work?
a special LATEX file (dtx) but in two passes:
1st pass: as you expect
2nd pass: input itself through \DocInput{myself.dtx}
output the documentation
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
doc Example
% \section{Implementation}
%
\begin{macrocode}
%<cls>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<cls>\ProvidesClass{thuthesis}
%<cfg>\ProvidesFile{thuthesis.cfg}
%<cls|cfg>[2007/05/13 3.0 Tsinghua University Thesis Template]
%
\end{macrocode}
% The main code from here.
%
\begin{macrocode}
%<*cls>
\newif\ifthu@bachelor\thu@bachelorfalse
\DeclareOption{bachelor}{\thu@bachelortrue}
%</cls>
%
\end{macrocode}
% \begin{macro}{\YOURMACRO}
% Put explanation of |\YOURMACRO| implementation here.
%
\begin{macrocode}
\newcommand{\YOURMACRO}{...}
%
\end{macrocode}
% \end{macro}
%
% \begin{environment}{YOURENV}
% Put explanation of |YOURENV|s implementation here.
%
\begin{macrocode}
\newenvironment{YOURENV}{}{}
%
\end{macrocode}
% \end{environment}
% \Finale
\endinput
% \CheckSum{0}
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
\DocInput{thuthesis.dtx}
\end{document}
%</driver>
% \fi
%
% \changes{v0.1}{2005/07/06}{Initial version}
% \GetFileInfo{thuthesis.dtx}
%
% \DoNotIndex{\begin}
%
% \title{ThuThesis~\fileversion}
% \author{Xue Ruini}\date{\filedate}
% \maketitle
%
% \begin{abstract}
% Put text here.
% \end{abstract}
%
% \section{Introduction}
% Put text here.
%
% \section{Usage}
% \DescribeMacro{\YOURMACRO}
% Put description of |\YOURMACRO| here.
%
% \DescribeEnv{YOURENV}
% Put description of |YOURENV| here.
%
% \StopEventually{\PrintIndex\PrintChanges}
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
doc Commands
\DocInput{myself.dtx}
all % are ignored
all conflits are between \iffalse/\fi pairs.
^^A is the new comment char.
\def\MakePercentIgnore{\catcode‘\%9\relax}
\def\MakePercentComment{\catcode‘\%14\relax}
\def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment}
two parts: main documentation and implementation. \StopEventually
\DescribeMacro{h\cauthori} \DescribeEnv{hcodei}
macrocode: 4 spaces
% \begin{macro}{\name}
%
\begin{macrocode}
\def\name{Xue Ruini}
%
\end{macrocode}
% \end{macro}
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
doc Commands
\DoNotIndex{\begin,\end,\begingroup,\endgroup}
\changes{version}{date}{comment}
\MakeShortVerb{\|}
\DisableCrossrefs,\EnableCrossrefs
\PageIndex, \CodelineIndex, \PrintIndex
\OnlyDescription
\StopEventually{\PrintIndex\PrintChanges} \Finally
\Checksum{h0i}
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
What’s docstrip?
a program to extract your codes from literate programminged sources
directives in .ins, sources in .dtx
why not shell, perl, ptython? docstrip provides more than them!
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
How does docstrip work?
.dtx codes are marked by tags
single line: %<tag>
block:
%<*tag>
....
%</tag>
must be in macrocode
tag operations: &, |, !
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
docstrip Example
\input docstrip
\askforoverwritefalse
\keepsilent
\usedir{tex/latex/thuthesis}
\preamble
This is a generated file.
Copyright (C) 2005-\the\year by Xue Ruini <xueruini@gmail.com>
\endpreamble
\generate{\file{thuthesis.cls}{\from{thuthesis.dtx}{cls}}
\usepreamble\cfgpreamble
\file{thuthesis.cfg}{\from{thuthesis.dtx}{cfg}}
}
\ifToplevel{
\Msg{* Happy TeXing!}
}
\endbatchfile
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
docstrip Commands
\generate{[\file{<output>}{[\from{<input>}{<optionlist>}]*}]*}
\generate{\file{p1.sty}{\from{s1.dtx}{foo,bar}}
\file{p2.sty}{\from{s2.dtx}{baz}
\from{s3.dtx}{baz}}
\file{p3.sty}{\from{s1.dtx}{zip}
\from{s2.dtx}{zip}}}
\generate{\file{thuthesis.cls}{\from{thuthesis.dtx}{cls}}
\usepreamble\cfgpreamble
\file{thuthesis.cfg}{\from{thuthesis.dtx}{cfg}}}
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
Disadvantages
It’s really boring!
Xue Ruini
How to write L
ATEX Packages?
Introduction
doc and docstrip
doc
docstrip
Thank you!
ddress:
E_mail:
Institute of Structural Mechanics, CAEP, P.O.Bo
919-414, Mianyang, Sichuan, China, 621900
Xue Ruini
Tsinghua University
Beijing, China
qlx1205@263.net & qian_lixin@sohu.com
Tel:
08162485474(O), 08162482055(H),
13981148905(M)
Fax:
08162281485
Xue Ruini
How to write L
ATEX Packages?