summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/dynamicnumber
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/dynamicnumber
Initial commit
Diffstat (limited to 'macros/latex/contrib/dynamicnumber')
-rw-r--r--macros/latex/contrib/dynamicnumber/LICENSE.txt22
-rw-r--r--macros/latex/contrib/dynamicnumber/README.md73
-rw-r--r--macros/latex/contrib/dynamicnumber/dynamicnumber.dtx209
-rw-r--r--macros/latex/contrib/dynamicnumber/dynamicnumber.ins45
-rw-r--r--macros/latex/contrib/dynamicnumber/dynamicnumber.pdfbin0 -> 158209 bytes
5 files changed, 349 insertions, 0 deletions
diff --git a/macros/latex/contrib/dynamicnumber/LICENSE.txt b/macros/latex/contrib/dynamicnumber/LICENSE.txt
new file mode 100644
index 0000000000..6327fe56a1
--- /dev/null
+++ b/macros/latex/contrib/dynamicnumber/LICENSE.txt
@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Olivier Pieters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
diff --git a/macros/latex/contrib/dynamicnumber/README.md b/macros/latex/contrib/dynamicnumber/README.md
new file mode 100644
index 0000000000..4c86a3cfa6
--- /dev/null
+++ b/macros/latex/contrib/dynamicnumber/README.md
@@ -0,0 +1,73 @@
+Dynamic Number
+==============
+
+What is it?
+-----------
+
+Dynamic Number dynamically typesets values generated in different kinds of scripts in LaTeX through the use of symbolic links. The aim is to reduce errors resulting from out-of-date numbers by directly setting them in the number generating file and importing a symbolic link in the LaTeX source file.
+
+It can be used to import not only numerical values into LaTeX, but even strings and pieces of code are possible. The main repository is located in [this](https://github.com/opieters/DynamicNumber) repository.
+
+**Attention** The symbolic links mentioned here are ***NOT*** related in any kind to the symbolic links used in UNIX systems. See example below to see what is meant with a symbolic link.
+
+Installation
+------------
+
+Depending on your desires, one or more might not be applicable. All the supported languages have a file in the `languages` folder. Currently only MATLAB and Python are supported to produce Dynamic Number (dn) list files (also called symbolic link lists).
+
+### LaTeX
+
+Currently the package is also available on CTAN. This is the preferred way of installing LaTeX packages. You can thus download it using your favourite (La)TeX package manager. The instructions below are thus obsolete.
+
+### MATLAB
+
+Add the necessary functions to MATLAB's path.
+
+1. Clone the directory in your MATLAB folder (`Documents/MATLAB`).
+2. Now the contents should be in `Documents/MATLAB/DynamicNumber`.
+3. Open MATLAB.
+4. Set path to include the cloned folder. The Set path can be found in the File menu on older MATLAB installations or HOME, Environment in newer installations.
+
+### Python
+
+Install with `pip`: `sudo pip install dynamicnumber`
+
+Quick start
+-----------
+
+### LaTeX
+
+LaTeX usage is very straightforward. Load the package with `\usepackage{dynamicnumber}` and next load a symbolic link lists with `\dnreadfile{list}`. Now you can start using your dynamic variables with `\dnget{variable}`.
+
+More information and additional commands can be found in the documentation.
+
+**Attention!** Do not attempt to create a `pgfkey` with the name `dynamicnumber`, it will conflict with the internal workings of the package.
+
+### MATLAB and Python
+
+Create a symbolic link lists with the `dn()` command, then add symbolic links with the `add`-method.
+
+The `add`-method requires at least 2 arguments: the symbolic link name and a value (either numerical or string). The optional third can specify a unit for the value. The symbolic link will be stored to typeset both number and unit in a nice way, with the `units` package (`\unit{<value}{<unit>}`).
+
+Example (in Python, MATLAB code is almost identical)
+
+```python
+# Some computations and sensor readout to predict temperature tomorrow:
+temperature = 23.4
+temp_predictions = dn('TemperaturePredictions')
+temp_predictions.add('tomorrow',temparture,'C') # or \\Celcius instead of C
+```
+
+**Note!**: If you wish to use special LaTeX commands such as `\Celcius` or `\metre`, your need to be careful with the use of the backslash. In MATLAB you only need to add one backslash because of the way it is parsed, but in Python you need to add two of them! This is needed because the backslash is also used for escape sequences.
+
+Contributions
+-------------
+
+The libraries are basic in a sense that they do not have a lot of features or options. This is intentional. Users can easily adopt them to suit their own needs without having to go through 100s of lines of code and the learning curve is very small. So the main goal is to have a library that support many platforms, is (almost) identical on all these platforms and is simple to use.
+
+Bug fixes and small feature improvements are always welcome, you can use a pull request to add must-have features or perform bug fixes.
+
+License
+-------
+
+See the `LICENSE.txt` file.
diff --git a/macros/latex/contrib/dynamicnumber/dynamicnumber.dtx b/macros/latex/contrib/dynamicnumber/dynamicnumber.dtx
new file mode 100644
index 0000000000..fe512c14d9
--- /dev/null
+++ b/macros/latex/contrib/dynamicnumber/dynamicnumber.dtx
@@ -0,0 +1,209 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2015 by Olivier Pieters
+% -------------------------------------
+%
+% This file may be distributed and/or modified under the
+% conditions of the MIT License, a version can be found
+% in the GitHub repository:
+%
+% https://github.com/opieters/DynamicNumber
+%
+% \fi
+%
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{dynamicnumber}
+%<package> [2015/10/27 v0.1.3 Dynamic Number package]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{dynamicnumber}
+\usepackage{hyperref}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{dynamicnumber.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{58}
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+%
+% \changes{v0.1}{2015/10/04}{Initial version}
+% \changes{v0.1.1}{2015/10/06}{Performance improvements (one call to newread)}
+%
+% \GetFileInfo{dynamicnumber.sty}
+%
+% \DoNotIndex{<list of control sequences>}
+%
+% \title{The \textsf{dynamicnumber} package\thanks{This document
+% corresponds to \textsf{dynamicnumber}~\fileversion,
+% dated \filedate.}}
+% \author{Olivier Pieters \\ \texttt{me (at) olivierpieters (dot) be}}
+%
+% \maketitle
+%
+% \section{Introduction}
+%
+% Dynamic Number dynamically typesets values generated in different kinds of
+% scripts in LaTeX through the use of symbolic links. The aim is to reduce
+% errors resulting from out-of-date numbers by directly setting them in the
+% number generating file and importing a symbolic link in the LaTeX source file.
+%
+% \textbf{Attention!} The name ``symbolic link'' is not related to UNIX symbolic
+% links.
+%
+% \section{Usage}
+%
+% \DescribeMacro{\dndeclare}
+% Declares a dynamic number (dn) list. \index{decare dn list|usage} By creating
+% a list, variables can be saved and loaded for use in the document. The
+% mandatory argument is the list name.
+%
+% \DescribeMacro{\dnsetcurrent}
+% This environment does nothing. \index{decare dn list|usage} Sets the current
+% dn list. The mandatory argument specifies the list name. This command is very
+% useful if multiple lists are used, so you do not always have to specify the dn
+% list if it is not the current one.
+%
+%% \DescribeMacro{\dncurrent}
+% Returns the name of current dn list. \index{current dn list|usage} Returns
+% the current dn list and takes no arguments. This can be useful for debugging
+% purposes.
+%
+% \DescribeMacro{\dnload}
+% Load dn list \meta{name}|.dnlist|. \index{load dn list|usage} Loads the dn
+% list whose name is passed as mandatory argument. This argument should only
+% include the list-name and \emph{not} the filename. It sets the current dn list
+% to this list.
+%
+% \DescribeMacro{\dnget}
+% Get symbolic link value. \index{get dn list entry|usage} Loads the symbolic link's value from the current dn list if no optional argument is present (optional argument is passed first). Otherwise, the optional argument specifies the dn list containing the symbolic link
+%
+% \StopEventually{\PrintIndex}
+%
+% \section{Implementation}
+%
+% Load all required packages.
+% \begin{macrocode}
+\RequirePackage{pgfkeys}
+\RequirePackage{xparse}
+% \end{macrocode}
+%
+% Create input stream
+% \begin{macrocode}
+\newread\dninstream
+% \end{macrocode}
+% \begin{macro}{\@IfNoValueOrEmptyTF}
+% Tests if a parameter is empty using expl3.
+% Performs a double check to make sure it really is empty.
+% This is based on \href{http://tex.stackexchange.com/questions/63223/xparse-empty-arguments}{this}
+% StackExchange post.
+% \begin{macrocode}
+\ExplSyntaxOn
+\DeclareExpandableDocumentCommand{\@IfNoValueOrEmptyTF}{mmm}
+ {
+ \IfNoValueTF{#1}{#2}
+ {
+% \end{macrocode}
+% Order: |{argument}{if empty}{if not empty}|
+% \begin{macrocode}
+ \tl_if_empty:nTF {#1} {#2} {#3}
+ }
+ }
+\ExplSyntaxOff
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\dndeclare}
+% The |\dndeclare| macro defines a list name and defines a |pgfkey| that stores
+% all symbolic links and their values. It always is a subdirectory of |/dynamicnumber|:
+% |/dynamicnumber/|\meta{name}|/|
+% \begin{macrocode}
+\DeclareDocumentCommand{\dndeclare}{m}{%
+ \pgfkeys{%
+ /dynamicnumber/#1/.is family,
+ /dynamicnumber/#1/.unknown/.style = {%
+ \pgfkeyscurrentpath/\pgfkeyscurrentname/.initial = ##1%
+ }
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\dnsetcurrent}
+% |\dnsetcurrent{|\meta{name}|}| sets the current dn list to \meta{name}.
+% If no list was previously set, the |\dnsetcurrent| command is defined and
+% set to \meta{name}.
+% \begin{macrocode}
+\DeclareDocumentCommand{\dnsetcurrent}{m}{%
+ \@ifundefined{dncurrent}{%
+% \end{macrocode}
+% \begin{macro}{\dncurrent}
+% Stores the current dn list used in the |\dnget| command.
+% \begin{macrocode}
+ \DeclareDocumentCommand{\dncurrent}{}{#1}%
+% \end{macrocode}
+% \end{macro}
+% \begin{macrocode}
+ }
+ {%
+ \RenewDocumentCommand{\dncurrent}{}{#1}%
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\dnload}
+% Loads a dn list from file \meta{load}|.dnlist| and executes all commands in
+% this file after a check if the file exists.
+% \changes{v0.1.3}{2015/10/27}{Removed bug where the current list was reset.}
+% \begin{macrocode}
+\DeclareDocumentCommand{\dnload}{m}{%
+ \IfFileExists{#1.dnlist}{%
+ \immediate\openin\dninstream=#1.dnlist
+ \@whilesw\unless\ifeof\dninstream\fi{%
+ \immediate\read\dninstream to \@auxcommand
+ \@auxcommand
+ }%
+ \immediate\closein\dninstream%
+ }{}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\dnget}
+% Get the value stored in a specific dn list entry. A dn list can be specified
+% (hence optional argument), otherwise the current list will be used.
+% \begin{macrocode}
+\DeclareDocumentCommand{\dnget}{O{} m}{%
+\@IfNoValueOrEmptyTF{#1}{%
+ \pgfkeysvalueof{/dynamicnumber/\dncurrent/#2}}{%
+ \pgfkeysvalueof{/dynamicnumber/#1/#2}}%
+}
+\endinput
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \Finale
+\endinput
diff --git a/macros/latex/contrib/dynamicnumber/dynamicnumber.ins b/macros/latex/contrib/dynamicnumber/dynamicnumber.ins
new file mode 100644
index 0000000000..38ef4b9cd7
--- /dev/null
+++ b/macros/latex/contrib/dynamicnumber/dynamicnumber.ins
@@ -0,0 +1,45 @@
+%%
+%% Copyright (C) 2015 by Olivier Pieters
+%%
+%% This file may be distributed and/or modified under the
+%% conditions of the MIT License, a version can be found
+%% in the GitHub repository:
+%%
+%% https://github.com/opieters/DynamicNumber
+%%
+
+\input docstrip.tex
+\keepsilent
+
+\usedir{tex/latex/dynamicnumber}
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2015 by Olivier Pieters
+
+This file may be distributed and/or modified under the
+conditions of the MIT License, a version can be found
+in the GitHub repository:
+
+ https://github.com/opieters/DynamicNumber
+
+\endpreamble
+
+\generate{\file{dynamicnumber.sty}{\from{dynamicnumber.dtx}{package}}}
+
+\Msg{*********************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the}
+\Msg{* following file into a directory searched by TeX:}
+\Msg{*}
+\Msg{* \space\space dynamicnumber.sty}
+\Msg{*}
+\Msg{* To produce the documentation run the file }
+\Msg{* dynamicnumber.dtx through LaTeX.}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{*********************************************************}
+
+\endbatchfile
diff --git a/macros/latex/contrib/dynamicnumber/dynamicnumber.pdf b/macros/latex/contrib/dynamicnumber/dynamicnumber.pdf
new file mode 100644
index 0000000000..dde0bbdc87
--- /dev/null
+++ b/macros/latex/contrib/dynamicnumber/dynamicnumber.pdf
Binary files differ