From e757e4bfb6f6d3fd6faf03ebe3a334838c29c9f6 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 1 Sep 2013 22:41:26 +0000 Subject: idxcmds (1sep13) git-svn-id: svn://tug.org/texlive/trunk@31557 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/idxcmds/README | 32 ++ Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.pdf | Bin 0 -> 114643 bytes Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.tex | 373 +++++++++++++++++++++ 3 files changed, 405 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/idxcmds/README create mode 100644 Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.pdf create mode 100644 Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.tex (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/idxcmds/README b/Master/texmf-dist/doc/latex/idxcmds/README new file mode 100644 index 00000000000..8f9f5312a0f --- /dev/null +++ b/Master/texmf-dist/doc/latex/idxcmds/README @@ -0,0 +1,32 @@ +-------------------------------------------------------------------------- +the IDXCMDS package v0.2b 2013/08/31 + + create commands for adding formatted index entries + +-------------------------------------------------------------------------- +Clemens Niederberger +Web: https://bitbucket.org/cgnieder/idxcmds/ +E-Mail: contact@mychemistry.eu +-------------------------------------------------------------------------- +Copyright 2012-2013 Clemens Niederberger + +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 Clemens Niederberger. +-------------------------------------------------------------------------- +The idxcmds package consists of the files + - idxcmds.sty + - idxcmds_en.tex, idxcmds_en.pdf + - README +-------------------------------------------------------------------------- +If you have any ideas, questions, suggestions or bugs to report, please +feel free to contact me. +-------------------------------------------------------------------------- diff --git a/Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.pdf b/Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.pdf new file mode 100644 index 00000000000..4d50199850a Binary files /dev/null and b/Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.pdf differ diff --git a/Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.tex b/Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.tex new file mode 100644 index 00000000000..a91c7b8e1f5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/idxcmds/idxcmds_en.tex @@ -0,0 +1,373 @@ +% arara: lualatex +% !arara: biber +% arara: lualatex +% !arara: lualatex +% -------------------------------------------------------------------------- +% the IDXCMDS package +% +% create commands for adding formatted index entries +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% Web: https://bitbucket.org/cgnieder/idxcmds/ +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2012-2013 Clemens Niederberger +% +% 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 Clemens Niederberger. +% -------------------------------------------------------------------------- +% The idxcmds package consists of the files +% - idxcmds.sty +% - idxcmds_en.tex, idxcmds_en.pdf +% - README +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +% in order to compile this documentation you need the document class +% `cnpkgdoc' which you can get here: +% https://bitbucket.org/cgnieder/cnpkgdoc/ +% +\PassOptionsToPackage{supstfm=libertinesups}{superiors} +\documentclass{cnpkgdoc} +\docsetup{ + pkg = idxcmds , + subtitle = create commands for adding formatted index entries, + language = en , + code-box = { + backgroundcolor = gray!5!white , + skipbelow = .6\baselineskip plus .5ex minus .5ex , + skipabove = .6\baselineskip plus .5ex minus .5ex , + roundcorner = 3pt , + } , + gobble = 1 +} + +\addcmds{acr,environ,file,hsnbg,KOMAScript,name,test} +\addcmds{ + @ifstar, + cmd,cmd@base,cmd@idx,cmd@nostar,cmd@star, + indexentry +} + +\cnpkgusecolorscheme{friendly} +\usepackage[oldstyle,proportional]{libertine} +\usepackage[libertine]{newtxmath} +\usepackage{libertinehologopatch} +\setmonofont[Scale=MatchLowercase]{Bitstream Vera Sans Mono} + +\usepackage[english]{selnolig} + +\renewcommand*\othersectionlevelsformat[3]{% + \textcolor{main}{#3\autodot}\enskip} +\renewcommand*\partformat{% + \textcolor{main}{\partname~\thepart\autodot}} +\usepackage{fnpct} +\pagestyle{headings} + +\usepackage{imakeidx} +\usepackage{filecontents} +\begin{filecontents*}{\jobname.ist} + heading_prefix "{\\bfseries " + heading_suffix "\\hfil}\\nopagebreak\n" + headings_flag 1 + delim_0 "\\dotfill\\hyperpage{" + delim_1 "\\dotfill\\hyperpage{" + delim_2 "\\dotfill\\hyperpage{" + delim_r "}\\textendash\\hyperpage{" + delim_t "}" + suffix_2p "\\nohyperpage{\\,f.}" + suffix_3p "\\nohyperpage{\\,ff.}" +\end{filecontents*} +\indexsetup{othercode=\footnotesize,noclearpage} +\makeindex[options={-s \jobname.ist},intoc,columns=3] +\makeindex[name=examples,title=Example Index,intoc,columns=3] + +\usepackage[backend=biber,style=alphabetic]{biblatex} +\addbibresource{\jobname.bib} +\begin{filecontents}{\jobname.bib} +@package{pkg:etoolbox, + title = {\paket*{etoolbox}}, + author = {Philipp Lehman}, + date = {2011-01-21}, + version = {2.1}, + url = {http://mirror.ctan.org/macros/latex/contrib/etoolbox} +} +@package{pkg:imakeidx, + title = {\paket*{imakeidx}}, + author = {Claudio Beccari and Enrico Gregorio}, + date = {2013-03-26}, + version = {1.3}, + url = {http://mirror.ctan.org/macros/latex/contrib/imakeidx} +} +@package{pkg:ltxcmds, + title = {\paket*{ltxcmds}}, + author = {Heiko Oberdiek}, + date = {2011-11-09}, + version = {1.22}, + url = {http://mirror.ctan.org/tex-archive/macros/latex/contrib/oberdiek/} +} +@package{pkg:pgfopts, + title = {\paket*{pgfopts}}, + author = {Joseph Wright}, + date = {2011-06-02}, + version = {2.1}, + url = {http://mirror.ctan.org/macros/latex/contrib/pgfopts} +} +\end{filecontents} + +\newidxcmd\acr{\textsc{#1}} +\newidxcmd[{\index[examples]}]\environ{\texttt{#1}}[ (Environment)] +\newidxcmd\name{\textsf{#1}} +\newsubmainidxcmd\file{\textsf{#1}} +\newsubidxcmd\test{Test}{\textcolor{red}{#1}} +\newsubidxcmd*\hsnbg{\name[Heisenberg]{Werner Heisenberg}}{#1} + +\begin{document} + +\section{Licence and Requirements}\label{sec:license}\secidx{Licence} +Permission is granted to copy, distribute and/or modify this software under +the terms of the \LaTeX{} Project Public License, version 1.3 or later +(\url{http://www.latex-project.org/lppl.txt}). The package has the status +``maintained.'' + +\idxcmds loads and needs the the packages \paket{etoolbox}~\cite{pkg:etoolbox}, +\paket{pgfopts}~\cite{pkg:pgfopts} and \paket{ltxcmds}~\cite{pkg:ltxcmds}. +\secidx*{Licence} + +\section{Motivation}\secidx{Motivation} +When working on a larger document and designing and writing the macros for +various bits and pieces I was going to use I found myself repeatedly writing +the same kind of macros again and again that had some kind of semantic +meaning, maybe some markup definitions that also created an index entry and +had a star form for omitting the index entry. They all had more or less the +following structure: + +\begin{beispiel}[code only] + \makeatletter + \newcommand*\cmd{\@ifstar\cmd@star\cmd@nostar} + \newcommand*\cmd@star[1]{\cmd@base{#1}} + \newcommand*\cmd@nostar[1]{\cmd@base{#1}\cmd@idx{#1}} + \newcommand*\cmd@base[1]{\textit{#1}} + \newcommand*\cmd@idx[1]{\index{#1@\cmd@base{#1}}} + \makeatother +\end{beispiel} + +After having copied and pasted this code for the fourth time I thought: you +should have a command that does this for you. That was when \cmd{newidxcmd} +was born. This command soon enough got some extensions, \eg, giving +the commands thus defined an optional argument that allowed specifying the +sorting. It wasn't long before I realized that I might want to use this +\cmd{newidxcmd} again in other documents which was when I wrote the first +draft of this package. + +I added other commands, \cmd{newsubmainidxcmd} and \cmd{newsubidxcmd}, which I +didn't (and still don't) really use or need but of which I thought they could +be useful for others, and here we are. +\secidx*{Motivation} + +\section{Usage}\label{sec:usage}\secidx{Usage} +\subsection{Available Commands}\secidx[Available Commands]{Usage} +\idxcmds provides these commands: +\begin{beschreibung} + \Befehl{newidxcmd}[]{\cmd*{cmd}}\ma{}\oa{}\newline + Defines a command \cmd*{cmd} that formats its argument according to + \code{} and creates an index entry with \code{} + that gets \code{} appended. Refer to the argument of \cmd*{cmd} + in \code{} with \code{\#1}. + + Also defines a command \cmd*{cmdidx} that allows to only create an index + entry. See section~\ref{ssec:command:usage:newidxcmd} for examples and + further description of its functionality. Default for \code{} is + \cmd{index}. + \Befehl{newsubidxcmd}*[]{\cmd*{cmd}}\ma{
}\ma{}\oa{}\newline + Defines a command \cmd*{cmd} that formats its argument according to + \code{} and creates an index sub-entry to \code{
} with \code{} that gets \code{} + appended. Refer to the argument of \cmd*{cmd} in \code{} + with \code{\#1}. + + Also defines a command \cmd*{cmdidx} that allows to only create an index + entry. See section~\ref{ssec:command:usage:newsubidxcmd} for further + description of its functionality. Default for \code{} is + \cmd{index}. + \Befehl{newsubmainidxcmd}[]{\cmd*{cmd}}\ma{}\oa{}\newline + Defines a command \cmd*{cmd} that formats its argument according to + \code{} and creates an index sub-entry to a main entry with + \code{} that gets \code{} appended. Refer to + the argument of \cmd*{cmd} in \code{} with \code{\#1}. + + Also defines a command \cmd*{cmdidx} that allows to only create an index + entry. The main entry is specified at use time. See + section~\ref{ssec:command:usage:newsubmainidxcmd} for examples and further + description of its functionality. Default for \code{} is + \cmd{index}. +\end{beschreibung} + +The commands \cmd*{cmd} defined this way are robust but their formatting +argument is not placed in a group. Keep this in mind when you use +\cmd*{bfseries} or something in a definition. \cmd*{cmd} will be defined +using \paket{etoolbox}' \cmd{newrobustcmd} which means an error will be thrown +if \cmd*{cmd} is already defined. + +Of course these commands cannot cover all possible use cases for index entries +but that is not the intention of this package, anyway. + +\subsection{Command Usage}\label{ssec:command:usage}\secidx[Command Usage]{Usage} +\subsubsection{\cmd*{newidxcmd}}\label{ssec:command:usage:newidxcmd} +The command \cmd{newidxcmd}{\cmd*{cmd}}\ma{} will define a +new command \cmd*{cmd} with the following syntax: +\begin{beschreibung} + \Befehl{cmd}*{}\newline + format \code{} according to specifications, no index entry. + \Befehl{cmd}[]{}\oa{}\newline + format \code{} according to specifications, add formatted index + entry, sorted according to \code{} or, if the optional argument + is left out, sorted according to \code{}. \code{} is added to + the index entry if the trailing optional argument is used (this can be + useful for instance for getting formatted page numbers). + \Befehl{cmdidx}[]{}\oa{}\newline + add formatted index entry, sorted according to \code{} or, if the + optional argument is left out, sorted according to \code{}. + \code{} is added to the index entry if the trailing optional argument + is used. +\end{beschreibung} + +Let's see an example: +\begin{beispiel} + % in the preamble, probably: + % \newidxcmd{\acr}{\textsc{#1}} + % \newidxcmd[{\index[examples]}]{\environ}{\texttt{#1}}[ (Environment)] + % \newidxcmd{\name}{\textsf{#1}} + \acr{cd}, \acr{id} + + \environ{center}, \environ{flushleft} + + \name*{Albert Einstein}, \name[Heisenberg]{Werner Heisenberg} +\end{beispiel} +You will find these examples in the index or the examples index, +respectively. The second set of examples shows the purpose of the first +optional argument: if you have several indexes --~like this documentation has +for demonstration purposes~-- you might need to specify the index command +used\footnote{This document uses \paket*{imakeidx}~\cite{pkg:imakeidx} for + this purpose.}. If you want to prove if the example worked: \name*{Albert + Einstein} should not be found in the index and \name*{Werner Heisenberg} +should be sorted under \emph{Heisenberg}. Both \environ*{center} and +\environ*{flushleft} ahould be found in the examples index. + +Now let's disect the example a bit. The uses of \cmd*{acr}{cd}, +\cmd*{name}*{Albert Einstein} and \cmd*{environ}{center} will essentially +expand to +\begin{beispiel}[code only] + % \acr{cd} => + \textsc{cd}\index{cd@\textsc{cd}} + % and in \jobname.idx => + \indexentry{cd@\textsc {cd}}{3} + + % \name*{Albert Einstein} => + \textsf{Albert Einstein} + + % \environ{center} => + \texttt{center}\index[examples]{center@\texttt{center} (Environment)} + % and in examples.idx => + \indexentry{center@\texttt {center} (Environment)}{3} +\end{beispiel} + +\subsubsection{\cmd*{newsubidxcmd}}\label{ssec:command:usage:newsubidxcmd} +The command \cmd{newsubidxcmd}*{\cmd*{cmd}}\ma{
}\ma{} will define a new command \cmd*{cmd} with the same syntax as +\cmd{newidxcmd} does. However, \cmd{newsubidxcmd} has an additional argument +that specifies the main index entry this group of sub entries belongs to. For +the unstarred variant this argument can be some arbitrary main entry. For the +starred variant it demands a command plus argument defined by \cmd{newidxcmd} +as argument. + +\begin{beispiel} + % preamble: + % \newsubidxcmd{\test}{Test}{\textcolor{red}{#1}} + % \newsubidxcmd*{\hsnbg}{\name[Heisenberg]{Werner Heisenberg}}{#1} + \name[Heisenberg]{Werner Heisenberg} was born in + \hsnbg[Wuerzburg]{W\"urzburg (Germany)}. He worked as a + professor in \hsnbg{Leipzig (Germany)}. And this is a + \test{test}. +\end{beispiel} + +\subsubsection{\cmd*{newsubmainidxcmd}}\label{ssec:command:usage:newsubmainidxcmd} +The command \cmd{newsubmainidxcmd}{\cmd*{cmd}}\ma{} will define +a new command \cmd*{cmd} similar to \cmd{newsubidxcmd} but where the main +index entry is specified for every use case in the running text. \cmd*{cmd} +will have the following syntax: +\begin{beschreibung} + \Befehl{cmd}*{}\newline + format \code{} according to specifications, no index entry. + \Befehl{cmd}[]{}\ma{
}\oa{}\newline + format \code{} according to specifications, add formatted index + sub-entry to the main index entry \code{
}, sorted according to + \code{} or, if the optional argument is left out, sorted + according to \code{}. \code{} is added to the index entry if + the trailing optional argument is used (this can be useful for instance + for getting formatted page numbers). + \Befehl{cmdidx}[]{}\ma{
}\oa{}\newline + add formatted index sub-entry to the main index entry \code{
}, + sorted according to \code{} or, if the optional argument is left + out, sorted according to \code{}. \code{} is added to the + index entry if the trailing optional argument is used. +\end{beschreibung} + +\begin{beispiel} + % in the preamble, probably: + % \newsubmainidxcmd{\file}{\textsf{#1}} + \file{article}{classes} is a standard \LaTeX{} class. + \file{scrartcl}{KOMA-Script@\KOMAScript} is part of the \KOMAScript{} bundle. + \file*{test} is a dummy. +\end{beispiel} + +\subsection{Options}\secidx[Options]{Usage} +\idxcmds has the following options -- either setable as package option or with +the setup command \cmd{setidxcmds}{} which takes a comma separated +list of options: +\begin{beschreibung} + \Option{sort-sep}{}\Default{@} + set makeindex symbol to separate the index into sorting and typesetting + part as specified in the index style file. + \Option{sub-sep}{}\Default{!} + set makeindex symbol to add a sub entry as specified in the index style + file. + \Option{idx-cmd}{}\Default{\cmd*{index}} + \sinceversion{0.2b}The default indexing command that is used by \idxcmds. +\end{beschreibung} +\secidx*{Usage} + +\printbibliography + +\section{Implementation}\secidx{Implementation} +In the following code the lines 1--32 have been omitted. They only repeat the +license statement which has already been mentioned in +section~\ref{sec:license}. + +\implementation[linerange={33-1000},firstnumber=33] +\secidx*{Implementation} + +% \begingroup +\indexprologue{\noindent + This index has some peculiar entries in addition to the ones you would + normally expect. But actually they are the corresponding entries to the + examples shown in section~\ref{sec:usage}.% +} +\printindex +% \def\clearpage{\vskip\baselineskip} +\clearpage +\printindex[examples] +% \endgroup + +\end{document} -- cgit v1.2.3