From 7d90c1647c043c87a58609fbc1f9a5fe179dd916 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 14 May 2010 18:38:09 +0000 Subject: underscore own pkg + doc (12may10) git-svn-id: svn://tug.org/texlive/trunk@18261 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/underscore/miscdoc.sty | 115 +++++++++++++ .../texmf-dist/doc/latex/underscore/underscore.pdf | Bin 0 -> 252691 bytes .../texmf-dist/doc/latex/underscore/underscore.tex | 184 +++++++++++++++++++++ 3 files changed, 299 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/underscore/miscdoc.sty create mode 100644 Master/texmf-dist/doc/latex/underscore/underscore.pdf create mode 100644 Master/texmf-dist/doc/latex/underscore/underscore.tex (limited to 'Master/texmf-dist/doc/latex/underscore') diff --git a/Master/texmf-dist/doc/latex/underscore/miscdoc.sty b/Master/texmf-dist/doc/latex/underscore/miscdoc.sty new file mode 100644 index 00000000000..da1f2a5fdba --- /dev/null +++ b/Master/texmf-dist/doc/latex/underscore/miscdoc.sty @@ -0,0 +1,115 @@ +\ProvidesPackage{miscdoc}[2010/01/20 v1.2 documentation macros misc latex pkgs] + +% miscdoc.sty +% Copyright 2010 Robin Fairbairns +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Robin Fairbairns. +% +% This work consists of the file miscdoc.sty (only) + +\setcounter{errorcontextlines}{1274} + +% The package arose from a small exercise to document packages whose +% previous documentation consisted solely of comments in the package files. +% The macros here defined are lifted from the author's faq.sty +% (written for the UK TeX FAQ, CTAN:help/uk-tex-faq) or are inspired +% by others' work (credited where the author is known) ... except +% where they came as a flash of inspiration while actually writing the +% documentation. + +% this option suggested by Heiko Oberdiek, 2010-01-29 +\DeclareOption{hyper}{% + \AtEndOfPackage{% + \RequirePackage[pdfusetitle]{hyperref} + \RequirePackage{bookmark} + \bookmarksetup{numbered,open,openlevel=1} + } +} +\ProcessOptions\relax + +% note: T1 encoding assumed +\usepackage{lmodern} +\usepackage[T1]{fontenc} +\usepackage{booktabs} + +% from faq.sty +\newcommand\cs[1]{\texttt{\char`\\#1}} +\let\csx\cs +\def\bsbs{\cs{\char`\\}} + +% \cmdinvoke\cs +% \cs typeset as above +% may consist of optional or mandatory arguments; +% +% the `arguments' are simply typesett \texttt, as yet -- if something +% fancier is needed, there's a bunch of code needs rewriting here... +\DeclareRobustCommand\cmdinvoke{\@ifstar + {\let\@tempa\emph\@scmdinvoke}% + {\let\@tempa\relax\@scmdinvoke}% +} +\def\@scmdinvoke#1{\texttt{\symbol{92}#1}% + \futurelet\@let@token\@cmdinvoke +} +\def\@cmdinvoke{\ifx\@let@token\bgroup + \let\@tempb\@cmdinvoke@lbrace + \else + \ifx\@let@token[% ] + \let\@tempb\@cmdinvoke@lbrack + \else + \ifx\@let@token(% ) + \let\@tempb\@cmdinvoke@lparen + \else + \let\@tempb\@empty + \fi + \fi + \fi + \@tempb +} +\def\@cmdinvoke@lbrace#1{\penalty0\hskip0pt\relax + \texttt{\symbol{123}\@tempa{#1}\symbol{125}}% + \futurelet\@let@token\@cmdinvoke +} +\def\@cmdinvoke@lbrack[#1]{\penalty-150\hskip0pt\relax + \texttt{[\@tempa{#1}]}% + \futurelet\@let@token\@cmdinvoke +} +\def\@cmdinvoke@lparen(#1){\penalty-150\hskip0pt\relax + \texttt{(\@tempa{#1})}% + \futurelet\@let@token\@cmdinvoke +} +% and extension -- versions that take a single extra (delimiter) +% argument, such as \delcmdinvoke{lscrunge}( ... awful syntax, but... +\DeclareRobustCommand\delcmdinvoke{\@ifstar + {\let\@tempa\emph\@sdelcmdinvoke}% + {\let\@tempa\relax\@sdelcmdinvoke}% +} +\def\@sdelcmdinvoke#1#2{\texttt{\symbol{92}#1#2}% + \futurelet\@let@token\@cmdinvoke +} + +% sui generis +\newcommand\newitem{\par\addvspace{1ex}\noindent} + +% inspired by doc.sty in latex distribution +\newcommand\meta[1]{\ensuremath{\langle}\emph{#1}\ensuremath{\rangle}} + +% meaningful names, as in faq.sty +\newcommand\environment[1]{\texttt{#1}} +\newcommand\pkgoption[1]{\texttt{#1}} +\newcommand\extension[1]{\texttt{.#1}} +\newcommand\Package[1]{\textsf{#1}} +\def\option{\@ifnextchar[\@optionb\@option}% ] +\def\@optionb[#1]{{\normalfont\ttfamily[#1]}} +\def\@option#1{\texttt{#1}} + +\let\FontName\textsf \ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/underscore/underscore.pdf b/Master/texmf-dist/doc/latex/underscore/underscore.pdf new file mode 100644 index 00000000000..74da138d5d4 Binary files /dev/null and b/Master/texmf-dist/doc/latex/underscore/underscore.pdf differ diff --git a/Master/texmf-dist/doc/latex/underscore/underscore.tex b/Master/texmf-dist/doc/latex/underscore/underscore.tex new file mode 100644 index 00000000000..27331aba457 --- /dev/null +++ b/Master/texmf-dist/doc/latex/underscore/underscore.tex @@ -0,0 +1,184 @@ +\documentclass[a4paper]{article} +\usepackage[a4paper]{geometry} +\usepackage{miscdoc} +\usepackage[scaled=0.85]{luximono} +\usepackage{underscore} +\begin{document} +\title{The \Package{underscore} package} +\author{Donald Arseneau\thanks{Documentation file assembled by Robin + Fairbairns}} +\date{13 September 2006, version 1.0} +\maketitle + +\section*{Features} + +The package alters the command \cs{_} (which normally prints +an underscore character or facsimile) so that the hyphenation of +constituent words is not affected, and hyphenation is permitted after +the underscore. For example, +\begin{quote} + \texttt{compound\cs{_}fracture} +\end{quote} +hyphenates as +\begin{quote} + \texttt{com- pound\cs{_}- frac- ture} +\end{quote} +If you prefer the underscore to break without a hyphen (but still with +the same rules as for explicit hyphen-breaks) then use the +\option[nohyphen] package option. + +A simple ``\texttt{_}'' acts just like ``\cs{_}'' in text +mode, but makes a subscript in maths mode, so +\begin{quote} + \ttfamily activation_energy \$E_a\$ +\end{quote} +is printed as +\begin{quote} + activation_energy $E_a$ +\end{quote} + +Both forms use an underscore character if the font encoding contains +one (e.g., with \cmdinvoke{usepackage}[T1]{fontenc} or typewriter +fonts in any encoding), but they use a rule if there is no proper +character (just as unmodified \LaTeX{} does). + +\section*{Deficiencies} + +The skips and penalties ruin any kerning with the underscore character +(when a character is used). However, there doesn't seem to be much, if +any, such kerning in the EC fonts, and there is never any kerning with +a rule. + +You must avoid ``\texttt{_}'' in file names and in cite or ref tags, or you must +use the \Package{babel} package, with its active-character controls, +or you must give the \option[strings] option, which attempts to +redefine several commands (and may not work perfectly). Even without +the \option[strings] option or \Package{babel}, you can use occasional +underscores like: ``\cmdinvoke{include}{file\string\string_name}''. + +\subsection*{Option \protect\option[strings]} + +The default operation is quite simple and needs no customization; but +you must avoid using ``\texttt{_}'' in any place where LaTeX uses an argument +as a string of characters for some control function or as a name. +These include the tags for \cs{cite} and \cs{ref}, file names for \cs{input}, +\cs{include}, and \cs{includegraphics}, environment names, counter names, +and placement parameters (like \option[t]). The problem with these contexts +is that they are `moving arguments' but LaTeX does not `switch on' the +``\cs{protect} mechanism'' for them. + +If you need to use the underscore character in these places, the +package option \option[strings] is provided to redefine commands that +take such a string argument so that protection is applied (with +\cs{protect} made to be \cs{string}). The list of commands this +provision affects is given in \cs{UnderscoreCommands}, with \cs{do} +before each one; plus several others covering \cs{input}, +\cs{includegraphics}, \cs{cite}, \cs{ref}, and their variants. Not +included are many commands regarding font names, anything with counter +names, environment names, page styles, and versions of \cs{ref} and +\cs{cite} defined by external packages (e.g., \cs{vref} and +\cs{citeyear}). + +You can add to the list of supported commands by defining \cs{UnderscoreCommands} +before loading this package; e.g. +\begin{quote} +\begin{verbatim} +\usepackage{chicago} +\newcommand{\UnderscoreCommands}{% (\cite already done) + \do\citeNP \do\citeA \do\citeANP \do\citeN \do\shortcite + \do\shortciteNP \do\shortciteA \do\shortciteANP \do\shortciteN + \do\citeyear \do\citeyearNP +} +\usepackage[strings]{underscore} +\end{verbatim} +\end{quote} + +Not all commands can be supported this way! Only commands that take a +string argument \emph{first} can be protected. One optional argument before +the string argument is also permitted, as exemplified by \cs{cite}: both +\cmdinvoke{cite}{tags} and \cmdinvoke{cite}[text]{tags} are allowed. +A command like \cs{@addtoreset} which takes two counter names as +arguments could not be protected by listing it in \cs{UnderscoreCommands}. + +\textit{When you use the \option[strings] option, you must load this + package \textbf{last}} (or nearly last). +There are two reasons for this requirement: +\begin{enumerate} +\item The redefinitions done for protection must come after other + packages define their customized versions of those commands. +\item The \option[strings] option requires the ``\texttt{_}'' character to be + activated immediately in order for the cite and ref tags to be read + properly from the \texttt{.aux} file as plain strings, and this + catcode setting might disrupt other packages. +\end{enumerate} + +The \Package{babel} package implements a protection mechanism for many +commands, and will be a complete fix for most documents without the +\option[strings] option. Many add-on packages are compatible with +\Package{babel}, so they will get the strings protection also. +However, there are several commands that are not covered by +\Package{babel}, but can easily be supported by \option[strings] and +\cs{UnderscoreCommands} mechanism. Beware the potential conflict +using both \option[strings] and \Package{babel} (though none have been +reported, yet); load babel last. + +\subsection*{Implementation notes} + +The first setting of ``\texttt{_}'' to be an active character is +performed in a local group so as to not interfere with other packages. +The catcode setting is repeated with ``\cs{AtBeginDocument}'' so the +definition is in effect for the text. However, the catcode setting is +repeated immediately when the \option[strings] option is detected. + +The definition of the active ``\texttt{_}'' is essentially: +\begin{quote} + \cs{ifmmode} \cs{sb} \cs{else} \cs{BreakableUnderscore} \cs{fi} +\end{quote} +where \cs{sb} retains the normal subscript meaning of \texttt{_} and where +\cs{BreakableUnderscore} is essentially \cs{_}. The rest of the definition +handles the \cs{protect}ion without causing \cs{relax} to be inserted before +the character. + +\cs{BreakableUnderscore} uses \cs{nobreak}\cs{hskip}\cs{z@skip} to separate the +underscore from surrounding words, thus allowing \TeX{} to hyphenate them, +but preventing free breaks around the underscore. Next, it checks the +current font family, and uses the underscore character from tt fonts or +otherwise \cs{textunderscore} (which is a character or rule depending on +the font encoding). After the underscore, it inserts a discretionary +hyphenation point as \cs{usc@dischyph}, which is usually just \cs{-} +except that it still works in the tabbing environment; if the +\option[nohyphen] option is in effect, the empty discretionary +\cmdinvoke{discretionary}{}{}{} is used instead. After +that, another piece of non-breaking interword glue is inserted. + +Ordinarily, the comparison \cs{ifx}\cs{f@family}\cs{ttdefault} will fail +because \cs{ttdefault} is `long' whereas \cs{f@family} is +not\footnote{the package author says ``boooo hisss'' about this\dots}, +but \cs{ttdefault} is redefined to be non-long \cs{AtBeginDocument}. + +The \cs{_} command is then defined to use \cs{BreakableUnderscore}. + +If the \option[strings] option has not been given, that is all! + +Under the \option[strings] option, the list of special commands is processed to: +\begin{itemize} +\item retain the original command as \cs{US_}\meta{command} (e.g., \cs{US_ref}) +\item redefine the command as \cs{US@prot}\cs{US_command} for ordinary + commands (\cs{US@prot}\cs{US_ref}) or as + \cs{US@protopt}\cs{US_command} when an optional argument is possible + (e.g., \cs{US@protopt}\cs{US_bibitem}). +\item self-protecting commands (e.g., \cs{cite}) retain their + self-protection. +\end{itemize} +Diagnosing the state of the pre-existing command is done by painful +contortions involving \cs{meaning}. + +\cs{US@prot} and \cs{US@protopt} read the argument, process it with +\cs{protect} enabled, then invoke the saved \cs{US_command}. + +\end{document} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: -- cgit v1.2.3