From 4cc7922324b7a08ba0418e8f245cf1dcfa1891ac Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 21 Dec 2020 03:01:35 +0000 Subject: CTAN sync 202012210301 --- macros/latex/contrib/easyfloats/DEPENDS.txt | 14 + macros/latex/contrib/easyfloats/README.md | 49 + .../doc/content/bug-reports-and-contributions.tex | 41 + .../easyfloats/doc/content/documentation.tex | 1082 +++++++++++ .../contrib/easyfloats/doc/content/examples.tex | 355 ++++ .../easyfloats/doc/content/installation.tex | 8 + .../contrib/easyfloats/doc/content/license.tex | 17 + .../contrib/easyfloats/doc/content/motivation.tex | 378 ++++ .../latex/contrib/easyfloats/doc/content/names.tex | 18 + .../easyfloats/doc/content/other-packages.tex | 51 + .../contrib/easyfloats/doc/content/titlepage.tex | 17 + .../easyfloats/doc/content/used-packages.tex | 29 + macros/latex/contrib/easyfloats/doc/easyfloats.bib | 141 ++ macros/latex/contrib/easyfloats/doc/easyfloats.pdf | Bin 0 -> 546772 bytes macros/latex/contrib/easyfloats/doc/easyfloats.tex | 63 + .../contrib/easyfloats/doc/lexer/latex_atletter.py | 17 + macros/latex/contrib/easyfloats/doc/links.tex | 44 + .../easyfloats/doc/preamble/bibliography.tex | 35 + .../easyfloats/doc/preamble/description-links.tex | 224 +++ .../easyfloats/doc/preamble/examplecode.tex | 778 ++++++++ .../contrib/easyfloats/doc/preamble/keydoc.tex | 754 ++++++++ .../latex/contrib/easyfloats/doc/preamble/link.tex | 53 + .../contrib/easyfloats/doc/preamble/macros.tex | 218 +++ .../contrib/easyfloats/doc/preamble/markdown.tex | 153 ++ .../contrib/easyfloats/doc/preamble/pdfstring.tex | 35 + .../easyfloats/doc/undescribed-keywords.tex | 247 +++ .../contrib/easyfloats/easyfloats-file-list.txt | 40 + macros/latex/contrib/easyfloats/easyfloats.dtx | 1897 ++++++++++++++++++++ macros/latex/contrib/easyfloats/easyfloats.ins | 82 + 29 files changed, 6840 insertions(+) create mode 100644 macros/latex/contrib/easyfloats/DEPENDS.txt create mode 100644 macros/latex/contrib/easyfloats/README.md create mode 100644 macros/latex/contrib/easyfloats/doc/content/bug-reports-and-contributions.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/documentation.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/examples.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/installation.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/license.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/motivation.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/names.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/other-packages.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/titlepage.tex create mode 100644 macros/latex/contrib/easyfloats/doc/content/used-packages.tex create mode 100644 macros/latex/contrib/easyfloats/doc/easyfloats.bib create mode 100644 macros/latex/contrib/easyfloats/doc/easyfloats.pdf create mode 100644 macros/latex/contrib/easyfloats/doc/easyfloats.tex create mode 100644 macros/latex/contrib/easyfloats/doc/lexer/latex_atletter.py create mode 100644 macros/latex/contrib/easyfloats/doc/links.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/bibliography.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/description-links.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/examplecode.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/keydoc.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/link.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/macros.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/markdown.tex create mode 100644 macros/latex/contrib/easyfloats/doc/preamble/pdfstring.tex create mode 100644 macros/latex/contrib/easyfloats/doc/undescribed-keywords.tex create mode 100644 macros/latex/contrib/easyfloats/easyfloats-file-list.txt create mode 100644 macros/latex/contrib/easyfloats/easyfloats.dtx create mode 100644 macros/latex/contrib/easyfloats/easyfloats.ins (limited to 'macros/latex/contrib/easyfloats') diff --git a/macros/latex/contrib/easyfloats/DEPENDS.txt b/macros/latex/contrib/easyfloats/DEPENDS.txt new file mode 100644 index 0000000000..2f8165695e --- /dev/null +++ b/macros/latex/contrib/easyfloats/DEPENDS.txt @@ -0,0 +1,14 @@ +# packages loaded by default +float +caption +subcaption +graphicx # can be disabled using package option nographic +pgfkeys +etoolbox +environ +array # can be disabled using package option noarray +booktabs # can be disabled using package option nobooktabs + +# packages loaded if the corresponding package option is given +soft longtable +soft graphbox diff --git a/macros/latex/contrib/easyfloats/README.md b/macros/latex/contrib/easyfloats/README.md new file mode 100644 index 0000000000..58cca59837 --- /dev/null +++ b/macros/latex/contrib/easyfloats/README.md @@ -0,0 +1,49 @@ +# Abstract + +In standard LaTeX inserting objects like figures or tables requires too much knowledge for beginners and too much typing effort and hardcoding for people like me. +This package aims to make insertion of figures and tables easier for both beginners and experts. +Despite the term *floats* in it's name it also allows to disable floating of such objects. + + +# Documentation + +The documentation is contained in the file [doc/easyfloats.pdf](doc/easyfloats.pdf). + +The source code for the documentation is *not* contained in the dtx file but in the directory [doc](doc). +To build the documentation run: +```sh +cd doc +pdflatex easyfloats.tex +biber easyfloats +pdflatex easyfloats.tex +pdflatex easyfloats.tex +``` + + +# Dependencies + +The dependencies are listed in [DEPENDS.txt](DEPENDS.txt). +It's syntax is explained on http://tug.org/texlive/pkgcontrib.html#deps. +See also section *Used packages* in the [documentation](doc/easyfloats.pdf). + + +# License + +This package and it's documentation are distributed under the [LaTeX Project Public License](https://www.latex-project.org/lppl/), version 1.3 or later. +The preamble of the documentation may alternatively, at your choice, be reused under the terms of the [WTFPL](http://www.wtfpl.net/), version 2 or later. + +Additionally to the rights granted by the LaTeX Project Public License +you have permission to freely distribute *unmodified* copies +of the files [easyfloats.sty](easyfloats.sty) and [doc/easyfloats.pdf](doc/easyfloats.pdf) without other files of this work. +The other files of this work can be found at: +https://gitlab.com/erzo/latex-easyfloats + +The examples and tests are distributed under the [WTFPL](http://www.wtfpl.net/), version 2 or later. + + +# Contact + +Bug reports and feature requests can be submitted at +https://gitlab.com/erzo/latex-easyfloats/-/issues. + +Please see also section *Bug reports and contributions* in the [documentation](doc/easyfloats.pdf). diff --git a/macros/latex/contrib/easyfloats/doc/content/bug-reports-and-contributions.tex b/macros/latex/contrib/easyfloats/doc/content/bug-reports-and-contributions.tex new file mode 100644 index 0000000000..ccfb7dce9a --- /dev/null +++ b/macros/latex/contrib/easyfloats/doc/content/bug-reports-and-contributions.tex @@ -0,0 +1,41 @@ +% !TeX root = ../easyfloats.tex + +\section{Bug reports and contributions} +\label{bug-reports-and-contributions} + +If you find a bug please open an issue for it +on \url{https://gitlab.com/erzo/latex-easyfloats/-/issues} +including a minimal example where the bug occurs, +an explanation of what you expected to happen +and the version of \LaTeX\ and the packages you are using (which are included in the log file). +Issues which are not reproducible will be closed. + +If you have a feature request please open an issue for it +on \url{https://gitlab.com/erzo/latex-easyfloats/-/issues} +including a minimal example which you would like to work, +an explanation of what it should do +and a use case explaining why this would be useful. + +Before opening an issue please check that there is not yet an issue for it already. + +If you want to resolve an issue yourself please create a merge request. +Make the changes in \filename{easyfloats.dtx}. +You can generate the sty file with \verb|tex easyfloats.ins| +but you do not need to do that manually because \filename{test/autotest.py} does that automatically for you. +Before creating a merge request please make sure that the automated tests still pass. +Run the python3 script \filename{test/autotest.py} from the project root or test directory without arguments. +While running the tests it shows a progress bar in square brackets. +A dot stands for a successful test, an F for a failed test and an E for an error in the test script. +Merge requests where a test prints F will most likely be rejected. +If you get an E please create a bug report issue. + +Please use *tabs* for indentation. + +A merge request should include: +\begin{itemize} +\item The changes to \filename{easyfloats.dtx} +\item The automatically generated \filename{easyfloats.sty} +\item Additions to the documentation +\item Automated tests in the \filename{test} directory to make sure the new feature or bug fix does not break in the future +\item A link in the merge request description to the issue which it is supposed to close +\end{itemize} diff --git a/macros/latex/contrib/easyfloats/doc/content/documentation.tex b/macros/latex/contrib/easyfloats/doc/content/documentation.tex new file mode 100644 index 0000000000..6dd1d9b62d --- /dev/null +++ b/macros/latex/contrib/easyfloats/doc/content/documentation.tex @@ -0,0 +1,1082 @@ +% !TeX root = ../easyfloats.tex + +\section{Documentation} +\label{documentation} + +This section contains the documentation on how to use this package. + +\Cref{options} gives general information on options which environments and commands defined by this package may take. +The options themselves are explained in \cref{environments,commands} where the environments and commands defined by this package are explained. + +\Cref{initialization} describes what is happening when loading this package. +\Cref{package-options} describes the options which can be passed to `\usepackage` when loading this package. + +\Cref{help} explains a few features which may help you to get a better understanding about what is going on. +This might be useful if you run into unexpected errors or this package behaves different than you expected. + + +\subsection{Options} +\label{options} + +The environments and commands defined by this package take options (implemented with the \pkg{pgfkeys} package). +Options are a comma separated list of ``s or `=` pairs. + +Which keys are allowed for which environment\slash command and which values are allowed for which key is specified in \cref{environments,commands} where the environments and commands are documented. +This section gives general information about these options. + +This section does *not* apply to the package options which are explained in \cref{package-options}. + + +\subsubsection{Initial vs default values} +\label{initial-vs-default-values} + +I am using the words *initial value* and *default value* like they are used in the \mycite{tikz}. + +The *initial* value of an option is the value which is used if the key is *not* given. + +The *default* value of an option is the value which is used if the key is given without a value. +Most keys don't have a default value, i.e.\ if you use the key you must explicitly give it a value. + +\subsubsection{Options scope} +\label{options-scope} + +Setting an option always applies until the end of the current group. +For the argument of an environment this is the corresponding `\end` command. +For the argument of the \cmd{\includegraphicobject} command this is the end of this command. +For the argument of \cmd{\objectset} this may be the end of the document. + +If you are not familiar with the concept of groups in \TeX\ \mycite[chapter~10]{texbytopic} is one possible place to read up on it. + +\subsubsection{Special characters in options} +\label{special-characters-in-options} + +If a value contains a comma or an equals sign it must be wrapped in curly braces. + +Spaces before and after a comma (separating an option) and before or after an equals sign (separating key and value) are ignored. +However, a space after the opening brace is *not* ignored. +So if you put the first key on the next line make sure to comment out the linebreak. +If a leading or trailing space in a value is desired wrap the value in curly braces. + +`\par` (aka an empty line) is forbidden in keys but allowed in values. + +\subsubsection{Key patterns} +\label{key-patterns} + +Sometimes I am talking about entire groups of keys instead of individual keys. +I specify those groups with a pattern which matches the keys that I am referring to. +In these patterns parenthesis stand for something optional and angular brackets for wildcards. + +For example the pattern `() arg(s)` matches the keys `tabular* arg` and `args` (and many more) +but not `env arg` because `env` is not an existing environment. + +If a key has a version which ends on a `+` to append a value instead of replacing it the space in front of the `+` is optional. + +\subsubsection{Key name vs key path} +\label{key-name-vs-key-path} + +\pkg{pgfkeys} organizes all keys \textcquote[page~954]{tikz}{in a large tree that is reminiscent of the Unix file tree.} +The keys of this package are located in the three paths `/object`, `/subobject` and `/graphicobject`. + +In error messages thrown by the \pkg{pgfkeys} package the full path of a key is shown. + +When setting keys, however, you need not and should not specify the full path. +The commands and environments of this package set the path automatically. +Using full paths does not directly cause an error or a warning but trying to set options for a style or style group with \cmd{\objectset} causes undefined behavior. + +Therefore, error messages thrown directly by this package omit the path and show the name of the key only. + +\subsubsection{Key types} +\label{key-types} + +In \pkg{pgfkeys} there are different types of keys. +Which type a key belongs to is relevant for debugging if you want to check the value of a key, see \cref{help}. + +\keytypedoc{storing key} + Keys of this type are like a variable. + They store the given value. + This value can be showed using the `.show value` handler (see \cref{help}). + +\keytypedoc{executed key} + Keys of this type are like a function. + They execute some predefined code and possibly take a value as argument. + +\keytypedoc{boolean key} + is a special case of an executed key which sets a plain \TeX\ if command. + This if command and it's meaning can be showed with the `.show boolean` handler (which is *not* contained in \pkg{pgfkeys}, I have defined it in this package). + + The allowed values for a key of this type are `true` and `false`. + The default value (i.e.\ the value which is assumed if the key is given without a value) is `true`. + +\keytypedoc{forwarding key} + is a special case of an executed key which calls another key. + +\keytypedoc{handler} + Keys defined in the path `/handlers`. + They can be applied to other keys by appending them to the path. + For users of this package they can be helpful for debugging. + For example `\objectset{env/.show value}` shows the value of the key `env`. + + The \pkg{pgfkeys} package also defines handlers which expand the value. + I haven't come up with an example where this might be useful in the context of this package but e.g.\ `tabular arg/.expand once=\colspec,` works as expected. + +\keytypedoc{unknown key handler} + is a special key which is called if a given key does not exist and it's name is not a handler. + I am using this to implement key patterns. +\endkeytypedoc + +\subsubsection{Styles} +\label{styles} +\DescribeMeta{style} +\DescribeMeta{styles} + +This package defines two styles, one for figures and one for tables. + +You can think of these styles as an extension of the \pkg{float} package's float styles. + +These styles are somewhat inspired by the \pkg{pgfkeys} styles but are different. +They are neither set nor applied in the same way. + +A style is a list of options which is not set immediately but locally for each object belonging to that style. + +The options of a style can be set by passing the name of the style as an optional argument to the \cmd{\objectset} command, +e.g.\ `\objectset[figure]{}` or `\objectset[table]{}`. + +A style is applied by using the corresponding environment (e.g.\ \env{figureobject} or \env{tableobject}) +or `\graphicobjectstyle{