Initial commit

5 files changed, 445 insertions, 0 deletions

diff --git a/macros/latex/contrib/eqexpl/README.md b/macros/latex/contrib/eqexpl/README.md
new file mode 100644
index 0000000000..5154494a41
--- /dev/null
+++ b/macros/latex/contrib/eqexpl/README.md
@@ -0,0 +1,36 @@
+Align explanation for formulas in LaTeX
+========
+
+The package is licenced under Creative Commons Attribution-ShareAlike
+4.0 International (CC BY-SA 4.0).
+
+The package was developed as an answer to the question on [tex.stackexchange.com](https://tex.stackexchange.com/q/95838/119485)
+
+The package `eqexpl` was developed to give the tool to make «perfect»
+explanation for formulas, not just the enumeration.
+
+                I = U / Rs,            (1)
+
+    where   U --- voltage at the section, V;
+	       Rs --- total     section    resis-
+                  tance, Ohm.
+
+Requirements:
+1. The variables (left side) must be aligned right.
+2. The dash must be aligned center one under another.
+3. The explanation (right side) must be justified, the last string
+   must be aligned left and
+   - if the explanation takes more than one line, the left side of
+     explanation must be aligned (second explanation in the example).
+
+The package adds new environment `eqexpl` with a command `\item` with
+one required parameter --- variable to explain.  The explanation in
+the example above was made with the code
+
+    \begin{eqexpl}
+      \item{U} voltage at the section, V;
+	  \item{Rs} total section resistance, Ohm.
+	\end{exqexpl}
+
+See example `eqexpl.tex` for more details.  You can compile it with
+`pdflatex eqexpl.tex`.
diff --git a/macros/latex/contrib/eqexpl/README.ru.md b/macros/latex/contrib/eqexpl/README.ru.md
new file mode 100644
index 0000000000..7d60a4da60
--- /dev/null
+++ b/macros/latex/contrib/eqexpl/README.ru.md
@@ -0,0 +1,37 @@
+Выравнивание пояснений к формулам в LaTeX
+========
+
+Пакет распространяется по лицензии Creative Commons
+Attribution-ShareAlike 4.0 International (CC BY-SA 4.0).
+
+Пакет был разработан в качестве ответа на вопрос на [tex.stackexchange.com](https://tex.stackexchange.com/q/95838/119485)
+
+Пакет `eqexpl` был разработан для того, чтобы обеспечить возможность
+давать формулам более осмысленные пояснения, оформление которых
+отличается от простого перечисления.
+
+                I = U / Rs,            (1)
+
+    где   U --- напряжение на участке, В;
+	     Rs --- суммарное   сопротивление
+                участка, Ом.
+
+Требования к оформлению:
+1. Поясняемые переменные выравниваются по правому краю.
+2. Тире пояснения выравниваются по центру друг под другом.
+3. Пояснения выравниваются по ширине, последняя строка выравнивается
+   по левому краю, при этом
+   - если левый край пояснения занимает более одной строки, строки
+     должны быть выровнены слева (второе пояснение).
+
+Пакет добавляет новое окружение `eqexpl`, внутри которого команда
+перечисления `\item` имеет обязательный параметр --- поясняемую
+переменную.  Пояснение выше выполненяется следующим образом
+
+    \begin{eqexpl}
+      \item{U} напряжение на участке, В;
+	  \item{Rs} суммарное сопротивление участка, Ом.
+	\end{exqexpl}
+
+Подробнее смотрите `eqexpl.tex`.  Вы можете собрать его с помощью
+команды `pdflatex eqexpl.tex`.
diff --git a/macros/latex/contrib/eqexpl/eqexpl.pdf b/macros/latex/contrib/eqexpl/eqexpl.pdf
new file mode 100644
index 0000000000..33184744bb
--- /dev/null
+++ b/macros/latex/contrib/eqexpl/eqexpl.pdf
diff --git a/macros/latex/contrib/eqexpl/eqexpl.sty b/macros/latex/contrib/eqexpl/eqexpl.sty
new file mode 100644
index 0000000000..dfdd46779c
--- /dev/null
+++ b/macros/latex/contrib/eqexpl/eqexpl.sty
@@ -0,0 +1,76 @@
+%% The package is licenced under Creative Commons Attribution-ShareAlike
+%% 4.0 International (CC BY-SA 4.0)
+
+\ProvidesPackage{eqexpl}[2019/05/15 v. 1.1]
+\RequirePackage{etoolbox}
+\RequirePackage{xparse}
+\RequirePackage{calc}
+
+%% Spaces between elements
+\newlength{\eqexplSpaceWidth}
+\newcommand{\eqexplSetSpace}[1]{%
+  \setlength{\eqexplSpaceWidth}{\ifstrempty{#1}{2mm}{#1}}%
+}
+\eqexplSetSpace{}
+
+%% Width of 'intro' (typ. 'where')
+\newcommand{\eqexplSetIntro}[1]{%
+  \def\eqexplIntro{#1}%
+}
+\eqexplSetIntro{}
+
+%% Width of delimiter
+\newcommand{\eqexplSetDelim}[1]{%
+  \def\eqexplDelim{#1}%
+}
+\eqexplSetDelim{---}
+
+%% Width of item
+\newcommand{\eqexplSetItemWidth}[1]{%
+  \def\eqexplItemWidth{#1}%
+}
+\eqexplSetItemWidth{5mm}
+
+%% Align of item
+\newcommand{\eqexplSetItemAlign}[1]{%
+  \def\eqexplItemAlign{#1}%
+}
+\eqexplSetItemAlign{r}
+
+\newlength{\itemWidth}
+\newlength{\leftSideWidth}
+
+\newenvironment{eqexpl}[1][\eqexplItemWidth]{%
+  \let\olditem\item%
+  \setlength{\itemWidth}{#1}%
+  \setlength{\leftSideWidth}{\ifdefempty{\eqexplIntro}{}{\widthof{\eqexplIntro}+%
+                             \eqexplSpaceWidth+}%
+                             \itemWidth+%
+                             \eqexplSpaceWidth+%
+                             \widthof{\eqexplDelim}+%
+                             \eqexplSpaceWidth}%
+  \newtoggle{eqexplFirstItem}%
+  \toggletrue{eqexplFirstItem}%
+  \RenewDocumentCommand{\item}{ m O{\eqexplDelim}}{%
+    \olditem \makebox[\leftSideWidth]{%
+      \ifdefempty{\eqexplIntro}{}{
+        \makebox[\widthof{\eqexplIntro}][l]{\iftoggle{eqexplFirstItem}{\eqexplIntro}{}}%
+        \hspace{\eqexplSpaceWidth}%
+      }
+      \makebox[\itemWidth][\eqexplItemAlign]{##1}%
+      \hspace{\eqexplSpaceWidth}%
+      \makebox[\widthof{##2}][c]{##2}%
+      \hspace{\eqexplSpaceWidth}%
+    }%
+    \togglefalse{eqexplFirstItem}%
+    \ignorespaces% https://tex.stackexchange.com/a/44062
+  }%
+  \begin{list}{}{\setlength{\parsep}{0pt}%
+  \setlength{\topsep}{0pt}%
+  \setlength{\itemsep}{0pt}%
+  \setlength{\labelsep}{0pt}%
+  \setlength{\leftmargin}{\leftSideWidth}%
+  \setlength{\itemindent}{-\leftSideWidth}}}{%
+  \end{list}
+}
+\endinput
diff --git a/macros/latex/contrib/eqexpl/eqexpl.tex b/macros/latex/contrib/eqexpl/eqexpl.tex
new file mode 100644
index 0000000000..ece2fab947
--- /dev/null
+++ b/macros/latex/contrib/eqexpl/eqexpl.tex
@@ -0,0 +1,296 @@
+\documentclass{article}
+\usepackage[T2A,T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{hyperref}
+\usepackage{eqexpl}
+
+\begin{document}
+
+\title{eqexpl v. 1.1}
+\author{Konstantin Morenko}
+
+\maketitle
+
+The package is licenced under Creative Commons Attribution-ShareAlike
+4.0 International (CC BY-SA 4.0)
+
+The package use \href{https://semver.org/}{semantic versioning}.
+
+\section{The aim of the package}
+
+The package was developed as an answer to the question \href{https://tex.stackexchange.com/q/95838/119485}{on tex.stackexchange.com}
+
+Package was developed to give the tool to make <<perfect>> explanation
+for formulas, not just the enumeration.
+
+This package allows to describe formula's variables in unified through
+the document manner.
+
+\section{Similar packages}
+
+Nomencl: \href{http://ctan.org/pkg/nomencl}{http://ctan.org/pkg/nomencl}
+
+\section{Contributors}
+
+Konstantin Morenko \href{mailto:me@konstantin-morenko.ru}{me@konstantin-morenko.ru}
+
+The package currently hosted on GitHub:
+\href{https://github.com/konstantin-morenko/latex-equation-explanation}{https://github.com/konstantin-morenko/latex-equation-explanation}
+
+\section{Architecture}
+
+The list consist of few lengths:
+\begin{itemize}
+\item width of <<intro>> section (default is empty, 0pt);
+\item width of spaces between elements (default is 2mm);
+\item width of item block (default is 5mm);
+\item width of separator (default is '---');
+\item the rest of the width of a text (used to align left side of the
+  explanation text).
+\end{itemize}
+
+\section{Usage}
+
+First, include package into preamble with
+
+\begin{verbatim}
+  \usepackage{eqexpl}
+\end{verbatim}
+
+Then write a formula and describe the parameters
+
+\begin{equation}
+  E = m c^2
+\end{equation}
+\begin{eqexpl}
+\item{$E$} equivalent energy
+\item{$m$} mass
+\item{$c$} speed of light ($ c \approx 3 \times 10^8 m/s$)
+\end{eqexpl}
+using
+\begin{verbatim}
+  \begin{equation}
+    E = m c^2
+  \end{equation}
+  \begin{eqexpl}
+  \item{$E$} equivalent energy
+  \item{$m$} mass
+  \item{$c$} speed of light ($ c \approx 3 \times 10^8 m/s$)
+  \end{eqexpl}
+\end{verbatim}
+
+\section{Configure and examples}
+
+\subsection{Test list}
+
+\newcommand{\testList}{
+\item{U} voltage at the section, V;
+\item{Rs} total section resistance, Ohm.
+\item{$Very^{46}$}very very very very very very very very very very very
+  very very very very very very very very very very very very very
+  very very very very very very very very very very very very very
+  very very very very very very very very very long line;
+}
+
+This list is used for next examples:
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\subsection{Setting eqexplSetSpace}
+
+\noindent Set \verb+\eqexplSetSpace{0mm}+
+
+\eqexplSetSpace{0mm}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetSpace{}+ (default 2mm)
+
+\eqexplSetSpace{}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetSpace{10mm}+
+
+\eqexplSetSpace{10mm}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\eqexplSetSpace{}
+
+\subsection{Setting eqexplSetIntro}
+
+\noindent Set \verb+\eqexplSetIntro{where}+
+
+\eqexplSetIntro{where}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetIntro{in this equation}+
+
+\eqexplSetIntro{in this equation}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\eqexplSetIntro{}
+
+\subsection{Setting eqexplSetDelim}
+
+\noindent Set \verb+\eqexplSetDelim{---}+ (default)
+
+\eqexplSetDelim{---}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetDelim{=}+
+
+\eqexplSetDelim{=}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetDelim{$\to$}+
+
+\eqexplSetDelim{$\to$}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\eqexplSetDelim{---}
+
+\subsection{Setting eqexplSetItemWidth}
+
+\noindent Set \verb+\eqexplSetItemWidth{5mm}+ (default)
+
+\eqexplSetItemWidth{5mm}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetItemWidth{10mm}+
+
+\eqexplSetItemWidth{10mm}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\eqexplSetItemWidth{5mm}
+
+\subsection{Setting item width for 'begin-end' block}
+
+When we have a long variable name (for example \verb+very-very-long+),
+it could lead us to overhelming the variable name as in example below
+
+\begin{eqexpl}
+  \item{$long$} just variable
+  \item{$very-long$} just variable
+  \item{$very-very-long$} just variable
+\end{eqexpl}
+
+User could set a parameter to environment to use custom item width for
+current block in opposition to setting it before block to new value
+and unsetting it to default after the end of the block.  For this
+purpose use \verb+\begin{eqexpl}[width]+.
+
+\noindent Set \verb+\begin{eqexpl}[10mm]+
+
+\begin{eqexpl}[10mm]
+  \item{$long$} just variable
+  \item{$very-long$} just variable
+  \item{$very-very-long$} just variable
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Test for backing to default in next block
+
+\begin{eqexpl}
+  \item{$long$} just variable
+  \item{$very-long$} just variable
+  \item{$very-very-long$} just variable
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\begin{eqexpl}[20mm]+
+
+\begin{eqexpl}[20mm]
+  \item{$long$} just variable
+  \item{$very-long$} just variable
+  \item{$very-very-long$} just variable
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Test for backing to default in next block
+
+\begin{eqexpl}
+  \item{$long$} just variable
+  \item{$very-long$} just variable
+  \item{$very-very-long$} just variable
+\end{eqexpl}
+
+\subsection{Setting eqexplItemAlign}
+
+\noindent Set \verb+\eqexplSetItemAlign{r}+ (default)
+
+\eqexplSetItemAlign{r}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetItemAlign{l}+
+
+\eqexplSetItemAlign{l}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\vspace{5mm}
+
+\noindent Set \verb+\eqexplSetItemAlign{c}+
+
+\eqexplSetItemAlign{c}
+\begin{eqexpl}
+  \testList
+\end{eqexpl}
+
+\eqexplSetItemAlign{r}
+
+\subsection{Setting custom delimiter for individual items}
+
+\noindent Setting \verb+\item{U}[=]...+ and
+\verb+\item[$\to$]{Rs}...+.
+
+\begin{eqexpl}
+  \item{U}[=] voltage at the section, V;
+  \item{Rs}[$\to$] total section resistance, Ohm.
+  \item{$Very^{46}$}[$\propto$] very very very very very very very
+    very very very very very very very very very very very very very
+    very very very very very very very very very very very very very
+    very very very very very very very very very very very very very
+    long line;
+\end{eqexpl}
+
+\end{document}