From bc6fa26ca04ba4bc8430b98e775f40b616468e77 Mon Sep 17 00:00:00 2001 From: Tim Pope Date: Sat, 15 Nov 2003 06:51:18 +0000 Subject: [PATCH] Wrote several pages of documentation --- mlastyle.dtx | 269 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 206 insertions(+), 63 deletions(-) diff --git a/mlastyle.dtx b/mlastyle.dtx index 5da97f8..9294498 100644 --- a/mlastyle.dtx +++ b/mlastyle.dtx @@ -18,11 +18,27 @@ % \iffalse %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\ProvidesPackage{mlastyle} -% [2003/10/21 v1.0 .dtx mlastyle file] +% [2003/11/09 v0.9 .dtx mlastyle file] % %<*driver> -\documentclass{ltxdoc} -\usepackage[compat]{mlastyle} +\documentclass[draft]{ltxdoc} +\iftrue + \usepackage[compat]{mlastyle} + \addtolength{\headsep}{-25pt} + \addtolength{\headheight}{-12pt} + \addtolength{\topmargin}{-17pt} + \addtolength{\textheight}{58pt} + \IfFileExists{ulem.sty}{\usepackage[normalem]{ulem}}{\let\uline\emph} +\else + \usepackage[mla]{mlastyle} + \addtolength{\marginparwidth}{1in} + \addtolength{\textwidth}{-1in} + \addtolength{\headwidth}{-1in} +\fi +\IfFileExists{times.sty}% + {\newcommand{\examp}[2][]{{\let\emph\uline\fontfamily{ptm}\selectfont##2}##1}}% + {\newcommand{\examp}[2][]{``##2##1''}} + \EnableCrossrefs \CodelineIndex \RecordChanges @@ -52,7 +68,8 @@ % Right brace \} Tilde \~} % % -% \changes{v1.0}{2003/09/25}{Initial version} +% \changes{v0.9}{2003/11/09}{Converted to \texttt{dtx} file} +% \changes{v0.8}{2003/10/15}{Initial version} % % \GetFileInfo{mlastyle.sty} % @@ -222,22 +239,32 @@ % \DoNotIndex{\pdfpagewidth} % \DoNotIndex{\special} % -% \newcommand*{\Lopt}[1]{\textsf {#1}} -% \newcommand*{\file}[1]{\texttt {#1}} -% \newcommand*{\package}[1]{\textsf {#1}} -% \newcommand*{\Lcount}[1]{\textsl {\small#1}} -% \newcommand*{\pstyle}[1]{\textsl {#1}} +% \hyphenation{pre-am-ble pro-fess-ors} +% +% \newcommand{\Lopt}[1]{\textsf {#1}} +% \newcommand{\file}[1]{\texttt {#1}} +% \newcommand{\package}[1]{\textsf {#1}} +% ^^A\newcommand{\Lcount}[1]{\textsl {\small#1}} +% ^^A\newcommand{\pstyle}[1]{\textsl {#1}} +% +% \newcommand{\OptionIndex}[1]{\index{#1\actualchar\Lopt{#1} (option)\encapchar usage}\index{options:\levelchar\Lopt{#1}}} % % \title{The \package{mlastyle} package\thanks{This document % corresponds to \package{mlastyle}~\fileversion, dated \filedate.}} % \author{Tim Pope \\ \texttt{latex@rebelongto.us}} +% \surname{Pope} % % \maketitle +% \tableofcontents % % \section{Introduction} % -% MLA style is ugly. Nevertheless, it is often required, particularly in -% the humanities. +% MLA style consists of a set of documentation conventions that has gained +% widespread acceptance in the humanites. \LaTeX{} is a +% document preparation system enjoying populatity in the scientific field. +% It should come as no surprise that complete, up-to-date implementations +% of MLA style for \LaTeX{} are in short supply. The \LaTeX{} package +% \package{mlastyle} aims to fill this void. % % \section{Usage} % @@ -256,29 +283,24 @@ %\maketitle %'Nuff said. %\end{document}\end{verbatim} -% \subsection{Initiation Macros} -% \DescribeMacro{\maketitle} -% \DescribeMacro{\instructor} -% \DescribeMacro{\course} -% The mandatory heading\index{heading|usage} is generated with -% |\maketitle|. Use the standard macros |\author|, |\title|, and |\date| -% to specify the relevant information. To define the instructor and name -% of the course, use the aptly named |\instructor|\marg{instructor} and -% |\instructor|\marg{course} macros. -% -% \DescribeMacro{\surname} +% \subsection{Initialization Macros} +% The \index{heading|usage}mandatory heading is generated with +% \DescribeMacro{\maketitle}|\maketitle|. Use the standard macros +% |\author|, |\title|, and |\date| to specify the relevant information. +% To define the instructor and name of the course, use the aptly named +% \DescribeMacro{\instructor}|\instructor|\marg{instructor} and +% \DescribeMacro{\course}|\course|\marg{course} macros. +% % The last name for use in the header\index{header|usage} is derived from % |\author|. If this does not produce the desired result, use -% |\surname|\marg{last name} to override it. +% \DescribeMacro{\surname}|\surname|\marg{last name} to override it. % -% \DescribeMacro{\date} -% \DescribeMacro{\today} % MLA style recommends the DD~Mon.~YYYY format for specifying dates; -% |\today| has been conveniently redefined to this. However, other -% formats can be used as long as done so consistantly throughout the -% document. Also note that the date in the header should be the due date -% of the assignment, so be sure to explictly call |\date|\marg{due date} -% if you actually finish your assignments early. +% \DescribeMacro{\today}|\today| has been conveniently redefined to this. +% However, other formats can be used as long as done so consistently +% throughout the document. Also note that the date in the header should +% be the due date of the assignment; students who finish assignments early +% would be wise to call |\date|\marg{due date}. % % \subsection{Environments} % \DescribeEnv{verse} @@ -296,12 +318,128 @@ % quotes should be enclosed in quotation marks and included directly in % the text. % -% \subsection{Documentating Sources} +% \subsection{Modes of Operation} +% The \package{mlastyle} package has four basic modes of operations, +% selected with one of four mutually exclusive options. The +% \OptionIndex{format}\Lopt{format} +% option tells \package{mlastyle} to use MLA format (i.e., 1 inch margins, +% double-spaced, etc.). The \OptionIndex{style}\Lopt{style} option tells +% \package{mlastyle} to use MLA style (i.e., parenthetical documentation +% includes the author and page number, etc). Each of these options +% disables the other; to use both MLA format and MLA style, specify the +% \OptionIndex{mla}\Lopt{mla} option, or nothing at all. +% +% To disable both MLA style and MLA format, use the +% \OptionIndex{compat}\Lopt{compat} option. This differs from omitting +% the package entirely in that certain macros are still defined (e.g., +% |\instructor|). Also, citations are handled a bit differently than in +% standard \LaTeX{} (see section~\ref{sec:documentation}). +% +% In addition to the above, several other options modify the behavior of +% \package{mlastyle}. % -% Coupled with \BibTeX\index{BibTeX\actualchar\BibTeX|usage} +% \subsubsection{Italics vs.\ Underlining} \index{underlining|usage} +% \index{italics|usage} +% MLA format dictates that emphasis should be indicated by underlining the +% text. Thus, the \package{ulem} package is loaded by default +% in \Lopt{mla} and \Lopt{format} modes. To disable this, use the +% \OptionIndex{italics}\Lopt{italics} option. Conversely, if underlining +% is desired in \Lopt{style} or \Lopt{compat} mode, the +% \OptionIndex{underline}\Lopt{underline} option can be used. +% +% \subsubsection{Fonts} +% By default, \package{mlastyle} uses \TeX's standard Computer Modern +% font. Some professors\penalty\exhyphenpenalty---particularly those +% concerned with document length---mandate that assignments be set in +% \examp[.]{Times} This can be achieved with the +% \OptionIndex{times}\Lopt{times} option, which simply loads the +% \package{times} package. This option can be cancelled with +% the \OptionIndex{cm}\Lopt{cm} option, which reverts to Computer Modern. +% +% \index{works cited|usage} +% \subsection{Documenting Sources} \label{sec:documentation} +% +% The \package{mlastyle} package reimpliments the +% \DescribeEnv{thebibliography}|thebibliography| environment to generate +% the list of works cited in MLA style. Use of \LaTeX's bibliography +% features is beyond the scope of this document; however, the following +% example, which should be included just before |\end{document}|, might +% prove to be a useful starting point: +%\begin{verbatim} +%\begin{thebibliography}{} +% +%\bibitem[Lamport]{latex} +%Lamport, Leslie. +%\newblock {\em \LaTeX: A Document Preparation System}. +%\newblock 2nd.~ed. +%\newblock Reading: Addison-Wesley, 1994. +% +%\end{thebibliography}\end{verbatim} +% +% In this example, |Lamport| is the author's last name (for use in +% citations) and |latex| is the marker used to reference it (see +% section~\ref{sec:parenthetical}). +% +% For information on automatically generating the list of works cited with +% \BibTeX, see section~\ref{sec:bibtex}. +% +% \subsubsection{Parenthetical Documentation} \label{sec:parenthetical} +% A simple citation can by achieved with a call to +% \DescribeMacro{\cite}|\cite|\oarg{pages}\marg{marker}, where +% marker refers to the key given to either +% \index{BibTeX=\BibTeX|usage}\BibTeX{} or the |\bibitem| macro (|latex| +% in the above example). +% Omit \oarg{pages} if the source has no page numbers. +% Multiple sources can be cited using the syntax +% |\cite|\oarg{pages}|{|\meta{marker +% 1}\texttt{,}\penalty\exhyphenpenalty\meta{marker 2}\ldots|}|; however, page +% numbers can currently be specified only for the last referenced source. +% To work around this limitation |\citeN|, explained below, can be used. +% +% Three additional citation commands are provided, all of which take the +% same arguments as |\cite|. To omit the author information from the +% citation, use \DescribeMacro{\citepage}|\citepage|. Indirect +% citations---those of the format \examp{(qtd. in Brown 6)}---can be +% created with \DescribeMacro{\citeindirect}|\citeindirect|. Finally, the +% parentheses are omitted by \DescribeMacro{\citeN}|\citeN|. This was +% intended for use in cross references, but it can also help in citing +% multiple works. The result of +% |(\citeN[42]{knuth}|\texttt{; }|\citeN[69]{lamport})| +% would be something like \examp[.]{(Knuth 42; Lamport 69)} +% +% \subsubsection{Using {\rm \BibTeX}} \label{sec:bibtex} +% Coupled with \index{BibTeX=\BibTeX|usage}\BibTeX, % \package{mlastyle} provides a experimental implementation of MLA -% documentation style. Put |\bibliographystyle{mlastyle}| in the document -% preamble to load the bibliography style. +% documentation style. Put\SpecialUsageIndex{\bibliographystyle} +% |\bibliographystyle{mlastyle}| in the document preamble to load the +% bibliography style. Alternatively, the +% \OptionIndex{bibstyle}\Lopt{bibstyle} option can handle this +% automatically, loading a bibliography style of |mlastyle| in \Lopt{mla} +% and \Lopt{style} modes and a bibliography style of |plain| in +% \Lopt{format} and \Lopt{compat} modes. +% +% Use of \BibTeX{} is also beyond the scope of this document; instead, +% another example is provided. To use it, substitute +% |\bibliography|\marg{filename} for the |thebibliography| environment. +% Then create \meta{filename}\file{.bib} with the contents below. +% Generating the document entails running \file{latex} on the \file{.tex} +% file, \file{bibtex} on the resulting \file{.aux} file, then \file{latex} +% twice more. +%\begin{verbatim} +%@BOOK{latex, +% AUTHOR = "Leslie Lamport", +% TITLE = "\LaTeX: A Document Preparation System", +% KEY = "\LaTeX", +% EDITION = "Second", +% ADDRESS = "Reading", +% PUBLISHER = "Addison-Wesley", +% YEAR = "1994"}\end{verbatim} +% In \package{mlastyle}, The |KEY| field serves the additional purpose of +% specifying an abbreviated title. This is unnecessary in the above +% example. If an additional book by Leslie Lamport was included, however, +% the |KEY| field would allow |\cite{lamport}| to yield \examp{(Lamport, +% \emph{\LaTeX\/})} instead of \examp[.]{(Lamport, \emph{\LaTeX: A Document +% Preparation System\/})} % % \StopEventually{\PrintChanges\PrintIndex} % @@ -411,14 +549,13 @@ % \end{macrocode} % \end{macro} % \subsection{Formatting} -% Formatting is only done if the \Lopt{format} option is set. This is the -% default. +% Formatting is done if the \Lopt{mla} or \Lopt{format} option is set. % \begin{macrocode} \ifmlastyle@format % \end{macrocode} % \subsubsection{Macros} % \begin{macro}{\maketitle} -% Redefined |\maketitle| generate a heading in MLA format. +% |\maketitle| generates a heading in MLA format. % \begin{macrocode} \renewcommand{\maketitle}{\begin{flushleft} \@author\par @@ -439,9 +576,9 @@ % \end{macro} % \begin{macro}{\slash} % No penalty for |\slash|, and plain /'s permit line breaks if necessary. +% ^^A\let\mlastyle@sl@sh=/ % \begin{macrocode} \def\slash{/\penalty\z@} - %\let\mlastyle@sl@sh=/ \def\mlastyle@slash{/\futurelet\mlastyle@slashnext\mlastyle@slashx} \def\mlastyle@slashx{\ifx\mlastyle@slashnext/\else \penalty\exhyphenpenalty\fi} @@ -456,7 +593,11 @@ }{0pt}{1sp}{\centering}} \renewcommand{\subsection}{\@startsection{subsection}{2}{\z@ }{0pt}{1sp}{\centering}} + \renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{\z@ + }{0pt}{1sp}{\centering}} % \end{macrocode} +% ^^A\let\mlastyle@vfont\verbatim@font +% ^^A\def\verbatim@font{\mlastyle@qspread\mlastyle@vfont} % \end{macro} % \end{macro} % \subsubsection{Environments} @@ -498,14 +639,13 @@ % \subsubsection{Margins} % Top and bottom margins are 1 inch each. The header is flush with the % right margin at .5 inches from the top of the page. -% ^^A%\settoheight{\headheight}{\llap{\parbox[b]{\textwidth}{\large\raggedleft Pope}}} +% ^^A\addtolength{\headheight}{-1pt} +% ^^A\setlength{\headheight}{1.4\headheight}% kludge % \begin{macrocode} \addtolength{\voffset}{-0.5in} \setlength{\textheight}{\paperheight} \addtolength{\textheight}{-2in} \setlength{\topmargin}{0in} - %\addtolength{\headheight}{-1pt} - %\setlength{\headheight}{1.4\headheight}% kludge \setlength\headheight\f@baselineskip \setlength{\headsep}{0.5in} \addtolength{\headsep}{-\headheight} @@ -564,8 +704,7 @@ \fancyhf{} \rhead{\mlastyle@surname{} \thepage} \renewcommand{\headrulewidth}{0pt} - \renewcommand{\footrulewidth}{0pt} - } + \renewcommand{\footrulewidth}{0pt}} \pagestyle{mlastyle} % \end{macrocode} % \subsubsection{Notes} @@ -593,7 +732,7 @@ \def\enotesize{\normalsize} \fi % \end{macrocode} -% \subsubsection{Miscellaneous} +% \subsubsection{Bibliography} % The definition of |\thebibliography| varies depending on the document % class. % \begin{macrocode} @@ -601,8 +740,7 @@ % \end{macrocode} % Article class. % \begin{macrocode} - { - \def\thebibliography#1{\newpage\section*{\refname} + { \def\thebibliography#1{\newpage\section*{\refname} \list{\@biblabel{\@arabic\c@enumiv}}% {\settowidth\labelwidth{\@biblabel{#1}}} \leftmargin\labelwidth @@ -611,14 +749,11 @@ \def\newblock{} \usecounter{enumiv} \sloppy%\sfcode`\.=1000\relax - \catcode`/=13 - \let/=\mlastyle@slash - }} + \catcode`/=13\let/=\mlastyle@slash}} % \end{macrocode} % Report/book class. % \begin{macrocode} - { - \def\thebibliography#1{\chapter*{\bibname} + { \def\thebibliography#1{\chapter*{\bibname} \list{\@biblabel{\@arabic\c@enumiv}}% {\settowidth\labelwidth{\@biblabel{#1}}} \leftmargin\labelwidth @@ -627,30 +762,30 @@ \def\newblock{} \usecounter{enumiv} \sloppy%\sfcode`\.=1000\relax - \catcode`/=13 - \let/=\mlastyle@slash - }} + \catcode`/=13\let/=\mlastyle@slash}} % \end{macrocode} -% We're done formatting! % \begin{macrocode} \fi % \ifmlastyle@format % \end{macrocode} -% \subsection{Works Cited} +% \subsection{Style} % \begin{macro}{\cite} +% \begin{macro}{\citeN} +% ^^A\begin{macro}{\citepage} +% ^^A\begin{macro}{\citequote} % The following macros, combined with \file{mlastyle.bst}, provide % for a bibliography in MLA style. Note that the definition of |\cite|, % |\citeN|, etc.\ vary depending on the options passed to % \package{mlastyle}. % % \begin{macro}{\mlastyle@intcite} -% Since the original |\cite| is needed after it is overridden, it is stored +% The original |\cite| is stored % in |\mlastyle@intcite|. % \begin{macrocode} \let\mlastyle@intcite\cite % \end{macrocode} % \end{macro} % \begin{macro}{\mlastyle@relax} -% This macro does nothing. Depending on the options, ither |\citeC| or +% This macro does nothing. Depending on the options, either |\citeC| or % |\citeM| and its ilk will utilize it. % \begin{macrocode} \newcommand{\mlastyle@relax}[2][]{} @@ -663,11 +798,15 @@ % \begin{macrocode} \ifmlastyle@style \def\@cite#1#2{(#1\if@tempswa{} #2\fi)} - \def\cite{\def\@cite##1##2{(##1\if@tempswa{} ##2\fi)}\mlastyle@intcite} - \def\citeN{\def\@cite##1##2{##1\if@tempswa{} ##2\fi}\mlastyle@intcite} - \def\citeM{\def\@cite##1##2{ (##1\if@tempswa{} ##2\fi)}\mlastyle@intcite} + \def\cite{\def\@cite##1##2{(##1\if@tempswa{} + ##2\fi)}\mlastyle@intcite} + \def\citeN{\def\@cite##1##2{##1\if@tempswa{} + ##2\fi}\mlastyle@intcite} + \def\citeM{\def\@cite##1##2{ (##1\if@tempswa{} + ##2\fi)}\mlastyle@intcite} \def\citepage{\def\@cite##1##2{\if@tempswa(##2)\fi}\mlastyle@intcite} - \def\citepageM{\def\@cite##1##2{\if@tempswa{} (##2)\fi}\mlastyle@intcite} + \def\citepageM{\def\@cite##1##2{\if@tempswa{} + (##2)\fi}\mlastyle@intcite} \def\citeindirect{\def\@cite##1##2% {(qtd. in ##1\if@tempswa{} ##2\fi)}\mlastyle@intcite} \def\citeindirectM{\def\@cite##1##2% @@ -720,7 +859,7 @@ \itemindent-\leftmargin\def\@biblabel##1{}} % \end{macrocode} % \end{macro} -% Title the either the bibliography or the references ``Works Cited,'' +% Title either the bibliography or the references ``Works Cited,'' % depending on the document class. % \begin{macrocode} \@ifundefined{chapter} @@ -758,6 +897,10 @@ \fi % \end{macrocode} % \end{macro} +% +% ^^A\end{macro} +% ^^A\end{macro} +% \end{macro} % \end{macro} % \iffalse % -- 2.30.2