From 40af42087ad5180e7ef930675b5eefa5e86f1363 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 21 Dec 2020 22:19:11 +0000 Subject: easyfloats (21dec20) git-svn-id: svn://tug.org/texlive/trunk@57195 c570f23f-e606-0410-a88d-b1316a301751 --- .../content/bug-reports-and-contributions.tex | 41 + .../doc/latex/easyfloats/content/documentation.tex | 1082 ++++++++++++++++++++ .../doc/latex/easyfloats/content/examples.tex | 355 +++++++ .../doc/latex/easyfloats/content/installation.tex | 8 + .../doc/latex/easyfloats/content/license.tex | 17 + .../doc/latex/easyfloats/content/motivation.tex | 378 +++++++ .../doc/latex/easyfloats/content/names.tex | 18 + .../latex/easyfloats/content/other-packages.tex | 51 + .../doc/latex/easyfloats/content/titlepage.tex | 17 + .../doc/latex/easyfloats/content/used-packages.tex | 29 + 10 files changed, 1996 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/bug-reports-and-contributions.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/documentation.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/examples.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/installation.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/license.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/motivation.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/names.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/other-packages.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/titlepage.tex create mode 100644 Master/texmf-dist/doc/latex/easyfloats/content/used-packages.tex (limited to 'Master/texmf-dist/doc/latex/easyfloats/content') diff --git a/Master/texmf-dist/doc/latex/easyfloats/content/bug-reports-and-contributions.tex b/Master/texmf-dist/doc/latex/easyfloats/content/bug-reports-and-contributions.tex new file mode 100644 index 00000000000..ccfb7dce9a7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/easyfloats/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/Master/texmf-dist/doc/latex/easyfloats/content/documentation.tex b/Master/texmf-dist/doc/latex/easyfloats/content/documentation.tex new file mode 100644 index 00000000000..6dd1d9b62dd --- /dev/null +++ b/Master/texmf-dist/doc/latex/easyfloats/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{