path: root/macros/latex/contrib/xltxtra/xltxtra.dtx

% \iffalse
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% THE XLTXTRA PACKAGE
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Copyright (C) 2006-2018 by Will Robertson <wspr81@gmail.com>
%%
%% Distributable under the LaTeX Project Public License,
%% version 1.3c or higher (your choice). The latest version of
%% this license is at: http://www.latex-project.org/lppl.txt
%%
%% This work is "maintained" (as per LPPL maintenance status)
%% by Will Robertson.
%%
%% This work consists of the files xltxtra.dtx and xltxtra.ins,
%%           and the derived files xltxtra.sty and xltxtra.pdf.
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%<*driver>
\documentclass{ltxdoc}

\makeatletter

\def\@dotsep{1000}
\setcounter{tocdepth}{2}

\setcounter{IndexColumns}{2}
\renewenvironment{theglossary}
  {\small\list{}{}
     \item\relax
     \glossary@prologue\GlossaryParms
     \let\item\@idxitem \ignorespaces
     \def\pfill{\hspace*{\fill}}}
  {\endlist}

\usepackage{array,booktabs,calc,color,enumitem,fancyvrb,graphicx,ifthen,longtable,refstyle,varioref,xltxtra}
\usepackage[rm]{titlesec}
\setmainfont{texgyrepagella}[
  Extension = .otf ,
  UprightFont = *-regular ,
  ItalicFont = *-italic ,
  BoldFont = *-bold ,
  BoldItalicFont = *-bolditalic ,
]
\setsansfont{texgyreheros}[
  Scale=MatchLowercase ,
  Extension = .otf ,
  UprightFont = *-regular ,
  ItalicFont = *-italic ,
  BoldFont = *-bold ,
  BoldItalicFont = *-bolditalic ,
]
\setmonofont{lmmono10}[
  Extension = .otf ,
  UprightFont = *-regular ,
  ItalicFont = *-italic ,
]

\linespread{1.05}      % A bit more space between lines
\frenchspacing         % Remove space after punctuation

\setlogokern{Xe}{-0.061em}
\setlogokern{eL}{-0.057em}
\setlogokern{La}{-0.28em}
\setlogokern{aT}{-0.10em}
\setlogokern{Te}{-0.0575em}
\setlogokern{eX}{-0.072em}
\setlogokern{eT}{-0.056em}
\setlogokern{X2}{0.1667em}
\setlogodrop{0.153em}
\setLaTeXa{\scshape a}
\setLaTeXee{\mbox{\fontspec{Times}\itshape ε}}
\def\eTeX{{\fontspec{Times}\textit{ε}{}}-\TeX} % The eTeX logo is not (yet) covered by metalogo

\definecolor{niceblue}{rgb}{0.2,0.4,0.6}
\def\theCodelineNo{\textcolor{niceblue}{\sffamily\tiny\arabic{CodelineNo}}}

\newenvironment{example}
  {\VerbatimEnvironment
   \begin{trivlist}\item[]
   \begin{minipage}{\linewidth}
   \par\noindent\hrulefill\par
   \begin{VerbatimOut}[gobble=4]{\examplefilename}}
  {\end{VerbatimOut}\relax
   \begingroup
     \color{niceblue}
     \typesetexample
   \endgroup\par\noindent\hrulefill\par
   \end{minipage}\end{trivlist}}

\let\examplesize\normalsize
\let\auxwidth\relax

\newlength\examplewidth\newlength\verbatimwidth
\newlength\exoutdent   \newlength\exverbgap
\setlength\exverbgap{0em}
\setlength\exoutdent{-0\textwidth}
\newsavebox\verbatimbox
\edef\examplefilename{xltxtra.example}

\newcommand\typesetexample{\relax
   \begin{lrbox}{\verbatimbox}\relax
     \BVerbatimInput[fontsize=\small]{\examplefilename}\relax
   \end{lrbox}
   \begin{list}{}{\setlength\itemindent{0pt}
                  \setlength\leftmargin\exoutdent
                  \setlength\rightmargin{0pt}}\item
   \ifx\auxwidth\relax
     \setlength\verbatimwidth{\wd\verbatimbox}\relax
   \else
     \setlength\verbatimwidth{\auxwidth}\relax
   \fi
   \begin{minipage}[c]{\textwidth-\exoutdent-\verbatimwidth-\exverbgap}
     \catcode`\%=14\centering\examplesize\input\examplefilename\relax
   \end{minipage}\hfill
   \begin{minipage}[c]{\verbatimwidth}
     \usebox\verbatimbox
   \end{minipage}
   \end{list}
   \global\let\examplesize\normalsize}

\newcommand*\setexsize[1]{\let\examplesize#1}
\newcommand*\setverbwidth[1]{\def\auxwidth{#1}}

\newcommand*\name[1]{{#1}}
\newcommand*\pkg[1]{\texttt{#1}}
\newcommand*\pkgopt[1]{\texttt{[#1]} package option}

\newcommand*\acro[1]{\textsc{\MakeLowercase{#1}}}

\newcommand*\note[1]{\unskip\footnote{#1}}

\let\latin\textit
\def\eg{\latin{e.g.}}
\def\Eg{\latin{E.g.}}
\def\ie{\latin{i.e.}}
\def\etc{\@ifnextchar.{\latin{etc}}{\latin{etc.}\@}}

\newcounter{argument}
\g@addto@macro\endmacro{\setcounter{argument}{0}}
\newcommand*\darg[1]{%
  \stepcounter{argument}%
  \noindent{\ttfamily\#\theargument}:~#1\par\nobreak}
\newcommand*\doarg[1]{%
  \stepcounter{argument}%
  \noindent{\ttfamily\makebox[0pt][r]{[}\#\theargument]}:~#1\par\nobreak}

\newcommand\unichar[2]{\textsc{\MakeLowercase{u+#1: #2}}}

\makeatother

\EnableCrossrefs
\CodelineIndex
\begin{document}
  \DocInput{xltxtra.dtx}
\end{document}
%</driver>
% \fi
%
% \errorcontextlines=999
% \makeatletter
%
% \GetFileInfo{xltxtra.sty}
%
% \title{The \pkg{xltxtra} package}
% \author{Will Robertson}
% \date{\filedate \qquad \fileversion}
%
% \maketitle
%
% \tableofcontents
%
% \section{Introduction}
%
% This document describes the \pkg{xltxtra} package.
% It implements some odds-and-ends features when using the \XeLaTeX\ format.
%
% \subsection{Usage}
% Easy: |\usepackage{xltxtra}|. This package automatically loads the following packages: \pkg{fontspec}, \pkg{realscripts}, \pkg{metalogo}.
%
% There are some package options to disable various functionality that could clash with other things:
% \begin{description}[font=\ttfamily]
% \item[no-sscript] Swaps the definitions of \cmd\textsubscript\ and \cmd\textsuperscript\ with their respective starred versions, as described in \secref{sscript}.
% \item[no-logos] Disables the redefinition of \cmd\TeX, etc. described in \secref{logos}, but \emph{does} still define the \cmd\XeTeX\ and \cmd\XeLaTeX\ logo commands.
% \end{description}
%
% \section{Features}
%
% \subsection{\cmd\textsuperscript\ and \cmd\textsubscript}
% \seclabel{sscript}
%
% This functionality is achieved through loading the \pkg{realscripts}
% package.
%
% These two macros have been redefined to take advantage, if possible, of actual superior or inferior glyphs in the main document font. This is very important for high-quality typesetting — compare this first example to the third; yes, they are the same font.
% \begin{quotation}\color{niceblue}
%	\fontspec{Skia}
%	  |\textsuperscript     | \textsuperscript{abcdefghijklmnopqrstuvwxyz1234567890}\par
%	  |\textsubscript       | \textsubscript{abcdefghijklmnopqrstuvwxyz1234567890}
% \end{quotation}
% But will fall back on `faked' ones if they don't exist:
% (this is {\fontspec{Didot} Didot})
% \begin{quotation}\color{niceblue}
%	\fontspec{Didot}
%	  |\textsuperscript     | \textsuperscript{abcdefghijklmnopqrstuvwxyz1234567890}\par
%	  |\textsubscript       | \textsubscript{abcdefghijklmnopqrstuvwxyz1234567890}
% \end{quotation}
% The original definitions are available in starred verions of the commands:
% \begin{quotation}\color{niceblue}
%	\fontspec{Skia}
%	  |\textsuperscript*    | \textsuperscript*{abcdefghijklmnopqrstuvwxyz1234567890}\par
%	  |\textsubscript*      | \textsubscript*{abcdefghijklmnopqrstuvwxyz1234567890}
% \end{quotation}
%
% The \pkgopt{no-sscript} will swap the definitions of the starred and non-starred versions of the commands described above if the new definitions are undesirable.
%
% The macros
% \cmd\realsubscript,
% \cmd\realsuperscript,
% \cmd\fakesubscript, and
% \cmd\fakesuperscript\
% may be used to access the `new' and `old' functionalities regardless of the \pkgopt{no-sscript}.
%
%
%
%
% \subsection{Logos}
% \seclabel{logos}
%
% This part of the package essentially exists to define the \cmd\XeTeX\ and \cmd\XeLaTeX\ logos,
% which need to be tuned according to the font that is used. Originally I had some hard-coded
% definitions in here, but Andrew Moschou’s |metalogo| package now provides a much more
% flexible and useful interface to a variety of \TeX-related logos.
%
% Here are some examples. The default:
% \begingroup
% \setlogokern{Xe}{default}
% \setlogokern{eL}{default}
% \setlogokern{La}{default}
% \setlogokern{aT}{default}
% \setlogokern{Te}{default}
% \setlogokern{eX}{default}
% \setlogokern{eT}{default}
% \setlogokern{X2}{default}
% \setlogodrop{default}
% \setLaTeXa{default}
% \setLaTeXee{default}
% \begin{example}
%   \TeX\ \XeTeX\ \LaTeX\ \XeLaTeX
% \end{example}
% \noindent Notice that it's a bit tight when not using Computer Modern, for which the logos were designed:
% \begin{example}
%   \usefont{OT1}{cmr}{m}{n}
%   \TeX\ \XeTeX\ \LaTeX\ \XeLaTeX
% \end{example}
% \endgroup
%
% These logos, ideally, should be hand-tuned for each font that they're used in. Please refer to the |metalogo| documentation for more information.
%
% The \pkgopt{no-logos} will not redefine \cmd\TeX\ or \cmd\LaTeX\ but will still define \cmd\XeTeX\ and \cmd\XeLaTeX.
%
%
% \subsection{Vulgar fractions}
% The \cmd\vfrac\ command for setting `vulgar' fractions based on AAT or OpenType font features. Not really recommended for many purposes, depending on your text, but it's a good example of how to program such things using \pkg{fontspec}.
% \begin{example}
%   \fontspec{LibreCaslonText-Regular.otf}
%   \vfrac{123}{456}
% \end{example}
% \noindent (This can also be achieved in regular \LaTeX\ with either the \pkg{nicefrac} or \pkg{xfrac} package.)
%
% Only use it when you know it will work; no warnings are given if the font doesn't support the necessary features.
%
% \subsection{Named glyphs}
% Along the way somewhere, \XeTeX\ added support for selecting glyphs from a TrueType-based OpenType font based on their internal glyph name. Jonathan Kew posted the following definition as a nice interface to it.
% \begin{example}
%   \fontspec{charis}
%   \namedglyph{yen}
%   \namedglyph{smile}
% \end{example}
%
% \subsection{The \cmd\showhyphens\ command}
% The default definition doesn't work in \XeTeX.
% A new version, written by Enrico Gregorio, is included in this package that \emph{does} work; note that the syntax now matches plain \TeX's original rather than the comma-list approach taken by an earlier version of this package.
% \showhyphens{discomedusoid discommodiousness}
%
% \newpage
% \part{The \textsf{xltxtra} package}
%\iffalse
%<*package>
%\fi
% This is the package implementation.
%
%    \begin{macrocode}
\ProvidesPackage{xltxtra}
  [2018/12/31 v0.7 Improvements for the "XeLaTeX" format]
%    \end{macrocode}
%
% \paragraph{Not for Lua\TeX}
%    \begin{macrocode}
\RequirePackage{ifluatex}
\ifluatex
  \PackageWarningNoLine {xltxtra} {^^J
    XLTXTRA IS TO BE USED ONLY UNDER XETEX.
    LOAD FONTSPEC DIRECTLY, INSTEAD.^^J
    ABORTING LOADING%
  }
  \RequirePackage{fontspec}
  \expandafter \endinput
\fi
%    \end{macrocode}
%
% \paragraph{Required packages}
%    \begin{macrocode}
\RequirePackage{ifxetex}
\RequireXeTeX
\RequirePackage{fontspec}
\RequirePackage{realscripts}
%    \end{macrocode}
%
% \paragraph{Option processing}
%    \begin{macrocode}
\newif\if@xxt@nosscript@
\newif\if@xxt@nologos@
\DeclareOption{no-sscript}{\@xxt@nosscript@true}
\DeclareOption{no-logos}{\@xxt@nologos@true}
\ProcessOptions*
%    \end{macrocode}
%
%
% \section{Logos}
% \DescribeMacro{\XeTeX}
% \DescribeMacro{\XeLaTeX}
% The \TeX-related logos people insist upon using need to be tuned
% on a per-font  basis. This package calls upon Andrew Moschou's package
% |metalogo| for this purpose. To tune the logos to each font,
% use the commands \cmd\setlogokern, \cmd\setlogodrop, etc.\ Refer to
% |mathspec|’s documentation for further details.
%
% \begin{example}
%   \setlogokern{Xe}{-0.061em}
%   \setlogokern{eL}{-0.057em}
%   \setlogokern{La}{-0.265em}
%   \setlogokern{aT}{-0.0585em}
%   \setlogokern{Te}{-0.0575em}
%   \setlogokern{eX}{-0.072em}
%   \setlogokern{eT}{-0.056em}
%   \setlogokern{X2}{0.1667em}
%   \setlogodrop{0.153em}
%   \setLaTeXa{\scshape a}
%   \setLaTeXee{\mbox{\fontspec{Times}\itshape ε}}
%   \TeX\ \XeTeX\ \LaTeX\ \XeLaTeX\ \LaTeXe
% \end{example}
%
%    \begin{macrocode}
\RequirePackage{metalogo}
%    \end{macrocode}
%
% The \pkgopt{no-logos} might be in effect, in which case \cmd\TeX, \cmd\LaTeX\ and
% \cmd\LaTeXe\ should keep their original definitions (which were saved by |metalogo|).
%
%    \begin{macrocode}
\if@xxt@nologos@
  \let\TeX\original@TeX
  \let\LaTeX\original@LaTeX
  \let\LaTeXe\original@LaTeXe
\fi
%    \end{macrocode}
%
%
%
% \section{Subscript and superscript}
%
% \begin{macro}{\textsubscript}
% \begin{macro}{\textsubscript*}
% \begin{macro}{\textsuperscript}
% \begin{macro}{\textsuperscript*}
% These commands are either defined to create fake or real sub-/super-scripts if they are starred or not, respectively. This swaps if the \pkgopt{no-sscript} is in effect.
% Text subscripts:
%    \begin{macrocode}
\if@xxt@nosscript@
  \DeclareRobustCommand*\textsubscript{%
    \@ifstar{\realsubscript}{\fakesubscript}}
  \DeclareRobustCommand*\textsuperscript{%
    \@ifstar{\realsuperscript}{\fakesuperscript}}
\fi
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \section{Assorted commands}
%
% \begin{macro}{\vfrac}
% \darg{Numerator}
% \darg{Denominator}
% No error checking is done to ensure that the font actually has the neceessary features.
% Requires the \pkg{xunicode} package for \cmd\textfractionsolidus.
%    \begin{macrocode}
\ExplSyntaxOn
\newcommand*\vfrac[2]{
  \fontspec_if_fontspec_font:TF
  {
    \fontspec_if_opentype:TF
    {
      {\addfontfeature{VerticalPosition=Numerator}#1}
       \textfractionsolidus
      {\addfontfeature{VerticalPosition=Denominator}#2}
    }
    {
      {\addfontfeature{VerticalPosition=Superior}#1}
       \textfractionsolidus
      {\addfontfeature{VerticalPosition=Inferior}#2}
    }
  }
  {
    \PackageError {xltxtra}
      { \string\vfrac\space~can~only~be~used~with~fontspec~fonts }
      { Nothing~more~to~tell. }
  }
}
\ExplSyntaxOff
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\namedglyph}
% \darg{Name of the font glyph to be typeset}
%    \begin{macrocode}
\newcommand\namedglyph[1]{%
  \@tempcnta=\XeTeXglyphindex "#1"\relax
  \ifnum\@tempcnta>0
    \XeTeXglyph\@tempcnta
  \else
    \xxt@namedglyph@fallback{#1}%
  \fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xxt@namedglyph@fallback}
% Redefine this macro to change how glyph names that aren't found get typeset.
%    \begin{macrocode}
\newcommand\xxt@namedglyph@fallback[1]{[#1]}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\showhyphens}
% Courtesy egreg.
%    \begin{macrocode}
\ExplSyntaxOn
\seq_new:N \l__xetex_showhyphens_seq
\box_new:N \l__xetex_show_hyphens_wrapping_box
\box_new:N \l__xetex_show_hyphens_temp_box
\box_new:N \l__xetex_show_hyphens_final_box
\box_new:N \g__xetex_show_hyphens_word_box

\cs_new_protected:Npn \xetex_show_hyphens:n #1
 {
  \box_clear:N \l__xetex_show_hyphens_final_box
  % split the input into items
  \seq_set_split:Nnn \l__xetex_showhyphens_seq { ~ } { #1 }
  % hyphenate all items
  \seq_map_function:NN \l__xetex_showhyphens_seq \xetex_hyphenate_word:n
  % set a box to the maximum dimension to force a Underfull \hbox warning
  \hbox_set_to_wd:Nnn \l__xetex_show_hyphens_final_box { \c_max_dim }
   {
    \hbox_unpack_clear:N \l__xetex_show_hyphens_final_box
   }
 }

\cs_new_protected:Npn \xetex_hyphenate_word:n #1
 {
  \vbox_set:Nn \l__xetex_show_hyphens_wrapping_box
   {% build a paragraph with the word with a very narrow line width
    \dim_set:Nn \hsize { 1sp }
    % disregard spurious messages
    \hbadness = 10000\relax
    \dim_set:Nn \hfuzz { \c_max_dim }
    % clear possible values of \everypar and other parameters
    \everypar={}
    \skip_set:Nn \leftskip { 0pt }
    \skip_set_eq:NN \rightskip \leftskip
    % skip the first step
    \pretolerance = -1\relax
    % avoid the indentation and add a skip to allow hyphenation
    \noindent
    \skip_horizontal:n { 0pt }
    #1
    \par
    \hbox_gset:Nn \g__xetex_show_hyphens_word_box {}
    % start a recursion to dismantle the paragraph just built
    \xetex_show_hyphens_split:
    % the result is put into \g__xetex_show_hyphens_word_box
   }
   % add the box to the final container
   \hbox_set:Nn \l__xetex_show_hyphens_final_box
    {
     \hbox_unpack_clear:N \l__xetex_show_hyphens_final_box
     \hbox_unpack_clear:N \g__xetex_show_hyphens_word_box
    }
 }

\cs_new_protected:Npn \xetex_show_hyphens_split:
 {
  \unskip % remove the interline glue
  \unpenalty % remove possible penalties
  % get the last line
  \box_set_to_last:N \l__xetex_show_hyphens_temp_box
  \box_if_empty:NF \l__xetex_show_hyphens_temp_box
   {% if there is a last line unpack it into a container
    \hbox_gset:Nn \g__xetex_show_hyphens_word_box
     {% the order is last to first
      \hbox_unpack_clear:N \l__xetex_show_hyphens_temp_box
      \unskip\unskip % remove spaces
      \hbox_unpack_clear:N \g__xetex_show_hyphens_word_box
     }
    % restart the recursion
    \xetex_show_hyphens_split:
   }
 }

\cs_set_eq:NN \showhyphens \xetex_show_hyphens:n
\ExplSyntaxOff
%    \end{macrocode}
% \end{macro}
%
%\iffalse
%</package>
%\fi
%
% \Finale
%
\endinput