texlive[72699] Master/texmf-dist: easyfloats (29oct24)
commits+karl at tug.org
commits+karl at tug.org
Tue Oct 29 21:07:24 CET 2024
Revision: 72699
https://tug.org/svn/texlive?view=revision&revision=72699
Author: karl
Date: 2024-10-29 21:07:23 +0100 (Tue, 29 Oct 2024)
Log Message:
-----------
easyfloats (29oct24)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/easyfloats/README.md
trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats-file-list.txt
trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.bib
trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.pdf
trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/links.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/bibliography.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/description-links.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/examplecode.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/keydoc.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/macros.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/markdown.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/undescribed-keywords.tex
trunk/Master/texmf-dist/source/latex/easyfloats/easyfloats.dtx
trunk/Master/texmf-dist/tex/latex/easyfloats/easyfloats.sty
Added Paths:
-----------
trunk/Master/texmf-dist/doc/latex/easyfloats/content/f1_titlepage.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/s1_examples.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/s2_names.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/s3_documentation.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/s4_installation.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/s5_bug-reports-and-contributions.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/s6_changelog.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/s7_license.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/x1_motivation.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/x2_used-packages.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/x3_other-packages.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/license.txt
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/changelog.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/geometry.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/todo.tex
trunk/Master/texmf-dist/tex/latex/easyfloats/my_biblatex_data_model.dbx
Removed Paths:
-------------
trunk/Master/texmf-dist/doc/latex/easyfloats/content/bug-reports-and-contributions.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/documentation.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/examples.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/installation.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/license.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/motivation.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/names.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/other-packages.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/titlepage.tex
trunk/Master/texmf-dist/doc/latex/easyfloats/content/used-packages.tex
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/README.md
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/README.md 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/README.md 2024-10-29 20:07:23 UTC (rev 72699)
@@ -3,6 +3,7 @@
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.
+It also defines a new placement `I` similar to `H` which respects the indentation in an `itemize`.
# Documentation
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/bug-reports-and-contributions.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/bug-reports-and-contributions.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/bug-reports-and-contributions.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,41 +0,0 @@
-% !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}
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/documentation.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/documentation.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/documentation.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,1082 +0,0 @@
-% !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 `<key>`s or `<key>=<value>` 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 `(<env>) 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]{<options>}` or `\objectset[table]{<options>}`.
-
-A style is applied by using the corresponding environment (e.g.\ \env{figureobject} or \env{tableobject})
-or `\graphicobjectstyle{<style>}` for \cmd{\includegraphicobject}.
-
-New styles can be defined with `\NewObjectStyle` as explained in \cref{new-object-styles-and-types}.
-
-\subsubsection{Style groups}
-\label{style-groups}
-\DescribeMeta{group}
-
-This package defines one group of styles called `all` which contains all defined styles.
-
-When setting options one can use a group name instead of a style name.
-In that case the options are set for all styles in the group.
-
-\subsubsection{Options processing order}
-\label{options-processing-order}
-
-\begin{enumerate}
-\item Options set with `\objectset{<options>}` have the lowest priority.
-\item Options set for a specific style with `\objectset[<styles>]{<options>}` take precedence because they are set later (at the object, not the `\objectset` command).
-\item Options passed directly to the object have the highest priority.
-\end{enumerate}
-
-For example:
-
-\begin{examplecode}
-\objectset[figure]{placement=p}
-\objectset{placement=H}
-\objectset[table]{placement=htbp}
-\end{examplecode}
-
-Given the above preamble both figure- and tableobjects are floating.
-Tableobjects are allowed to be placed where they are specified in the source code.
-Figureobjects are put on a separate float page.
-The second line (which would disable floating) has no effect (unless you define a custom style) because it is overridden not only by the third but also the first line.
-
-
-\subsection{Environments}
-\label{environments}
-
-This package defines the following environments.
-Each of them takes exactly one mandatory argument,
-options as a comma separated key=value list.
-
-\subsubsection{`object` environment}
-\label{object-environment}
-\begingroup
-\keydocpath{/object}
-\DescribeEnv{object}
-The `object` environment is used internally by \env{figureobject} and \env{tableobject}.
-Don't use this directly.
-You can define more environments like `figureobject` or `tableobject` with \cmd{\NewObjectStyle} if needed.
-
-This environment redefines the `\caption` and `\label` commands to set the \key{caption}\slash `label` option so that you can use them as usual except you cannot create several labels.
-If you really need several labels for the same object put the additional `\label` command(s) inside of the caption argument, there `\label` has it's original meaning.
-The location or the order of `\caption` and `\label` inside of the object environment is not relevant.
-Nevertheless I recommend to always put the `\label` after the `\caption` as it is usually required in order to get the references right (if you choose to use these commands instead of the options).
-Where the caption is typeset (above or below the object) is determined by the float style.
-
-This environment takes the following options:
-\keydoc{type = <type>}{storing key}
-\DescribeMeta{type}
- The floating environment to use, e.g.\ `figure` or \env{table}.
-\keydoc[initial value=empty]{float style = plain | plaintop | ruled | boxed | <empty>}{storing key}
- How the object is supposed to look like,
- most importantly whether the caption is supposed to be above or below the object.
- See the \pkg{float} package for more information.
-
- If the value is empty the float type is *not* restyled before the\slash each object.
- However, this package restyles \env{table} to `plaintop` and `figure` to `plain` when it is loaded.
- The reasoning is explained in~\autocite{texexchange_caption_position}.
-
-\keydoc{caption = <text>}{storing key}
- The caption to place above or below the float.
-
- The appearance of the caption can be configured using `\captionsetup` defined by the \pkg{caption} package.
- The \pkg{caption} package is loaded automatically by this package.
-\keydoc{list caption = <text>}{storing key}
- The caption to place in the list of `<type>`s.
- If this is not given, the value of \key{caption} is used instead.
-\keydoc{details = <text>}{storing key}
- This is appended to the caption which is placed above or below the object but not to the list of `<type>`s.
- \begin{examplecodekey}
- caption=CTAN lion drawing by Duane Bibby,
- details=Thanks to \url{www.ctan.org}.
- \end{examplecodekey}
- is equivalent to
- \begin{examplecodekey\starred}{\ExamplecodeEscapeinside $ $}
- list caption=CTAN lion drawing by Duane Bibby,
- caption=CTAN lion drawing by Duane Bibby.$\\$ Thanks to \url{www.ctan.org}.
- \end{examplecodekey\starred}
-\keydoc[initial value=a full stop followed by a space]{details sep = <text>}{storing key}
- The separator to be placed between caption and details if details are given.
-\keydoc{label = <label>}{storing key}
- Defines a label to reference this object.
-\keydoc{add label = <label>}{storing key}
- Defines an additional label which can be used synonymously to label.
- If this key is given several times, only the last one will have an effect.
-\keydoc[initial value=empty]{placement = [htbp]+!? | H | <empty>}{storing key}
- The optional argument passed to the floating environment.
- Allowed values:
- \begin{itemize}
- \item any combination of the letters `htbp` (where no letter is occuring more than once), optionally combined with an exclamation mark.
- This means that the object will be a floating object.
- The order of the letters makes no difference.
- They have the following meanings:
- \begin{itemize}
- \item `h`: \LaTeX\ is allowed to place the object `h`ere, where it is defined.
- \item `t`: \LaTeX\ is allowed to place the object at the `t`op of a page.
- \item `b`: \LaTeX\ is allowed to place the object at the `b`ottom of a page.
- \item `p`: \LaTeX\ is allowed to place the object on a separate `p`age only for floats.
- \item `!`: \textcquote[page~27]{latex2e}{\LaTeX\ ignores the restrictions on both the number of floats that can appear and the relative amounts of float and non-float text on the page.}
- \end{itemize}
- \item `H`: \LaTeX\ places the object exactly here, no matter how unfitting that may be.
- In contrast to a single `h` or `h!` where the object is still a floating object which may float somewhere else if it does not fit here,
- `H` means here and nowhere else.
- `H` is defined by the \pkg{float} package which is loaded by this package automatically.
- \item empty: do *not* pass the optional argument.
- In this case the placement of the float can be changed using the `\floatplacement` command of the \pkg{float} package.
- I have defined this key instead of advertising `\floatplacement` because `\floatplacement` does not allow the value~`H`.
- \end{itemize}
-
-\keydoc[initial value=`\centering`]{align = <code>}{storing key}
- \TeX\ code which is inserted at the beginning of the `<type>` environment.
-\keydoc[initial value=empty]{exec = <code>}{storing key} /
-\keydoc{exec += <code>}{executed key}
- \TeX\ code which is inserted at the beginning of the `<type>` environment before align.
- Can be used to define a command for this object, see \cref{local-definitions-in-tables}.
-\keydoc{graphic <option> = <value>}{unknown key handler}
-\keylinktarget{graphic width}
- Is applied to \cmd{\includegraphicobject} and \cmd{\includegraphicsubobject}.
- Is ignored for other objects.
-
- `<option>` can be any key which is unique to one of these two commands and any key allowed by the `\includegraphics` command (see \pkg{graphicx}\slash \pkg{graphbox} package).
- Unlike `\setkeys{Gin}{<options>}` this works with all keys (compare \pkg{graphicx} documentation~\autocite[section~4.6]{graphicx}, unfortunately it's not getting more specific than \enquote{Most of the keyval keys}).
-
- I am checking if the key is existing immediately but I cannot check the value (only whether it is required).
- Therefore if you pass a wrong value the error message will not appear where you set this option but at the object where it is applied.
-
- If you set `graphic width` globally and want to override it locally you can use `graphic width=!`.
- This is a feature of the graphicx package but it is not well documented in it's documentation~\autocite{graphicx}.
- (Which is why I am mentioning it here.)
- The exclamation mark is mentioned for the `\resizebox` command.
-
-\bigpar
-
-\keydoc[initial value=empty]{env = <env>}{storing key}
- The name of an additional inner environment in which the body is wrapped, e.g.\ `tabular`, \env{tabularx}, `tikzpicture`.
- If empty the body is *not* wrapped in another environment (additional to object).
-
- Please note that using this option can lead to difficult to find errors with confusing error messages
- if you forget that you used it or it has a different value than you think it has.
- In this case `show env args` may help you.
-
- Please note that due to the way how environments are implemented in \LaTeX2 (this will change in \LaTeX3~\autocite{ltx3env})
- it is not possible to check whether a given name is an environment or a command.
- But if you pass something that is *not* defined you will get an error.
-
- If you have loaded the \pkg{longtable} package (either with the package option \pkgoptn{longtable} or with a `\usepackage{longtable}`)
- you can set the value of this key to \val{longtable}.
- In that case the necessary changes are performed
- so that the content of this object environment is set in a \env{longtable} environment
- and does *not* float but can span across page breaks.
- In this case `type`, `placement` and `align` are ignored.
-
-\keydoc{<env> arg = <value>}{unknown key handler}
-\keylinktarget{(<env>) arg(s) (+)}
-\keylinktarget{(<env>) arg(s)}
-\keylinktarget{tabularx arg+}
-\keylinktarget{tabularx arg}
-\keylinktarget{\detokenize{tabular* arg}}
-\keylinktarget{tabular arg}
-\NoDescribeKey{env arg}
- The value is wrapped in braces and passed as argument to the additional inner environment if the value of `env` is not empty and `<env>` equals the value of `env`.
- Arguments to this environment can be given as an argument to the `*object` environment as well but this key provides the possibility to pass arguments on a global level (or to override a globally passed argument).
- For example this can be used to give all tabularx-tables a consistent width:
-
- \begin{examplecode}
- % in preamble
- \objectset[table]{tabularx arg=.8\linewidth}
-
- % in document
- \begin{tableobject}{caption=Test Table, label=tab1, env=tabularx}{XX}
- ...
- \end{tableobject}
- \end{examplecode}
-
-\keydoc{<env> args = <value>}{unknown key handler}
- Same like `<env> arg` except that the value is *not* wrapped in braces.
- This can be used to pass several arguments or an optional argument.
- Please not that this key cannot be used to pass exactly one undelimited argument consisting of more (or less) than one token because `\pgfkeys` (which I am using internally) strips several levels of braces.
-\keydoc{arg = <value>}{unknown key handler}
- If `env` has a non-empty value this is an abbreviation of `<env> arg` where `<env>` is the value of `env`.
-
- Please note that because this key depends on the value of another key the order in which these two keys are given is important.
-
- The value of `env` is considered when this key is evaluated.
- If you use `\objectset[<styles>]{<options>}` (with it's optional argument) the processing of the keys is delayed but it makes some basic error handling already so that the line numbers are as fitting as possible.
- For this error handling only the options passed to this call of the command are considered.
- (Trying to consider previously set values correctly would make things more difficult because you might be applying these options to several styles at once where one might have `env` set and another not.)
- Therefore the following causes an error message:
-
- \begin{examplecode}
- \objectset[table]{env=tabularx}
- \objectset[table]{arg=.8\linewidth}
- \end{examplecode}
-
- While this would not:
-
- \begin{examplecode}
- \objectset{env=tabularx}
- \objectset{arg=.8\linewidth}
- \end{examplecode}
-
- Anyway, I recommend to always use this option directly after `env` (if you intend to use it).
- `env` and it's `args` belong together:
-
- \begin{examplecode}
- \objectset{env=tabularx, arg=.8\linewidth}
- \end{examplecode}
-
-\keydoc{args = <value>}{unknown key handler}
- If `env` has a non-empty value this is an abbreviation of `<env> args` where `<env>` is the value of `env`.
- The notes on error handling of the `arg` key apply to this key as well.
-\keydoc{(<env>) arg(s) += <value>}{unknown key handler}
- A plus sign can be appended to the key (patterns) `<env> arg`, `<env> args`, `args` and `arg`.
- In that case a possibly previously passed argument is not overridden but this value is appended to it.
- For example the following pattern allows to easily switch between tabular and tabularx tables on a global level:
-
- \begin{examplecode}
- % in preamble
- \objectset[table]{tabularx arg=.8\linewidth, env=tabularx}
- \newcolumntype{Y}{>{\raggedleft\arraybackslash}X}
-
- % in document
- \begin{tableobject}{caption=Test Table, label=tab1, tabular arg=lr, tabularx arg+=XY}
- ...
- \end{tableobject}
- \end{examplecode}
-
-\bigpar
-
-\keydoc{first head = <code>}{storing key}
- Is inserted at the beginning of the object (if `env` is non-empty: inside of the inner environment and after possibly specified `(<env>) arg(s)`).
- If this is not given, `head` is used instead.
-\keydoc{last foot = <code>}{storing key}
- Is inserted at the end of the object (if `env` is non-empty: inside of the inner environment).
- If this is not given, `foot` is used instead.
-\keydoc[initial value=empty]{head = <code>}{storing key}
- This value is used for `first head` if `first head` is not given.
- If `env=longtable` this is the head after a pagebreak inside of the table.
-\keydoc[initial value=empty]{foot}{storing key}
- This value is used for `last foot` if `last foot` is not given.
- If `env=longtable` this is the foot before a pagebreak inside of the table.
-\keydoc{table head = <code>}{executed key}
- This is a convenience key which sets `first head`, `last foot`, `head` and `foot`.
- The value is the column headers without rules\slash lines and without the trailing `\\`.
-\keydoc{table break text = <text>}{storing key}
- A text put in the `foot` by `table head`.
-\keydoc{table head style = <code>}{executed key}
- Defines how `table head` fills out `first head`, `last foot`, `head` and `foot`.
-
- Initial value:
-
- \begin{examplecode}
- {%
- first head =
- \toprule
- #1 \\
- \midrule,
- head =
- #1 \\
- \midrule,
- foot =
- \midrule
- \ifx\object at tableBreakText\@empty
- \else
- \multicolumn{\the\LT at cols}{r@\relax}{\object at tableBreakText}%
- \fi,
- last foot =
- \bottomrule,
- }
- \end{examplecode}
-
- (Note the curly braces which are required because the value contains commas and equal signs, see \cref{special-characters-in-options}.
- `\the\LT at cols` is the number of columns of the longtable and `\object at tableBreakText` is the value of `table break text`.
- Commands containing an @ in their name are internal commands and can only be used between `\makeatletter` and `\makeatother`, see also \autocite{texexchange_make_at}.)
-
-\bigpar
-
-\keydoc[initial value=`false`, default value=`true`]{show env args =? true | false}{boolean key}
- Show the code which is assembled from the `env` and `(<env>) arg(s) (+)` keys before executing it.
- See \cref{help}.
- Please note that arguments may be given as additional arguments and not as `(<env>) arg(s) (+)` like in `\begin{tableobject}{env=tabular}{cl}`.
- Such arguments are *not* shown by this key.
- This key applies to subobjects as well.
-
-\keydoc[initial value=`true`, default value=`true`]{warn no caption =? true | false}{boolean key}
- Give a warning if \key{caption} is *not* given.
-\keydoc[initial value=`true`, default value=`true`]{warn no label =? true | false}{boolean key}
- Give a warning if `label` is *not* given.
-\keydoc[initial value=`false`, default value=`true`]{warn other env =? true | false}{boolean key}
- Give a warning when `<env> args` is given if `env` does not have the value `<env>` and the value of `env` is not empty.
- This applies to subobjects as well.
-
- The \cmd{\objectset} command if used with it's optional argument does not set the options immediately but stores them in different macros for different object styles.
- Therefore if you change this value for certain styles this change does not affect following `\objectset` commands.
- Without the optional style argument, however, the change takes effect immediately.
-
- In order to avoid duplicates this warning is printed only where the key is passed by the user
- and *not* where it is applied implicitly because of a previous `\objectset[<styles>]{<options>}`.
-
-\keydoc[initial value=`false`, default value=`true`]{contains subobjects =? true | false}{boolean key} /
-\keydoc{sub =? true | false}{forwarding key}
- Specifies that this object contains subobjects, see \cref{subobject-environment}.
- Is relevant only if `env` is set.
- The value of `env` is applied to the subobjects instead of this object.
- This is not executed immediately but only after all options have been processed so that you do not need to pay special attention to pass `env` before `contains subobjects`.
-
- If this is *not* given (or more precisely: if this is false)
- and the value of `env` is *not* empty I look ahead whether the object contains a subobject.
- If I find a subobject I pretend you had passed this option and print a warning.
- I insist on you explicitly passing this option because the lookahead does not work in all situations.
- It ignores space and `\par` tokens but if there is any other token before the subobject,
- for example a `\small` to fit two tables side by side which are a little too wide
- (which may not be the best solution but an easy quick fix)
- or a `\typeout` for debugging,
- the lookahead does not find the subobject (possibly) resulting in unpredictable errors.
- For example if you set `env=tabular` it will most likely complain about an \errormessage{Illegal pream-token}
- or about a \errormessage{Missing number, treated as zero} with `env=tabular*` because the required arguments are missing.
-\endkeydoc
-
-
-All `(<env>) arg(s) (+)` options apply to subobjects as well.
-
-Additionally the following options are passed through to the corresponding options of all subobjects inside of this object, they are all \keytype[forwarding key]{forwarding keys}.
-\newcommand{\TargetKey}[2]{/subobject/\stripsubobject #2\relax}%
-\def\stripsubobject subobject #1\relax{\stripoptplus{#1}}%
-See \env{subobject} environment.
-\forwardingkeydoc{subobject linewidth = <dimen>}
-\forwardingkeydoc{subobject sep = <code>}
-\forwardingkeydoc{subobject hor =? <code>}
-\forwardingkeydoc{subobject hor sep (+)= <code>}
-\forwardingkeydoc{subobject ver =? <code>}
-\forwardingkeydoc{subobject ver sep (+)= <code>}
-\forwardingkeydoc{subobject exec (+)= <code>}
-\forwardingkeydoc{subobject env = <env>}
-\forwardingkeydoc[target=/subobject/subcaptionbox]{subcaptionbox}
-\forwardingkeydoc[target=/subobject/subcaptionbox inner pos]{subcaptionbox inner pos = c | l | r | s | <empty>}
-\forwardingkeydoc[target=/subobject/subpage]{subpage}
-\forwardingkeydoc[target=/subobject/subpage outer pos]{subpage outer pos = c | t | b | T | B | auto | Auto | <empty>}
-\forwardingkeydoc[target=/subobject/subpage height]{subpage height = <dimen>}
-\forwardingkeydoc[target=/subobject/subpage inner pos]{subpage inner pos = c | t | b | s | <empty>}
-\forwardingkeydoc[target=/subobject/subpage align]{subpage align = <code>}
-
-\forwardingkeydoc{subobject warn no caption =? true | false}
-\forwardingkeydoc{subobject warn no label =? true | false}
-\endkeydoc
-\endgroup
-
-
-\subsubsection{`figureobject` environment}
-\label{figureobject-environment}
-\DescribeEnv{figureobject}
-Is used for inserting figures.
-Takes the same options like the \env{object} environment.
-It differs in the following initial values:
-\begin{itemize}
-\item `type=figure`
-\end{itemize}
-
-\subsubsection{`tableobject` environment}
-\label{tableobject-environment}
-\DescribeEnv{tableobject}
-Is used for inserting tables.
-Takes the same options like the \env{object} environment.
-It differs in the following initial values:
-\begin{itemize}
-\item `type=table`
-\end{itemize}
-
-
-\subsubsection{`subobject` environment}
-\label{subobject-environment}
-\begingroup
-\keydocpath{/subobject}
-\DescribeEnv{subobject}
-To be used inside of an `*object` environment if you want to place several images\slash tables\slash whatever together.
-See also \cmd{\includegraphicsubobject}.
-
-I recommend to *not* put anything between the subobjects manually so that you can control their positioning with the `hor` and `ver` options.
-(Spaces after a subobject are ignored but empty lines are not.)
-
-Unlike the `object` environment, `\caption` and `\label` *cannot* be used inside of the subobject environment.
-Use the \key{caption} and `label` options instead.
-
-There are two different backends available, both provided by the \pkg{subcaption} package.
-See the `subcaptionbox` and `subpage` keys.
-
-The `subobject` environment has exactly one mandatory argument, a comma separated list of the following options.
-
-
-The following options correspond to those of an `object`.
-See \cref{object-environment}.
-\newcommand{\TargetKey}[2]{/object/#2}%
-\correspondingkeydoc{label = <label>}{storing key}
-
-\correspondingkeydoc{caption = <text>}{storing key}
-
-\correspondingkeydoc{list caption = <text>}{storing key}
-
- (The \pkg{subcaption} package disables subcaptions in the list of figures\slash tables\slash whatever by default.
- To enable them use `\captionsetup[sub]{list=true}`.)
-\correspondingkeydoc{details = <text>}{storing key}
-
-\correspondingkeydoc{details sep = <text>}{storing key}
-
-\correspondingkeydoc{exec = <code>}{storing key} /
-\correspondingkeydoc{exec += <code>}{executed key}
-
-\correspondingkeydoc{graphic <option> = <value>}{unknown key handler}
-
- (This key is completely useless.
- It only has a meaning in the context of \cmd{\includegraphicsubobject} but there these options can be used directly without the prefix `graphic`.
- I am allowing it anyway in order to support the same key like in \cmd{\objectset} which is supported by \cmd{\includegraphicobject} as well.)
-\correspondingkeydoc{env = <env>}{storing key}
-
- (See also the `contains subobjects` option of the \env{object} environment.)
-\correspondingkeydoc{(<env>) arg(s) (+) = <value>}{unknown key handler}
-
- (All values passed to the corresponding keys of the \env{object} environment apply to this option, too.)
-
-\correspondingkeydoc{warn no caption =? true | false}{boolean key}
-
-\correspondingkeydoc{warn no label =? true | false}{boolean key}
-
-\forwardingkeydoc[target=/object]{warn other env =? true | false}
-
-\forwardingkeydoc[target=/object]{show env args =? true | false}
-
-\endkeydoc
-
-The following options are unique for the `subobject` environment:
-\keydoc[initial value=`.5\linewidth`]{linewidth = <dimen>}{storing key}
- The horizontal space available for the subobject.
- The content of the subobject is centered within this width.
- If two subobjects displayed side by side have a small width they may appear too far apart from each other with the initial value.
- Then you can decrease this value so that they come closer together.
- (With `subcaptionbox` this value may be empty.
- In that case the subobject takes as much space as it needs
- and `\linewidth` inside of the subobject is the same like in the parent object.)
-
- If you want to place more than two subobjects side by side you must decrease this value accordingly.
- Keep in mind that you need to consider the width of `hor sep` as well if you changed it.
-
- Dimensions can be given relative to other dimensions or in numbers.
- Aside from absolute units like `pt` or `cm` \TeX\ also recognizes units relative to the current font size: `em` and `ex`.
- For more information on dimensions see \mycite[chapter~10]{texbook} or \mycite[chapter~8]{texbytopic}.
-
-\keydoc{sep = <code>}{storing key}
- A separator which is inserted before each subobject except for the first subobject inside of the current parent object.
-
-\keydoc[default value=empty]{hor =? <code>}{executed key}
- Set the value of `sep` to the value of `hor sep` so that the subobjects are placed side by side.
- If you pass a value the value will be appended to `sep` after setting it to `hor sep`.
-
- Please note that options are only valid until the end of a group.
- Therefore if you use this inside of a subobject it does *not* apply for the following subobject.
- Instead use `subobject hor` on the parent object.
-
-\keydoc[initial value=empty]{hor sep = <code>}{storing key} /
-\keydoc{hor sep += <code>}{executed key}
- The separator to be used if the subobjects are suppossed to be placed side by side.
-
- Please note that `hor` must be used *after* setting this key, otherwise this option will not take effect.
-
-\keydoc[default value=empty]{ver =? <code>}{executed key}
- Set the value of `sep` to the value of `ver sep` so that the subobjects are placed below each other.
- If you pass a value the value will be appended to `sep` after setting it to `ver sep`.
-
- Please note that options are only valid until the end of a group.
- Therefore if you use this inside of a subobject it does *not* apply for the following subobject.
- Instead use `subobject ver` on the parent object.
-
-\keydoc[initial value=`\par\bigskip`]{ver sep = <code>}{storing key} /
-\keydoc{ver sep += <code>}{executed key}
- The separator to be used if the subobjects are suppossed to be placed below each other.
-
- Please note that `ver` must be used *after* setting this key, otherwise this option will not take effect.
-
-\bigpar
-
-\keydoc{subcaptionbox}{executed key}
- The \pkg{subcaption} package provides several possibilities to insert subobjects.
- This option tells the subobject environment to use the `\subcaptionbox` command instead of the `subfigure` or `subtable` environment, see option `subpage`.
- (This key does *not* take a value.)
-
- This option allows to pass an empty value to `linewidth`.
- It can be useful if you have subobjects with a small width
- so that you don't need to try different `subobject linewidth`s.
- The example in \cref{subobjects-2} could be rewritten as following:
-
- \begin{examplecode}
- \documentclass{article}
- \usepackage{easyfloats}
-
- \objectset[table]{%
- env = tabular,
- subcaptionbox,
- subobject linewidth =,
- subobject hor = \qquad,
- }
- \captionsetup[sub]{list=true}
-
- \begin{document}
- \begin{tableobject}{contains subobjects,
- caption = Two test tables,
- label = tabs abc 123,
- }
- \begin{subobject}{caption=Abc \& 123, arg=rl}
- \toprule
- abc & 123 \\
- de & 45 \\
- f & 6 \\
- \bottomrule
- \end{subobject}
- \begin{subobject}{caption=123 \& abc, arg=lr}
- \toprule
- 123 & abc \\
- 45 & de \\
- 6 & f \\
- \bottomrule
- \end{subobject}
- \end{tableobject}
- \end{document}
- \end{examplecode}
-
- Note that this works only if the subobject captions are very short.
- If they are wider than the subobjects the line breaks which looks ugly.
-
- If you want to use this option with `env=tabular` (or similar) you must pass the column specification with the option `arg=lr` (instead of as a separate argument).
- Otherwise you will get the error message \errormessage{Package array Error: Illegal pream-token (\BODY): `c' used.}
-
- This option is *not* compatible with `env=tabularx` and does not allow verbatim content inside of the subobject.
-
-\keydoc{subcaptionbox inner pos = c | l | r | s | <empty>}{storing key}
- The horizontal position of the content in the box.
- Also allowed is any justification defined with `\DeclareCaptionJustification`
- (see the \pkg{caption} package documentation).
- An empty value means that this optional argument is
- *not* passed to the `\subcaptionbox` command.
- This option has no effect if `linewidth` is empty.
- I discourage using this option because it destroys
- the alignment of (sub)object and (sub)caption.
-
-\bigpar
-
-\keydoc{subpage}{executed key}
- This is (after `subcaptionbox`) the second and nowadays initial backend for the `subobject` environment.
- It uses the `subfigure`\slash `subtable` environment defined by the \pkg{subcaption} package.
- (This key does *not* take a value.)
-
- The `subfigure` and `subtable` environments are minipages and take the same arguments
- which can be set with `linewidth`, `subpage outer pos`, `subpage height` and `subpage inner pos`.
-
-\keydoc[initial value=`auto`]{subpage outer pos = c | t | b | T | B | auto | Auto | <empty>}{storing key}
- The vertical position of the minipage on the baseline.
-
- Additionally to the values `t`, `c` and `b` supported by the minipage environment
- the \pkg{subcaption} package v1.2 adds the allowed values `T` and `B`
- and this key also allows the values `auto`, `Auto` and empty.
-
- While `t` and `b` align the top\slash bottom *baseline* of the content
- `T` and `B` align the very top\slash bottom of the content.
-
- `c` aligns the center of the content.
-
- `auto` means `t` if the caption is displayed at the top
- or `b` if the caption is displayed at the bottom
- so that the captions are aligned
- (same behavior like `subcaptionbox`).
-
- If a subobject has neither caption nor label `auto` may not work as expected.
- Instead `Auto` can be used which is based on `T` and `B` instead of `t` and `b`.
- Note that `Auto` requires version 1.2 or newer of the \pkg{subcaption} package.
-
- Empty is equivalent to `c`.
-
- Invalid values are silently ignored and are equivalent to `c`.
-
-
-\keydoc[initial value=empty]{subpage height = <dimen>}{storing key}
- The height of the minipage.
- An empty value means that this optional argument is
- *not* passed to the `subfigure`\slash `subtable` environment.
-
- Dimensions can be given relative to other dimensions or in numbers.
- Aside from absolute units like `pt` or `cm` \TeX\ also recognizes units relative to the current font size: `em` and `ex`.
- For more information on dimensions see \mycite[chapter~10]{texbook} or \mycite[chapter~8]{texbytopic}.
-
-\keydoc[initial value=empty]{subpage inner pos = c | t | b | s | <empty>}{storing key}
- The vertical position of the content on the minipage.
- Empty means that this optional argument is
- *not* passed to the `subfigure`\slash `subtable` environment.
- This option has no effect if `subpage height` is empty.
-
-\keydoc[initial value=`\centering`]{subpage align = <code>}{storing key}
-
- \TeX\ code which is inserted at the beginning of the `subfigure`\slash `subtable` environment.
-\endkeydoc
-
-If you want to change the numbering of subobjects please refer to the \pkg{subcaption} package documentation~\autocite[section~5 \sectionname{The `\DeclareCaptionSubType` command}]{subcaption}.
-The \pkg{subcaption} package is loaded automatically by this package.
-\endgroup
-
-
-\subsection{Commands}
-\label{commands}
-
-In this section I am describing the commands defined by this package.
-
-
-\subsubsection{`\includegraphicobject` command}
-\label{includegraphicobject-command}
-\begingroup
-\keydocpath{/graphicobject}
-\DescribeMacro{\includegraphicobject}
-`\includegraphicobject{<filename>}` \\
-`\includegraphicobject[<options>]{<filename>}` \\
-`\includegraphicobject[<style>][<options>]{<filename>}`
-
-Is used for inserting graphics from a different file.
-It is very similar to \pkg{graphicx}' `\includegraphics` command, except that the graphic is automatically set in a \env{figureobject} environment.
-You can change this by setting the object style with \cmd{\graphicobjectstyle} or an additional optional argument given *before* the usual optional argument.
-The mandatory argument is the same: The name of the graphics file to include *without* the file extension.
-The optional argument accepts---aside from all the options defined by \pkg{graphicx}\slash \pkg{graphbox}---also all options of the \env{figureobject} environment.
-Additionally there are the following unique options:
-\keydoc[initial value=`true`, default value=`true`]{auto caption =? true | false}{boolean key}
- If no \key{caption} is given the file name is used as caption.
- All underscores in the file name are replaced by `\textunderscore`.
- This option is intended to be used on a global level but works in the optional argument of this command as well.
-\keydoc[initial value=`false`, default value=`true`]{auto caption strip path =? true | false}{boolean key}
- If `auto caption` is true and the file name is used as caption
- a possibly leading path is stripped (everything before and including the last slash in `<filename>`).
- This is initially false because I am assuming that in most cases where the path should not be displayed `\graphicspath{{path/}}` would be used.
-\keydoc[initial value=`true`, default value=`true`]{auto label =? true | false}{boolean key}
- If no `label` is given the file name is used as label.
- This option is intended to be used on a global level but works in the optional argument of this command as well.
-\keydoc[initial value=`false`, default value=`true`]{auto label strip path =? true | false}{boolean key}
- If `auto label` is true and the file name is used as label
- a possibly leading path is stripped (everything before and including the last slash in `<filename>`).
- This is initially false because I am assuming that in most cases where the filename without path is unique `\graphicspath{{path/}}` would be used.
-\keydoc[initial value=`true`, default value=`true`]{warn env =? true | false}{boolean key}
- Give a warning if `env` is not empty.
-\keydoc[initial value=`true`, default value=`true`]{no env =? true | false}{boolean key}
- Reset `env` to an empty value.
- This happens after evaluating `warn env`.
-\endkeydoc
-
-You may not use this command inside of an `*object` environment.
-Otherwise you will get an \errormessage{object environment may not be nested} error.
-See also \cmd{\includegraphicsubobject}.
-\endgroup
-
-\subsubsection{`\includegraphicsubobject` command}
-\label{includegraphicsubobject-command}
-\DescribeMacro{\includegraphicsubobject}
-`\includegraphicsubobject{<filename>}` \\
-`\includegraphicsubobject[<options>]{<filename>}`
-
-To be used if you want to place several graphics from different files in one object.
-
-It takes the same options like \cmd{\includegraphicobject} except that it takes options for the \env{subobject} environment instead of options for the `object` environment.
-Also it does *not* take the optional `<style>` argument.
-
-You may not use this command outside of an `*object` environment.
-Otherwise you will get a \errormessage{subobject environment may not be used outside of an object} error.
-See also \cmd{\includegraphicobject}.
-
-
-\subsubsection{Setting options globally}
-\label{setting-options-globally}
-
-\DescribeMacro{\objectset}
-`\objectset{<options>}` \\
-`\objectset[<styles>]{<options>}`
-
-Sets the passed options for all following objects until the end of the current group.
-All options of the \env{object} environment are allowed.
-
-A comma separated list of styles or style groups can be given in an optional argument.
-In that case the options are not set immediately but appended to the specified style(s).
-The options are set locally for any following object of the specified style(s) in the same group.
-Although setting the options is delayed the options are checked immediately so that error messages and warnings point to the line where the option is specified in the code, not where it is technically set.
-(In order for that to work properly it is important that options are specified with the key name only and not with the full path, see \cref{key-name-vs-key-path}.)
-However, the value can usually *not* be checked immediately, only whether it is required or not.
-Therefore if you pass a wrong value the error message will not appear where you set this option but at the object where it is applied.
-An exception is the key `env` where the value is checked immediately for plausibility whether it might be the name of an environment.
-
-If `<styles>` is empty or an empty group the options are not applied.
-No error or warning is printed.
-
-There is a style group called `all` which all styles belong to.
-`\objectset{<options>}` and `\objectset[all]{<options>}` are mostly equivalent
-except that the former (without optional argument) is more efficient because it sets the options immediately
-and the latter (with the optional argument given) is able to override options set for a style.
-
-
-\DescribeMacro{\graphicobjectstyle}
-`\graphicobjectstyle{<style>}` can be used to change the object style used by \cmd{\includegraphicobject}.
-For example, if you have a single table in a file called \filename{catcodes.pdf} you can insert it as following.
-Alternatively, you can use the optional `<style>` argument.
-
-\begin{examplecode}
-\begingroup
-\graphicobjectstyle{table}
-\includegraphicobject[caption=Catcodes]{catcodes}
-\endgroup
-\end{examplecode}
-
-
-\DescribeMacro{\graphicspath}
-`\graphicspath{{path/}}`: see \pkg{graphicx} package documentation~\autocite[section~4.5]{graphicx}.
-
-
-\subsubsection{New object styles and types}
-\label{new-object-styles-and-types}
-
-This section explains how to define a new object `<style>` in the sense of \cref{styles}.
-It is *not* about how to define a new `<floatstyle>` which can be used as value for the `float style` key.
-
-\DescribeMacro{\NewObjectStyle}
-`\NewObjectStyle{<style>}{<options>}`
-defines a new environment called `<style>object` analogous to `figureobject` and `tableobject`.
-`<options>` are set for the new object style as if you had used `\objectset[<style>]{<options>}`.
-You must always specify the `type`.
-If this package is loaded without `allowstandardfloats`
-the float environment which is passed to `type` is redefined to issue a warning that `<style>object` should be used instead.
-This warning should not influence the environment's usual behavior.
-If the float environment was already passed as `type` to a previous call of `\NewObjectStyle` it is not redefined again but `<style>object` is appended to the list of replacement suggestions.
-
-If you define a new object style you may also want to define a new float type.
-The \pkg{float} package (which is automatically loaded by this package) defines the following command for doing so:
-
-\DescribeMacro{\newfloat}
-`\newfloat{<type>}{<placement>}{<ext>}[<within>]`
-\begin{itemize}
-\item `<type>` is the floating environment to be defined.
- This value is also used as the float name which is displayed in front of the caption, therefore it should be capitalized.
- Alternatively the name can be changed using `\floatname{<type>}{<name>}`.
-\item `<placement>` is the value to be used if the `placement` key is not given (or has an empty value).
- This is initially `tbp` for the standard float types.
-\item `<ext>` is the extension of a file used to save the list of `<type>`s.
- This is `lof` (list of figures) for `type=figure` and `lot` (list of tables) for `type=table`.
- This file extension should be unique.
-\item `<within>` is a counter whose value is prepended to the `<type>` counter. The `<type>` counter is reset every time the `<within>` counter is incremented.
-\item Make sure an appropriate default float style is active when using `\newfloat`.
- The default float style can be activated using `\floatstyle{<floatstyle>}`, see the \pkg{float} package documentation~\autocite{float}.
- It should be `plain` for something like an image or `plaintop` for something like a table.
- The reasoning is explained in~\autocite{texexchange_caption_position}.
- Alternatively you can specify the float style using the `float style` key in the `<options>` of `\NewObjectStyle`.
-\end{itemize}
-
-`\NewObjectStyle` automatically defines the corresponding environment needed for `subobject` if possible, i.e.\ if the \pkg{caption} package is new enough.
-If the \pkg{caption} package is older than August~30, 2020 and you want to use subobjects you need to define the subtype manually by putting the following line *before* loading this package \autocite{texexchange_subtype_workaround}:
-\begin{examplecode}
-\AtBeginDocument{\DeclareCaptionSubType{<type>}}
-\end{examplecode}
-
-\DescribeMacro{\trivfloat}
-The \pkg{trivfloat} package provides the `\trivfloat{<type>}` command which is an easier alternative to `\newfloat`.
-If you use it you should be aware that it does not define the new float type environment immediately but at `\begin{document}`.
-This does *not* affect `\NewObjectStyle` (you can still use it directly afterwards)
-but it means that the float style active at `\begin{document}` is applied and not the float style active at `\trivfloat`.
-Therefore I recommend to pass the `float style` option to `\NewObjectStyle`,
-then it does not matter which float style was active when the float type was defined because it is restyled before each use of an object where this option applies.
-`\trivfloat` must be used before `\AtBeginDocument{\DeclareCaptionSubType{<type>}}`.
-
-\DescribeMacro{\DeclareFloatingEnvironment}
-The \pkg{newfloat} package provides the `\DeclareFloatingEnvironment[<options>]{<type>}` command which is a newer alternative to `\newfloat` and `\trivfloat`.
-With it's key=value options it is more intuitive than `\newfloat` and more flexible than `\trivfloat`.
-Unlike `\newfloat` and `\trivfloat` it automatically capitalizes `<type>` before using it as float name.
-It seems to ignore `\floatstyle` so you need to specify that in the options.
-The \pkg{newfloat} package is written by the same author like the \pkg{subcaption} package so you don't need to worry about defining subtypes manually.
-
-
-\subsubsection{New object style groups}
-\label{new-object-style-groups}
-
-Several object styles can be combined to a group.
-You can set options for all styles contained in a group using `\objectset[<group>]{<options>}`.
-
-\DescribeMacro{\NewObjectStyleGroup}
-`\NewObjectStyleGroup{<group>}{<styles*>}`
-defines a new style group consisting of the styles `<styles*>`.
-`<styles*>` is a comma separated list of styles.
-In contrast to `<styles>` it may *not* contain style groups.
-
-\DescribeMacro{\AddObjectStyleToGroup}
-`\AddObjectStyleToGroup{<group>}{<style>}`
-adds an existing style to an existing group.
-
-
-\subsubsection{Hooks}
-\label{hooks}
-
-This package provides several commands similar to `\AtBeginDocument`
-which take one argument, \TeX\ code which is executed at a later point in time.
-
-
-\DescribeMacro{\AtBeginObject}
-`\AtBeginObject{<code>}`
- runs `<code>` every time at the begin of an \env{object} environment
- (including \env{figureobject}, \env{tableobject} and \cmd{\includegraphicobject}).
- This hook is inside of the group but before any options are processed.
-
-\DescribeMacro{\AtBeginSubobject}
-`\AtBeginSubobject{<code>}`
- runs `<code>` every time at the begin of a \env{subobject} environment
- (including \cmd{\includegraphicsubobject}).
- This hook is inside of the group but before any options are processed.
-
-\DescribeMacro{\AtBeginGraphicObject}
-`\AtBeginGraphicObject{<code>}`
- runs `<code>` every time in \cmd{\includegraphicobject} and \cmd{\includegraphicsubobject}.
- This hook is after the object\slash subobject hook but before any options are processed.
-
-
-\subsection{Initialization}
-\label{initialization}
-
-This package uses the \pkg{float} package to restyle \env{table} to `plaintop` and `figure` to `plain`
-so that captions of tables appear always above the table and captions of figures always below the figure.
-The reasoning is explained in~\autocite{texexchange_caption_position}.
-If you really want to place captions differently you can do that with `\restylefloat` (see \pkg{float} package documentation~\autocite{float}) or by setting the `float style` option.
-However, I would advice to rethink why you would want to do that.
-
-Unless this package is loaded with the \pkgoptn{allowstandardfloats} option
-it redefines the \env{table} and `figure` environments to issue a warning if they are used directly.
-This warning should not influence their usual behavior, though.
-Instead of \env{table}\slash `figure` you should use \env{tableobject}\slash \env{figureobject} or \cmd{\includegraphicobject},
-otherwise this package cannot help you.
-
-Unless this package is loaded with the \pkgoptn{nographic} option
-it loads the \pkg{graphicx} package in order to include graphics.
-It also guarantees that the paper size of the generated pdf matches \LaTeX' point of view (instead of depending on the system settings).
-
-Unless this package is loaded with the \pkgoptn{noarray} option
-it loads the \pkg{array} package which defines additional column specification features like `>{<prefix>}`, `<{<suffix>}` and `!{<addcolsep>}`
-and the `\newcolumntype{<col>}[<args>]{<spec>}` command.
-It also changes the implementation of how lines (rules) are drawn
-but that is irrelevant if you use the recommendations given in the \pkg{booktabs} package documentation~\autocite[section~2 \sectionname{The layout of formal tables}]{booktabs}.
-Loading the \pkg{array} package is merely for convenience. This package does not use any of it's features.
-
-Unless this package is loaded with the \pkgoptn{nobooktabs} option
-it loads the \pkg{booktabs} package which defines commands for formatting tables, most importantly `\toprule`, `\midrule` and `\bottomrule`.
-These are used by the `table head` key unless you redefine it using `table head style`.
-
-Other packages loaded by this package are listed in \cref{used-packages}.
-
-
-\subsection{Package options}
-\label{package-options}
-
-The package options are implemented using the standard \LaTeX\ package options handling functionality as described in~\autocite{clsguide}.
-Therefore they do *not* take any values but consist of keys only.
-Instead I usually provide two separate keys, one which enables an option and another which disables the option.
-The keys with a~\radioon\ are active by default and the keys with a~\radiooff\ are inactive by default.
-
-\pkgoptndoc*{graphicx} use the \pkg{graphicx} package as backend for \cmd{\includegraphicobject}.
-\pkgoptndoc{graphbox} use the \pkg{graphbox} package as backend for \cmd{\includegraphicobject}.
-\pkgoptndoc{nographic} do not load \pkg{graphicx} or \pkg{graphbox}.
- If you use this option \cmd{\includegraphicobject} and \cmd{\includegraphicsubobject} are not defined.
-
- Warning: Without driver specific packages like \pkg{graphicx}, \pkg{geometry} or \pkg{hyperref} the paper size of the resulting pdf depends on the system settings, independent of what you set in \LaTeX. \autocite{texexchange_papersize}
-
-\pkgoptndoc*{array} load the \pkg{array} package.
- There is no difference between using this package option or a separate `\usepackage{array}`.
-\pkgoptndoc{noarray} do *not* load the \pkg{array} package.
-
-\pkgoptndoc*{booktabs} load the \pkg{booktabs} package.
- There is no difference between using this package option or a separate `\usepackage{booktabs}`.
-\pkgoptndoc{nobooktabs} do *not* load the \pkg{booktabs} package.
- Please note that the `table head` key initially relies on the booktabs package.
- If you want to use it with this package option you need to redefine it with `table head style`.
-
-\pkgoptndoc{longtable} load the \pkg{longtable} package.
- There is no difference between using this package option or a separate `\usepackage{longtable}`.
-\pkgoptndoc*{nolongtable} do *not* load the \pkg{longtable} package.
-
-\pkgoptndoc{allowstandardfloats} do not redefine the \env{table} and `figure` environments.
- Without this option they are redefined to issue a warning if they are used directly.
- This warning should not influence their usual behavior.
- Instead of \env{table}\slash `figure` you should use \env{tableobject}\slash \env{figureobject} or \cmd{\includegraphicobject},
- otherwise this package cannot help you.
-\endpkgoptndoc
-
-
-\subsection{Help}
-\label{help}
-
-If you get an error message and don't understand where it comes from
-or the output is different from what you expected
-the following features may give you a better understanding of what this package is doing.
-These features are based on the \TeX\ primitive `\show`.
-
-\DescribeMacro{\show}
-`\show` shows (among other information) the parameter text and the replacement text of a macro on the terminal and in the log file.
-If you use one of the following features you most likely want to know the replacement text which is the part between `->` and the last `.` on the line.
-In errorstopmode mode (i.e.\ without `--interaction=nonstopmode` which most IDEs pass by default) \TeX\ stops after `\show` and waits until you confirm that you have read the information and it may proceed by pressing enter.
-For more information see \mycite[section~34.1]{texbytopic}.
-
-\DescribeHandler{.show value}
-The `.show value` handler can be used to show the value of a \keytype{storing key}
-(see \pkg{pgfkeys} documentation~\autocite[section~87.4.9 \sectionname{Handlers for Key Inspection}]{tikz}).
-For example:
-
-\begin{examplecode}
-\includegraphicsubobject[sep/.show value]{<filename>}
-\end{examplecode}
-
-\DescribeHandler{.show boolean}
-This package also defines a new handler called `.show boolean` which can be used to show the value of a \keytype{boolean key}.
-For example:
-
-\begin{examplecode}
-\objectset{warn other env/.show boolean}
-\end{examplecode}
-
-\DescribeMacro{\ShowObjectStylesInGroup}
-`\ShowObjectStylesInGroup{<group>}` shows all object styles which are contained in the given group.
-The styles are wrapped in curly braces so that I can iterate over them with the \LaTeX\ command `\@tfor`.
-
-\DescribeMacro{\ShowObjectStyleOptions}
-`\ShowObjectStyleOptions{<style>}` shows the options set for a specific style.
-Please note that this does *not* show directly set options (i.e.\ options set by `\objectset` without the optional argument and options in the options argument of the object).
-
-\DescribeKey{show env args}
-See also the `show env args` key of the \env{object} and \env{subobject} environments.
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/examples.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/examples.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/examples.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,355 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\section{Examples}
-\label{examples}
-
-Let's start with a few examples.
-Environments, commands and keys defined by this package are links (both in the code and in the text).
-Klicking on them will get you to their explanation in \cref{documentation}.
-
-\Cref{motivation} gives a motivation why this package is useful.
-There is a list of related packages in \cref{used-packages,other-packages}.
-Package names link to the rather short description in that list.
-
-
-\subsection{Table}
-\label{table}
-Use the \env{tableobject} environment for inserting tables.
-Pass caption and label as keyword arguments.
-You can't mess up the order of caption and label and you get a warning if you forget to specify them.
-You don't need two environments (one for the float, one for the table---`tableobject` can do both).
-\pkg{booktabs} (and \pkg{array}) are loaded automatically (if not disabled, see \cref{package-options}).
-
-\begin{examplecode}
-\documentclass{article}
-\usepackage{easyfloats}
-\objectset{warn no label=false}
-
-\begin{document}
-\begin{tableobject}{caption=Some catcodes, env=tabular}{cl}
- \toprule
- Catcode & Meaning \\
- \midrule
- 0 & Escape Character \\
- 1 & Begin Group \\
- 2 & End Group \\
- \vdots & \quad \vdots \\
- \bottomrule
-\end{tableobject}
-\end{document}
-\end{examplecode}
-
-You can reduce typing effort even further by using the `table head` key, see \cref{longtable}.
-
-
-\subsection{Graphic}
-\label{graphic}
-Use the \cmd{\includegraphicobject} command to insert a graphic.
-It is a wrapper around \pkg{graphicx}' `\includegraphics` command taking the same arguments.
-No need for a surrounding `figure` environment.
-I have extended the allowed optional keyword argument to also accept caption, label and more.
-`details` are appended to the caption below the figure but not in the list of figures.
-Select with the \pkgoptn{graphicx} or \pkgoptn{graphbox} package options whether you want to use the commonly used \pkg{graphicx} package or it's extension \pkg{graphbox}.
-
-\begin{examplecode}
-\documentclass{article}
-\usepackage{easyfloats}
-\usepackage{hyperref}
-\objectset[figure]{graphic width=.8\linewidth}
-
-\begin{document}
-\includegraphicobject[%
- label = lion,
- caption = CTAN lion drawing by Duane Bibby,
- details = Thanks to \href{https://ctan.org/lion/files}{www.ctan.org}.,
-]{graphics/ctan_lion}
-
-\listoffigures
-\end{document}
-\end{examplecode}
-
-If you omit \key{caption} or `label` the file name is used.
-See `auto label`, `auto caption`, `auto label strip path` and `auto caption strip path`.
-
-
-\subsection{Subobjects}
-\label{subobjects-2}
-Use the \env{subobject} environment to combine two (or more) subobjects to one big object.
-The `contains subobjects` option causes the `env` option to be applied to the subobjects instead of the containing object.
-Changing the `subobject linewidth` is usually not necessary but in this example the tables fill only a small part of the width
-so they are too far apart from each other if each is centered on `.5\linewidth`.
-Pay attention to *not* insert an empty line between the subobjects, otherwise they will be placed below each other instead of side by side.
-If you want them to be placed below each other you can use the `ver` option.
-
-`\captionsetup` is explained in the \pkg{caption} package documentation~\autocite{caption}.
-
-\begin{examplecode}
-\documentclass{article}
-\usepackage{easyfloats}
-
-\objectset[table]{env=tabular}
-\captionsetup[sub]{list=true}
-
-\begin{document}
-\begin{tableobject}{contains subobjects,
- caption = Two test tables,
- label = tabs abc 123,
- subobject linewidth = .25\linewidth,
- }
- \begin{subobject}{caption=Abc \& 123}{rl}
- \toprule
- abc & 123 \\
- de & 45 \\
- f & 6 \\
- \bottomrule
- \end{subobject}
- \begin{subobject}{caption=123 \& abc}{lr}
- \toprule
- 123 & abc \\
- 45 & de \\
- 6 & f \\
- \bottomrule
- \end{subobject}
-\end{tableobject}
-\end{document}
-\end{examplecode}
-
-\subsection{Longtable}
-\label{longtable}
-If you are undecided whether to use floating `tabular`s or \env{longtable}s which can break across pages you can use the following approach.
-Changing between them is as easy as changing `env=longtable` to `env=tabular` once.
-The table head and foot are set by the key `table head` and are by default formatted with the \pkg{booktabs} package.
-(If you don't like this you can change the definition of `table head` with `table head style`.)
-The column specification cannot be given as a separate argument (like in the example above) but must be set with the `arg` key
-because otherwise the column specification would be after the table head.
-
-\begin{examplecode}
-\documentclass{article}
-\usepackage[longtable]{easyfloats}
-\usepackage{siunitx}
-
-\newcommand\pminfty{\multicolumn1r{$\pm\infty$}}
-
-\objectset[table]{env=longtable}
-
-\begin{document}
-\begin{tableobject}{%
- caption = Trigonometric functions,
- label = trifun,
- arg = {
- S[table-format=2.0, table-space-text-post=\si{\degree}] <{\si{\degree}} !\quad
- *2{S[table-format=+1.2]}
- S[table-format=+4.2]
- },
- table head = \multicolumn1{c!\quad}{$x$} & $\sin x$ & $\cos x$ & $\tan x$,
-}
-
- 0 & 0.00 & 1.00 & 0.00 \\
- 5 & 0.09 & 1.00 & 0.09 \\
- 10 & 0.17 & 0.98 & 0.18 \\
- 15 & 0.26 & 0.97 & 0.27 \\
- 20 & 0.34 & 0.94 & 0.36 \\
- 25 & 0.42 & 0.91 & 0.47 \\
- 30 & 0.50 & 0.87 & 0.58 \\
- 35 & 0.57 & 0.82 & 0.70 \\
- 40 & 0.64 & 0.77 & 0.84 \\
- 45 & 0.71 & 0.71 & 1.00 \\
- 50 & 0.77 & 0.64 & 1.19 \\
- 55 & 0.82 & 0.57 & 1.43 \\
- 60 & 0.87 & 0.50 & 1.73 \\
- 65 & 0.91 & 0.42 & 2.14 \\
- 70 & 0.94 & 0.34 & 2.75 \\
- 75 & 0.97 & 0.26 & 3.73 \\
- 80 & 0.98 & 0.17 & 5.67 \\
- 85 & 1.00 & 0.09 & 11.43 \\
- 90 & 1.00 & 0.00 & \pminfty \\
-\end{tableobject}
-\begin{tableobject}{%
- caption = Squared trigonometric functions,
- label = trifun2,
- arg = {
- S[table-format=2.0, table-space-text-post=\si{\degree}] <{\si{\degree}} !\quad
- *2{S[table-format=+1.2]}
- S[table-format=+4.2]
- },
- table head = \multicolumn1{c!\quad}{$x$} & {$\sin^2 x$} & {$\cos^2 x$} & {$\tan^2 x$},
-}
-
- 0 & 0.00 & 1.00 & 0.00 \\
- 5 & 0.01 & 0.99 & 0.01 \\
- 10 & 0.03 & 0.97 & 0.03 \\
- 15 & 0.07 & 0.93 & 0.07 \\
- 20 & 0.12 & 0.88 & 0.13 \\
- 25 & 0.18 & 0.82 & 0.22 \\
- 30 & 0.25 & 0.75 & 0.33 \\
- 35 & 0.33 & 0.67 & 0.49 \\
- 40 & 0.41 & 0.59 & 0.70 \\
- 45 & 0.50 & 0.50 & 1.00 \\
- 50 & 0.59 & 0.41 & 1.42 \\
- 55 & 0.67 & 0.33 & 2.04 \\
- 60 & 0.75 & 0.25 & 3.00 \\
- 65 & 0.82 & 0.18 & 4.60 \\
- 70 & 0.88 & 0.12 & 7.55 \\
- 75 & 0.93 & 0.07 & 13.93 \\
- 80 & 0.97 & 0.03 & 32.16 \\
- 85 & 0.99 & 0.01 & 130.65 \\
- 90 & 1.00 & 0.00 & \pminfty \\
-\end{tableobject}
-\begin{tableobject}{%
- caption = Cubed trigonometric functions,
- label = trifun3,
- arg = {
- S[table-format=2.0, table-space-text-post=\si{\degree}] <{\si{\degree}} !\quad
- *2{S[table-format=+1.2]}
- S[table-format=+4.2]
- },
- table head = \multicolumn1{c!\quad}{$x$} & {$\sin^3 x$} & {$\cos^3 x$} & {$\tan^3 x$},
-}
-
- 0 & 0.00 & 1.00 & 0.00 \\
- 5 & 0.00 & 0.99 & 0.00 \\
- 10 & 0.01 & 0.96 & 0.01 \\
- 15 & 0.02 & 0.90 & 0.02 \\
- 20 & 0.04 & 0.83 & 0.05 \\
- 25 & 0.08 & 0.74 & 0.10 \\
- 30 & 0.12 & 0.65 & 0.19 \\
- 35 & 0.19 & 0.55 & 0.34 \\
- 40 & 0.27 & 0.45 & 0.59 \\
- 45 & 0.35 & 0.35 & 1.00 \\
- 50 & 0.45 & 0.27 & 1.69 \\
- 55 & 0.55 & 0.19 & 2.91 \\
- 60 & 0.65 & 0.13 & 5.20 \\
- 65 & 0.74 & 0.08 & 9.86 \\
- 70 & 0.83 & 0.04 & 20.74 \\
- 75 & 0.90 & 0.02 & 51.98 \\
- 80 & 0.96 & 0.01 & 182.41 \\
- 85 & 0.99 & 0.00 & 1493.29 \\
- 90 & 1.00 & 0.00 & \pminfty \\
-\end{tableobject}
-\end{document}
-\end{examplecode}
-
-\subsection{Local definitions in tables}
-\label{local-definitions-in-tables}
-
-If you want to define a command locally for one table you cannot put it's definition in the first cell because each cell is a separate group
-(meaning that the definition will be forgotten at the end of the cell).
-Instead I provide the `exec` key whose value is executed inside of the object but before `env`.
-If you want to tinker around with catcodes keep in mind that arguments are always read entirely before expansion and execution.
-The \eTeX\ primitive `\scantokens` can be useful to define active characters.
-If you are unfamiliar with how \TeX\ processes a file you can read up on it in \mycite[section~1]{texbytopic}.
-
-\begin{examplecode}
-\documentclass{article}
-\usepackage{easyfloats}
-\usepackage[table]{xcolor}
-
-% avoid Warning: Font shape `OMS/cmtt/m/n' undefined
-\usepackage[T1]{fontenc}
-% fontenc T1 causes unclean/pixelated font on some systems
-% and trouble with copying ligatures from pdf => change font
-% lmodern is relatively close to the default font but unmaintained
-\usepackage{lmodern}
-
-\colorlet{rowbg}{gray!50}
-
-\newcommand\charsym[1]{\texttt{#1}}
-\newcommand\charname[1]{$\langle$#1$\rangle$}
-
-\begin{document}
-\begin{tableobject}{%
- caption = Category Codes,
- details = Highlighted catcodes have no tokens.,
- label = catcodes,
- env = tabular,
- arg = cll,
- table head = Catcode & Meaning & Characters,
- exec = {%
- \catcode`* = \active
- \scantokens{\def*{\rowcolor{rowbg}}}%
- \catcode`= = \the\catcode`&%
- \catcode`, = \the\catcode`&%
- },
-}
- * 0 = Escape character, \charsym\textbackslash \\
- 1 = Begin grouping, \charsym\{ \\
- 2 = End grouping, \charsym\} \\
- 3 = Math shift, \charsym\$ \\
- 4 = Alignment tab, \charsym\& \\
- * 5 = End of line, \charname{return} \\
- 6 = Parameter, \charsym\# \\
- 7 = Superscript, \charsym\^ \\
- 8 = Subscript, \charsym\_ \\
- * 9 = Ignored character, \charname{null} \\
- 10 = Space, \charname{space} and
- \charname{tab} \\
- 11 = Letter, \charsym{a}--\charsym{z} and
- \charsym{A}--\charsym{Z} \\
- 12 = Other, other characters \\
- % "In plain TeX this is only the tie character ~"
- % TeX by Topic, page 30
- 13 = Active character, \charsym{\string~} \\
- * 14 = Comment character, \charsym\% \\
- * 15 = Invalid character, \charname{delete} \\
-\end{tableobject}
-\end{document}
-\end{examplecode}
-
-\subsection{New object style~\slash\ `tikzobject`}
-\label{new-object-style-tikzobject}
-
-You can easily define new object environments.
-For more information see \cref{new-object-styles-and-types}.
-
-\begin{examplecode}
-\documentclass{article}
-\usepackage{easyfloats}
-\usepackage{tikz}
-
-\NewObjectStyle{tikz}{type=figure, env=tikzpicture}
-% I am not using `arg=[3D]` so that I can still pass an optional argument to tikz3dobject
-\NewObjectStyle{tikz3d}{type=figure, env=tikzpicture, exec=\tikzset{3D}}
-
-\tikzset{
- 3D/.style = {
- x = {(-3.85mm, -3.85mm)},
- y = {(1cm, 0cm)},
- z = {(0cm, 1cm)},
- },
-}
-\objectset{warn no label=false}
-
-\begin{document}
-\begin{tikzobject}{caption=2D coordinate system}
- \newcommand\n{5}
- \newcommand\w{.075}
- \draw[->] (0,0) -- ++(\n,0);
- \draw[->] (0,0) -- ++(0,\n);
- \foreach \i in {1,...,\n-1} {
- \draw (\i,0) +(0,\w) -- +(0,-\w);
- \draw (0,\i) +(\w,0) -- +(-\w,0);
- }
-\end{tikzobject}
-\begin{tikz3dobject}{caption=3D coordinate system}
- \newcommand\n{5}
- \newcommand\w{.075}
- \draw[->] (0,0,0) -- ++(\n,0,0);
- \draw[->] (0,0,0) -- ++(0,\n,0);
- \draw[->] (0,0,0) -- ++(0,0,\n);
- \foreach \i in {1,...,\n-1} {
- \draw (\i,0,0) +(0,\w,0) -- +(0,-\w,0);
- \draw (0,\i,0) +(\w,0,0) -- +(-\w,0,0);
- \draw (0,0,\i) +(0,\w,0) -- +(0,-\w,0);
- }
-\end{tikz3dobject}
-\end{document}
-\end{examplecode}
-
-\subsection{Nonfloating objects}
-\label{nonfloating-objects}
-If your professor absolutely won't allow floating objects you can easily disable them globally
-(for all objects based on the \env{object} environment defined by this package which is internally used by \env{tableobject} and \cmd{\includegraphicobject}).
-
-\begin{examplecode}
-\objectset{placement=H}
-\end{examplecode}
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/f1_titlepage.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/f1_titlepage.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/f1_titlepage.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,18 @@
+% !TeX root = ../easyfloats.tex
+
+\maketitle
+\thispagestyle{empty}
+\vfill
+\begin{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.
+It also defines a new placement `I` similar to `H` which respects the indentation in an `itemize`.
+\end{abstract}
+\vfill
+\vspace{20em}
+\url{https://gitlab.com/erzo/latex-easyfloats}
+\clearpage
+
+\tableofcontents
+\pagebreak
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/f1_titlepage.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/installation.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/installation.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/installation.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,8 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\section{Installation}
-\label{installation}
-
-This package is still very new.
-If it is not yet contained in your \TeX\ distribution
-just download the \filename{sty-file} and put it next to your main document.
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/license.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/license.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/license.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,17 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\section{License}
-\label{license}
-
-This package and it's documentation are distributed under the \license{lppl}, version 1.3 or later.
-See \filename{license.txt}.
-The preamble of the documentation may alternatively, at your choice, be reused under the terms of the \license{wtfpl}, 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 \filename{easyfloats.sty} and \filename{doc/easyfloats.pdf} without other files of this work.
-The other files of this work can be found at:
-\url{https://gitlab.com/erzo/latex-easyfloats}
-
-The examples and tests are distributed under the \license{wtfpl}, version 2 or later.
-See \filename{test/license.txt}.
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/motivation.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/motivation.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/motivation.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,378 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\section{Motivation}
-\label{motivation}
-
-In this section I will explain how to insert figures and tables in standard \LaTeX\ without this package and how this package can improve that.
-If you are only interested in how to use this package not why, see \cref{examples} for examples and \cref{documentation} for an explanation of the commands, environments and options defined by this package.
-
-\subsection{Graphics}
-\label{graphics}
-
-Inserting a graphic without using this package requires 6 lines of code (\pkg{graphicx} or \pkg{graphbox} must be loaded for `\includegraphics`):
-\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
-\begin{figure}
- \centering
- \includegraphics[graphic width=.8\linewidth]{ctan_lion}
- \caption{CTAN lion drawing by Duane Bibby}
- \label{ctan_lion}
-\end{figure}
-\end{examplecode\starred}
-
-\begin{description}
-\item[Lines 1 and 6]
- open\slash close a floating environment.
- The content of this environment can float around so that it won't cause a bad page break.
- You don't need this if you really just want to insert a graphic exactly here (like a logo in a header)
- but a graphic cannot break across pages so if it is too large for the end of the current page it will move to the next page leaving the end of this page empty.
- This is a waste of paper and may confuse a reader by suggesting this might be the end of a chapter.
- A floating environment can help you by putting the figure where it fits best.
-
- The placement determines where a float is allowed to be placed.
- Initially that's the top or bottom of a text page or a separate page just for floats.
- The placement can be specified for a single floating object by passing an optional argument to the floating environment
- or for all floating objects using the `\floatplacement` command defined by the \pkg{float} package.
- (The floating environments `figure` and \env{table} are standard \LaTeX\ and do not require the \pkg{float} package.)
- The allowed values for the placement are described in the description of the \env{object} environment's `placement` key.
-
- There are people who are concerned that a figure not sitting at the exact position might confuse a reader.
- However, a graphic naturally attracts the reader's attention.
- Therefore it does not matter where it is located on the double page.
- The reader will see it.
-
- Of course the author must ensure that the figure does not float too far away.
- If that is the case changing the size of this or another graphic,
- `\usepackage[section]{placeins}`,
- `\FloatBarrier` (defined by the \pkg{placeins} package),
- moving this block of lines in the code,
- changing the placement or
- tweaking the parameters which govern the placing of floats \autocite[page~28]{latex2e}
- can help.
-
-\item[Line 2]
- centers the graphic horizontally on the line.
-
- The `\centering` command is used instead of the `center` environment because the latter would insert additional vertical space.
-
- \begin{examplecode\starred}{\ExamplecodeNoBox}
- \begin{center}
- ...
- \end{center}
- \end{examplecode\starred}
- is in \LaTeX2\footnote{This will change in \LaTeX3~\autocite{ltx3env}.}
- \makeatletter
- (somewhat simplified\footnote{`\begin` checks that it's argument is defined, `\end` checks that it's argument matches that of `\begin` and deals with `\ignorespacesafterend` and `\@endparenv`. Since 2019/10/01 `\begin` and `\end` are robust. Since 2020/10/01 they include hooks. \autocite[section \sectionname{ltmiscen.dtx}]{source2e}})
- \makeatother
- equivalent to
- \begin{examplecode\starred}{\ExamplecodeNoBox}
- \begingroup
- \center
- ...
- \endcenter
- \endgroup
- \end{examplecode\starred}
-
- This means that if you accidentally try to use `\centering` as an environment instead of a command you will *not* get an error.
- You might expect to get an error at least for `\endcentering` not being defined
- but the \TeX\ primitive `\csname` which is used to produce the `\endcentering` token instead defines it to `\relax`, a no operation.
-
- The output, however, will not be as desired: the group is closed before the end of the paragraph and `\centering` is forgotten before it can take effect.
-
-\item[Line 3]
- inserts the graphic.
- This requires the \pkg{graphicx} or \pkg{graphbox} package.
-
- If you want all graphics to have the same width you can set the `width` globally with `\setkeys{Gin}{width=<dimen>}`.
- However, that does not work with all options.
- Unfortunately the \pkg{graphicx} package documentation~\autocite[section~4.6]{graphicx} is not getting more specific than that this works with \enquote{Most of the keyval keys}.
-
-\item[Line 4]
- inserts the caption.
-
- Captions for a figure should be placed *below* the figure.
- Captions for a table should be placed *above* the table.
- \autocite{texexchange_caption_position}
-
- `\caption` can be used inside of a floating environment only.
- If you need a caption for a non-floating object you can either use `\captionof{<type>}{<caption>}` defined by the \pkg{capt-of} or \pkg{caption} package
- or use a floating environment with the placement `H` defined by the \pkg{float} package.
- Although the placement can usually be set globally with `\floatplacement` that does *not* work with `H`.
-
-\item[Line 5]
- defines a label.
- This is not visible in the output but can be referenced using `\ref{<label>}` or `\pageref{<label>}`.
- You might want to consider using the \pkg{cleveref} package for references.
-
- The label must be set inside of or after the caption.
- A label always refers to the last `\refstepcounter` inside of the current group. \autocite[section \sectionname{ltxref.dtx}]{source2e}
- `\refstepcounter` is used for example by `\caption` and `\section`.
- Therefore if you use `\label` after the caption it refers to the caption.
- If you use it before the caption it refers to the current section\slash subsection\slash subsubsection.
-\end{description}
-
-There are many things that a beginner can do wrong without even getting a warning.
-Three out of this six lines are always the same (lines 1, 2 and~6).
-I don't want to always write them out.
-There is no way to easily switch floating on or off globally.
-
-\bigpar
-
-This package reduces these six lines to a single command and loads \pkg{graphicx} automatically (unless this package is loaded with the `nographic` option).
-\begin{examplecode\starred}{}
-\includegraphicobject[%
- caption = CTAN lion drawing by Duane Bibby,
- graphic width = .8\linewidth,
-]{ctan_lion}
-\end{examplecode\starred}
-
-The floating environment is applied automatically.
-It can be changed using the `type` key but I discourage doing so manually.
-Instead I recommend to use the separate optional `<style>` argument if necessary.
-If you do not want the object to float you can pass `placement=H`.
-This works also globally with `\objectset`.
-
-`\centering` is applied automatically.
-It can be changed using the `align` key.
-
-You can set any of the options passed to the `\includegraphics` command globally using:
-\begin{examplecode\starred}{}
-\objectset[figure]{graphic width=.8\linewidth}
-\end{examplecode\starred}
-
-Caption and label can be passed as options.
-Which one is specified first makes no difference.
-I recommend to stick with caption first in case you ever need to work without this package and to not confuse other people who are not familiar with this package.
-If you omit one of them the file name is used.
-See `auto label`, `auto caption`, `auto label strip path` and `auto caption strip path`.
-
-Whether the caption is put above or below the object is specified by the `float style`.
-
-\subsection{Tables}
-\label{tables}
-
-Inserting a table is similar to inserting a graphic except that you replace the `\includegraphics` command with an environment which creates a table, place the caption above the table not below it and use another floating environment, namely \env{table} instead of `figure`.
-
-The following example (not using this package) requires the \pkg{booktabs} package for the horizontal rules and the \pkg{caption} package to have an appropriate space below the caption.
-
-\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
-\begin{table}
- \centering
- \caption{Some catcodes}
- \label{catcodes}
- \begin{tabular}{cl}
- \toprule
- Catcode & Meaning \\
- \midrule
- 0 & Escape Character \\
- 1 & Begin Group \\
- 2 & End Group \\
- \vdots & \quad \vdots \\
- \bottomrule
- \end{tabular}
-\end{table}
-\end{examplecode\starred}
-
-What I have said about floating environments, `\centering`, `\caption` and `\label` in \cref{graphics} is also valid for tables.
-New are lines 5--14.
-We now have two environments nested inside of each other.
-The outer environment (lines 1 and~15) is the floating environment.
-The inner environment (lines 5--14) is the environment which creates the table.
-The inner environment takes a column specification telling \LaTeX\ how many columns the table has and how they are supposed to be aligned.
-In this case that is `cl`: Two columns, the first centered, the second left aligned.
-For more information about column specifications see the \pkg{array} package documentation~\autocite[section~1]{array}.
-
-`\toprule`, `\midrule` and `\bottomrule` (defined by the \pkg{booktabs} package) produce horizontal lines.
-They differ in the width of the line and\slash or spacing around them.
-In contrast to the standard \LaTeX\ `\hline` command they have proper spacing around them.
-
-`&` separates columns, `\\` separates rows.
-Indentation and spaces at the beginning and end of a cell are ignored.
-
-\bigpar
-
-Using this package we don't need two environments and we don't even need to type out the rule commands if we use `table head`.
-The packages \pkg{caption}, \pkg{booktabs} and \pkg{array} are loaded automatically (unless you load this package with `nobooktabs` or `noarray`).
-\begin{examplecode\starred}{}
-\begin{tableobject}{%
- caption = Some catcodes,
- label = catcodes,
- env = tabular,
- arg = cl,
- table head = Catcode & Meaning,
-}
- 0 & Escape Character \\
- 1 & Begin Group \\
- 2 & End Group \\
- \vdots & \quad \vdots \\
-\end{tableobject}
-\end{examplecode\starred}
-
-Also we gain the possibility to easily switch between different tabular-like environments, see \cref{longtable} and the example given for the `(<env>) arg(s) +` key in \cref{object-environment}.
-
-\subsection{Subobjects}
-\label{subobjects}
-
-There are several packages to combine several figures\slash tables into a single floating environment.
-\mycite{l2tabu} recommends using \pkg{subcaption} over \pkg{subfig} and the long deprecated \pkg{subfigure}.
-
-The \pkg{subcaption} package provides several ways to do this.
-The first one is using the `\subcaptionbox` command.
-
-\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
-\begin{table}
- \centering
- \caption{Category and character codes}
- \label{codes}
- \subcaptionbox{Category codes\label{catcodes}}{%
- \begin{tabular}{cl}
- \toprule
- Catcode & Category \\
- \midrule
- 0 & Escape Character \\
- 1 & Begin Group \\
- 2 & End Group \\
- \vdots & \quad \vdots \\
- \bottomrule
- \end{tabular}%
- }%
- \qquad
- \subcaptionbox{Character codes\label{charcodes}}{%
- \begin{tabular}{cr<{\hspace{1.3em}}}
- \toprule
- Character & \multicolumn1c{Charcode} \\
- \midrule
- \textbackslash & \number`\\ \\
- \{ & \number`\{ \\
- \} & \number`\} \\
- \vdots & \vdots \phantom{0} \\
- \bottomrule
- \end{tabular}%
- }%
-\end{table}
-\end{examplecode\starred}
-
-As the subobjects are inside of an argument they cannot contain code which relies on changing catcodes e.g.\ `\verb`.
-Aside from that it just doesn't seem elegant to put an environment inside of an argument.
-
-If you accidentally put the label in the second argument of `\subcaptionbox` instead of in the first it refers to the parent object instead of the subobject and you won't get an error or a warning for that.
-
-Note how I have commented out line breaks in order to avoid undesired spaces.
-
-The second way is to use the `subfigure`\slash `subtable` environment.
-Because the subobject is not inside of an argument it is possible to use `\verb`.
-
-\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
-\begin{table}
- \caption{Category and character codes}
- \label{codes}
- \begin{subtable}{.5\linewidth}
- \centering
- \caption{Category codes}
- \label{catcodes}
- \begin{tabular}{cl}
- \toprule
- Catcode & Category \\
- \midrule
- 0 & Escape Character \\
- 1 & Begin Group \\
- 2 & End Group \\
- \vdots & \quad \vdots \\
- \bottomrule
- \end{tabular}%
- \end{subtable}%
- \begin{subtable}{.5\linewidth}
- \centering
- \caption{Character codes}
- \label{charcodes}
- \begin{tabular}{cr<{\hspace{1.3em}}}
- \toprule
- Character & \multicolumn1c{Charcode} \\
- \midrule
- \verb|\| & \number`\\ \\
- \verb|{| & \number`\{ \\
- \verb|}| & \number`\} \\
- \vdots & \vdots \phantom{0} \\
- \bottomrule
- \end{tabular}%
- \end{subtable}%
-\end{table}
-\end{examplecode\starred}
-
-But why having different environments for subfigures and subtables?
-The floating environment specifies the type already.
-
-These environments are based on a minipage and require you to always explicitly specify the width of this minipage.
-On the one hand I don't want to always type that out.
-On the other hand I want to be able to change the width once for all subobjects for easier consistency.
-
-Caption and label must be placed correctly, see \cref{graphics}.
-Even if you restyle the floating environment to always put the caption at the top or bottom using the \pkg{float} package this does *not* apply to subobjects.
-
-It is important to comment out line breaks because the widths of the two minipages add up to the line width, a space between them would cause an overfull hbox or a line break.
-
-We need two `\centering`s, one for each subobject.
-Remember what I said about `\centering` and `center` in \cref{graphics}.
-
-\bigpar
-
-This package defines an environment called `subobject` which is a unified wrapper around `\subcaptionbox` and `subfigure`\slash `subtable`.
-Which of these two backends should be used can be specified with the `subcaptionbox` and `subpage` options.
-`subpage` is used by default so that you can usually use `\verb` in the content.
-
-`subobject` can be used inside of any `*object` environment.
-If you define a new object environment with `\NewObjectStyle` it defines a corresponding subpage environment like `subfigure`\slash `subtable` if it does not exist already and if the \pkg{caption} package is new enough.
-If the \pkg{caption} package is older than August~30, 2020 you need to define the subtype manually by putting the following line *before* loading this package \autocite{texexchange_subtype_workaround}:
-\begin{examplecode\starred}{}
-\AtBeginDocument{\DeclareCaptionSubType{<type>}}
-\end{examplecode\starred}
-
-You don't need to write out the width, `.5\linewidth` is used automatically. You can change this value for all subobjects using
-\begin{examplecode\starred}{}
-\objectset{subobject linewidth=<dimen>}
-\end{examplecode\starred}
-
-Caption and label are given as options like for `tableobject`.
-Their order does not matter.
-They are placed above or below the subobject based on the internal command `\caption at iftop` defined by the \pkg{caption} package.
-
-Spaces after `\begin{subobject}` and before and after `\end{subobject}` are ignored so you don't need to comment out the line breaks.
-\unskip\footnote{Actually, spaces after `\begin{subobject}` and before `\end{subobject}` are ignored only if `env` is empty. But if `env` is not empty I am expecting it to be a tabular-like environment where spaces are ignored at the beginning and end of a cell or a tikzpicture where spaces are ignored as well. Spaces after `\end{subobject}` are ignored regardless of `env`.}
-Just make sure you don't have an empty line between the subobject environments.
-That would *not* be ignored.
-
-`\centering` is inserted automatically. It can be changed with `subpage align`.
-
-\begin{examplecode\starred}{}
-\begin{tableobject}{caption=Category and character codes, label=codes, env=tabular, sub}
- \begin{subobject}{caption=Category codes, label=catcodes}{cl}
- \toprule
- Catcode & Category \\
- \midrule
- 0 & Escape Character \\
- 1 & Begin Group \\
- 2 & End Group \\
- \vdots & \quad \vdots \\
- \bottomrule
- \end{subobject}
- \begin{subobject}{caption=Character codes, label=charcodes}{cr<{\hspace{1.3em}}}
- \toprule
- Character & \multicolumn1c{Charcode} \\
- \midrule
- \verb|\| & \number`\\ \\
- \verb|{| & \number`\{ \\
- \verb|}| & \number`\} \\
- \vdots & \vdots \phantom{0} \\
- \bottomrule
- \end{subobject}
-\end{tableobject}
-\end{examplecode\starred}
-
-A separator for the subobjects could be defined globally using `sep`, see also `hor` and `ver`.
-
-For including a graphic from an external file this package defines a wrapper command around `subobject` and `\includegraphics` in order to reduce the typing effort:
-\begin{examplecode\starred}{}
-\begin{figureobject}{caption=Two lions, label=lions, sub}
- \includegraphicsubobject[caption=A lion]{lion-1}
- \includegraphicsubobject[caption=Another lion]{lion-2}
-\end{figureobject}
-\end{examplecode\starred}
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/names.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/names.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/names.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,18 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\section{Names}
-\label{names}
-
-You have probably heard the term *floating object* or *float* for short.
-That is mainly what this package is about.
-However, I intended to avoid the term *floating* in the name of this package because this package also allows
-to globally disable the floating of those objects.
-Therefore I decided to name this package *objects*.
-
-This name, however, has been rejected by \TeX\ Live as being too generic.
-And they are right, especially for people with an object oriented programming background that name might be misleading.
-\TeX\ Live has informed me that floating objects are still called floats even if they are technically not floating.
-Therefore I have decided to rename this package to *easyfloats*.
-
-I have *not* changed the user interface because the package has already been online for more than half a year on my gitlab repository and I don't know how many people are using the package already.
-Therefore all commands and environments defined by this package still carry the old name *object* in them.
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/other-packages.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/other-packages.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/other-packages.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,51 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\section{Other packages}
-\label{other-packages}
-
-Other useful packages for dealing with figures or tables:
-\pkgdoc{placeins}
- When loaded with the `section` package option it prevents floats from floating to another section.
- It provides the `\FloatBarrier` command which prevents floats from floating past a certain point.
-\pkgdoc{flafter}
- ensures that floats are not placed before their inclusion in the source code.
- (With the placement=t it is possible that they are placed on the top of the same page.)
-\pkgdoc{booktabs}
- for formatting tables
-\pkgdoc{xcolor}
- When loaded with the package option \pkgoptn{table} it provides commands for coloring tables.
-
- `\rowcolor{<color>}` sets a background color for a single row. See \cref{local-definitions-in-tables}.
-
- `\rowcolors{<firstrow>}{<oddcolor>}{<evencolor>}` can be used with the `exec` key and sets alternating row colors for the entire table.
-
-\pkgdoc{array}
- extends the column specification syntax and defines the `\newcolumntype` command to define custom column types.
- Also changes the approach how rules are drawn but that is irrelevant if you apply \pkg{booktabs}' guidelines~\autocite[section~2 \sectionname{The layout of formal tables}]{booktabs}.
-\pkgdoc{siunitx}
- for typesetting numbers and units.
- It provides the `S` column to align numbers at their decimal separator.
-\pkgdoc{tabularx}
- A table where the columns adapt to the width of the table, not the other way around.
- Unlike `tabular*` the space goes into the columns, not between the columns.
-\pkgdoc{longtable}
- provides tables where a pagebreak is allowed,
- see \cref{longtable}
-\pkgdoc{hyperref}
- automatically creates links in the pdf document for example from references to floating objects.
- With the package option `pdfusetitle` it automatically sets the pdf title and author based on `\title` and `\author`.
-\pkgdoc{cleveref}
- to reference an object.
- In contrast to the standard `\ref` and `\pageref`, `\cref` and `\cpageref` automatically detect the type of object and can handle multiple references at once.
- With the `nameinlink` package option the object type in front of the number becomes part of the link created by hyperref (i.e.\ the link is \enquote{figure 1} instead of \enquote{1} and \enquote{figure } being before the link.)
- With the `noabbrev` option references are not abbreviated (by default references are abbreviated but only the lower case variants, not the upper case variants which seems inconsistent to me. Abbreviating at the beginning of a sentence is considered bad style~\autocite{texexchange_abbrev_bad_style}.)
-\pkgdoc{biblatex}
- If you input graphics you need to specify the source.
- Biblatex creates an entire bibliography for you.
-\pkgdoc{tikz}
- is an amazingly powerful package to create your own graphics in \LaTeX.
-\pkgdoc{newfloat} provides a more modern command to define new floating environments than the \pkg{float} package.
-\endpkgdoc
-
-
-For more information about floats see \url{https://latexref.xyz/Floats.html} (it seems this is an html version of the above quoted pdf~\autocite{latex2e}).
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s1_examples.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/s1_examples.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/s1_examples.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,230 @@
+% !TeX root = ../easyfloats.tex
+
+\section{Examples}
+\label{examples}
+
+Let's start with a few examples.
+Environments, commands and keys defined by this package are links (both in the code and in the text).
+Clicking on them will get you to their explanation in \cref{documentation}.
+
+\Cref{motivation} gives a motivation why this package is useful.
+There is a list of related packages in \cref{used-packages,other-packages}.
+Package names link to the rather short description in that list.
+
+The examples have been tested with \input{../test/generated/latex_version}\unskip.
+
+
+\subsection{Table}
+\label{table}
+Use the \env{tableobject} environment for inserting tables.
+Pass caption and label as keyword arguments.
+You can't mess up the order of caption and label and you get a warning if you forget to specify them.
+You don't need two environments (one for the float, one for the table---`tableobject` can do both).
+\pkg{booktabs} (and \pkg{array}) are loaded automatically (if not disabled, see \cref{package-options}).
+
+The last argument, `cl`, is not an argument of the `tableobject` environment but of the standard \LaTeX\ `tabular` environment which is started by the `tableobject` environment because it is specified with `env`.
+It specifies the columns of the table: The `l` stands for one left aligned column and the `c` for one centered column.
+An `r` would stand for a right aligned column and a \xc.p{<width>}. for a column which breaks the cell contents to a specified width.
+The \pkg{siunitx} package defines `S` for a column which aligns numbers and in the `tabularx` environment defined by the \pkg{tabularx} package `X` is available for a `p` column which automatically takes as much space as there is available.
+You can use the `\newcolumntype` command (defined by the \pkg{array} package) to define your own column types, e.g.\ `\newcolumntype{M}{>{$}c<{$}}` to define a column type `M` for centered math content.
+See the \pkg{array} package documentation~\autocite[chapter~1]{array} for more column specification options.
+
+`&` is the column separator and `\\` specifies the end of a row.
+
+The table is formatted with `\toprule`, `\midrule` and `\bottomrule` as explained in the \pkg{booktabs} documentation~\autocite[chapter~2]{booktabs}.
+
+\inputexamplecode{../test/exp-table}
+
+You can reduce typing effort even further by using the `table head` key, see \cref{longtable}.
+
+If you are not familiar with how to reference a label, see \cref{vref}.
+
+
+\subsection{Graphic}
+\label{graphic}
+Use the \cmd{\includegraphicobject} command to insert a graphic.
+It is a wrapper around \pkg{graphicx}' `\includegraphics` command taking the same arguments.
+No need for a surrounding `figure` environment.
+I have extended the allowed optional keyword argument to also accept caption, label and more, see \cref{includegraphicobject-command}.
+`details` are appended to the caption below the figure but not in the list of figures.
+Select with the \pkgoptn{graphicx} or \pkgoptn{graphbox} package options whether you want to use the commonly used \pkg{graphicx} package or it's extension \pkg{graphbox}.
+
+\inputexamplecode{../test/exp-graphic}
+
+The graphic automatically gets the label \formatlabel{fig:graphics/ctan_lion}, based on the file name and the specified prefix.
+You can override the automatically generated label by passing the key `label` to the optional argument.
+If you omit \key{caption} the file name \formatcaption{graphics/ctan_lion} is used.
+See `auto label`, `auto caption`, `auto label strip path`, `auto caption strip path` and `auto label prefix`.
+
+If you are not familiar with how to reference a label, see \cref{vref}.
+
+
+\subsection{Subfigures}
+\label{exp:subfigures}
+The following example shows a figure consisting of two graphics displayed side by side, each having their own caption and label.
+The graphics have a distance of one quad, i.e. 1\,em, and fill the entire width of the line.
+(em is a unit of distance relative to the font.
+If you are unfamiliar with the units supported by \TeX\ you can read up on them in \mycite[pages 57 and~60]{texbook} or \mycite[chapters 8.2.1 and~4.3.1]{texbytopic}.
+
+I am loading the \pkg{calc} package in order to use an expression as `subobject linewidth`.
+(Alternatively you could use the \eTeX\ primitive `\dimexpr`.)
+As I want to put two graphics next to each other, each of them should be half of the available line width minus half of the distance between them wide.
+Additionally I need to subtract a tiny bit more in order to compensate for rounding errors in the division which would cause an uninteded line break with the initial setting `align = \centering`.
+(The rounding errors would not need to be compensated if you set the value of `align` to an empty string).
+
+Pay attention to *not* insert an empty line between the subobjects, otherwise they will be placed below each other instead of side by side.
+If you want them to be placed below each other you can use the `ver` option.
+
+By default subobjects do not show up in the list of figures.
+You can change that with `\captionsetup[sub]{list=true}`.
+`\captionsetup` is explained in the \pkg{caption} package documentation~\autocite{caption}.
+
+\inputexamplecode{../test/exp-subgraphic}
+
+Each of the subfigures gets it's own label, generated based on the given prefix and the file name: \formatlabel{fig:ctan_lion} and \formatlabel{fig:tex_engines}.
+You can override the automatically generated labels with the \key[/subobject]{label} key if needed.
+How to reference the labels is shown in \cref{vref}.
+
+If you want to use the full width for graphics in subobjects but less than the full width for graphics in main objects you can achieve that with
+%If you want a different width for `\includegraphicsubobject` and `\includegraphicobject` you could achieve that with
+\begin{examplecode}
+\objectset[figure]{graphic width = .8\linewidth}
+\AtBeginSubobject{\AtBeginGraphicObject{%
+ \objectset{graphic width = \linewidth}%
+}}
+\end{examplecode}
+
+
+\subsection{Other subobjects}
+\label{subobjects-2}
+
+Use the \env{subobject} environment to combine two (or more) subobjects to one big object.
+The `contains subobjects` option causes the `env` option to be applied to the subobjects instead of the containing object.
+I am decreasing the `subobject linewidth` because the tables fill only a small part of the width
+so the distance between them would be too big if each was centered on `.5\linewidth`.
+(If you don't want to set the `subobject linewidth` to an explicit value take a look at the `subcaptionbox` option and the example provided there.
+ Setting `subobject sep` to the desired distance and aligning the subojects with `subpage align=\raggedleft` and `subpage align=\raggedright` does not work well because `\raggedleft` and `\raggedright` do not affect the caption. The alignment of the caption could be changed with `\captionsetup{justification=raggedleft,singlelinecheck=false}` but then the caption would not be centered relative to the tabular.)
+
+Pay attention to *not* insert an empty line between the subobjects, otherwise they will be placed below each other instead of side by side.
+If you want them to be placed below each other you can use the `ver` option.
+
+By default subobjects do not show up in the list of tables.
+You can change that with `\captionsetup[sub]{list=true}`.
+`\captionsetup` is explained in the \pkg{caption} package documentation~\autocite{caption}.
+
+\inputexamplecode{../test/exp-subobject}
+
+
+\subsection{Longtable}
+\label{longtable}
+If you are undecided whether to use floating `tabular`s or \env{longtable}s which can break across pages you can use the following approach.
+Changing between them is as easy as changing `env=longtable` to `env=tabular` once.
+The table head and foot are set by the key `table head` and are by default formatted with the \pkg{booktabs} package.
+(If you don't like this you can change the definition of `table head` with `table head style`.)
+The column specification cannot be given as a separate argument (like in the example above) but must be set with the `arg` key
+because otherwise the column specification would be after the table head.
+
+\inputexamplecode{../test/exp-longtable}
+
+
+\subsection{Local definitions in tables}
+\label{local-definitions-in-tables}
+
+If you want to define a command locally for one table you cannot put it's definition in the first cell because each cell is a separate group
+(meaning that the definition will be forgotten at the end of the cell).
+Instead I provide the `exec` key whose value is executed inside of the object but before `env`.
+If you want to tinker around with catcodes keep in mind that arguments are always read entirely before expansion and execution.
+The \eTeX\ primitive `\scantokens` can be useful to define active characters.
+If you are unfamiliar with how \TeX\ processes a file you can read up on it in \mycite[section~1]{texbytopic}.
+
+\inputexamplecode{../test/exp-exec}
+
+
+\subsection{New object style~\slash\ `tikzobject`}
+\label{new-object-style-tikzobject}
+
+You can easily define new object environments.
+For more information see \cref{new-object-styles-and-types}.
+
+\inputexamplecode{../test/exp-tikzobject}
+
+If you are interested in three dimensional drawing see also the \TikZ\ library \tikzlibrary{perspective} \autocite[section~63 Three Point Perspective Drawing Library]{tikz}.
+
+
+\subsection{New float type `diagram`}
+\label{exp:new-object-type}
+
+I am using `\AtEndPreamble` defined by the \pkg{etoolbox} package to defer loading of \pkg{cleveref} after \pkg{hyperref}.
+For more information about \pkg{cleveref} and \pkg{varioref} see \cref{vref}.
+
+I am defining `\listofdiagrams` analogous to `\listoffigures` and `\listoftables` with the help of the `\listof` command defined by the \pkg{float} package (which is loaded automatically by \pkg{easyfloats}).
+
+For more information see \cref{new-object-styles-and-types}.
+
+\inputexamplecode{../test/exp-new-object-style}
+
+
+\subsection{Split object}
+\label{split-object-example}
+
+If a float gets too big you can split it up with the `\splitobject` command so that the object can be broken across a page break.
+I am using `\DeclareCaptionLabelFormat` and `\captionsetup` to add the prefix \enquote{Continued} to the caption of the continuation as shown in the package \pkg{caption} documentation~\autocite[section~3.3
+Continued floats]{caption}.
+
+\inputexamplecode{../test/exp-splitobject}
+
+
+\subsection{Custom options}
+\label{custom-options}
+This package uses the \pkg{pgfkeys} package to define the options which can be passed to the environments and commands defined by this package.
+Therefore you can use the usual pgfkeys handlers to add custom options.
+The following example defines a new key `center subcaptions` which centers the captions of all subobjects.
+For more information see \cref{options} and the \mycite[Utilities/Key Management]{tikz}.
+
+\inputexamplecode{../test/exp-custom-option}
+
+
+\subsection{Nonfloating objects}
+\label{nonfloating-objects}
+If your professor absolutely won't allow floating objects you can easily disable them globally
+(for all objects based on the \env{object} environment defined by this package which is internally used by \env{tableobject} and \cmd{\includegraphicobject}).
+
+\begin{examplecode}
+\objectset{placement=H}
+\end{examplecode}
+
+
+\subsection{How to reference objects}
+\label{vref}
+When you insert floating objects you probably want to reference them in the text.
+Although this package does not change anything about referencing I have added an example for the sake of completeness.
+
+The standard \LaTeX\ commands are `\ref{<label>}` (to insert the number of a figure/table/whatever) and `\pageref{<label>}` (to insert the page number).
+The \pkg{hyperref} package automatically turns them into links.
+The \pkg{varioref} package defines new commands `\vref{<label>}` and `\Vref{<label>}` which automatically add a reference to the page if the label is on a different page.
+The \pkg{cleveref} package redefines `\vref{<label>}` and `\Vref{<label>}` to automatically insert the type of object in front of the reference so that you don't need to write out \enquote{figure\string~}.
+
+`\Vref{<label>}` is to be used at the beginning of the sentence and `\vref{<label>}` is to be used inside of a sentence.
+The distinction is important for capitalization and whether to use an abbreviation.
+You can disable abbreviations by loading the \pkg{cleveref} package with the `noabbrev` option.
+
+Note that \pkg{cleveref} must be loaded last, even after \pkg{hyperref} which should usually be loaded last.
+
+\inputexamplecode{../test/exp-vref}
+
+Warning: Using \pkg{varioref} can lead to not converging behavior.
+For example: You use `\vref{sec:foo}` in section~1 to reference `\label{sec:foo}` at the beginning of section~2.
+In the first run it prints \enquote{??} as reference because it does not know the referenced object yet. The reference is on page~1 and section~2 begins at the end of page~2.
+In the second run it therefore prints \enquote{section~2 on the following page}. Section~2 moves to the beginning of page~3 because the reference text is now longer.
+In the third run it therefore prints \enquote{section~2 on page~3}. Section~2 moves back to page~2 because the reference text is now shorter.
+In the fourth run it therefore prints \enquote{section~2 on the following page} again. And section~2 moves to the beginning of page~3 again.
+Every time you compile the document the beginning of section~2 will be somewhere else and the reference will never be correct.
+This may cause other references (e.g. `\pageref{LastPage}` (defined by the \pkg{lastpage} package) to jump as well.
+The same can happen when referencing an earlier label.
+
+You don't need to worry about this until the very end because this behavior may get resolved while inserting, deleting or rewriting contents or formatting the document.
+But if this still happens when you have finished everything else you can solve this by inserting a `\clearpage` or replacing the `\vref` with a `\fullref`.
+`\fullref{<label>}` is defined by the \pkg{varioref} package and is by default equivalent to `\cref{<label>} on \cpageref{<label>}` (if \pkg{cleveref} is loaded---if not it's default is equivalent to `\ref{<label>} on page~\pageref{<label>}`).
+Using `\clearpage` may be preferable in order to keep the referencing manner consistent.
+
+See also the \pkg{varioref} documentation, section~7 \sectionname{A few warnings}.
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s1_examples.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s2_names.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/s2_names.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/s2_names.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,18 @@
+% !TeX root = ../easyfloats.tex
+
+\section{Names}
+\label{names}
+
+You have probably heard the term *floating object* or *float* for short.
+That is mainly what this package is about.
+However, I intended to avoid the term *floating* in the name of this package because this package also allows
+to globally disable the floating of those objects.
+Therefore I decided to name this package *objects*.
+
+This name, however, has been rejected by \TeX\ Live as being too generic.
+And they are right, especially for people with an object oriented programming background that name might be misleading.
+\TeX\ Live has informed me that floating objects are still called floats even if they are technically not floating.
+Therefore I have decided to rename this package to *easyfloats*.
+
+I have *not* changed the user interface because the package has already been online for more than half a year on my gitlab repository and I don't know how many people are using the package already.
+Therefore all commands and environments defined by this package still carry the old name *object* in them.
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s2_names.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s3_documentation.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/s3_documentation.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/s3_documentation.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,1128 @@
+% !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 `<key>`s or `<key>=<value>` 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 `(<env>) 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]{<options>}` or `\objectset[table]{<options>}`.
+
+A style is applied by using the corresponding environment (e.g.\ \env{figureobject} or \env{tableobject})
+or `\graphicobjectstyle{<style>}` for \cmd{\includegraphicobject}.
+
+New styles can be defined with `\NewObjectStyle` as explained in \cref{new-object-styles-and-types}.
+
+\subsubsection{Style groups}
+\label{style-groups}
+\DescribeMeta{group}
+
+This package defines one group of styles called `all` which contains all defined styles.
+
+When setting options one can use a group name instead of a style name.
+In that case the options are set for all styles in the group.
+
+\subsubsection{Options processing order}
+\label{options-processing-order}
+
+\begin{enumerate}
+\item Options set with `\objectset{<options>}` have the lowest priority.
+\item Options set for a specific style with `\objectset[<styles>]{<options>}` take precedence because they are set later (at the object, not the `\objectset` command).
+\item Options passed directly to the object have the highest priority.
+\end{enumerate}
+
+For example:
+
+\begin{examplecode}
+\objectset[figure]{placement=p}
+\objectset{placement=H}
+\objectset[table]{placement=htbp}
+\end{examplecode}
+
+Given the above preamble both figure- and tableobjects are floating.
+Tableobjects are allowed to be placed where they are specified in the source code.
+Figureobjects are put on a separate float page.
+The second line (which would disable floating) has no effect (unless you define a custom style) because it is overridden not only by the third but also the first line.
+
+
+\subsection{Environments}
+\label{environments}
+
+This package defines the following environments.
+Each of them takes exactly one mandatory argument,
+options as a comma separated key=value list.
+
+\subsubsection{`object` environment}
+\label{object-environment}
+\begingroup
+\keydocpath{/object}
+\DescribeEnv{object}
+The `object` environment is used internally by \env{figureobject} and \env{tableobject}.
+Don't use this directly.
+You can define more environments like `figureobject` or `tableobject` with \cmd{\NewObjectStyle} if needed.
+
+This environment redefines the `\caption` and `\label` commands to set the \key{caption}\slash `label` option so that you can use them as usual except you cannot create several labels.
+If you really need several labels for the same object put the additional `\label` command(s) inside of the caption argument, there `\label` has it's original meaning.
+The location or the order of `\caption` and `\label` inside of the object environment is not relevant.
+Nevertheless I recommend to always put the `\label` after the `\caption` as it is usually required in order to get the references right (if you choose to use these commands instead of the options).
+Where the caption is typeset (above or below the object) is determined by the float style.
+
+This environment takes the following options:
+\keydoc{type = <type>}{storing key}
+\DescribeMeta{type}
+ The floating environment to use, e.g.\ `figure` or \env{table}.
+\keydoc[initial value=empty]{float style = plain | plaintop | ruled | boxed | <empty>}{storing key}
+ How the object is supposed to look like,
+ most importantly whether the caption is supposed to be above or below the object.
+ See the \pkg{float} package for more information.
+
+ If the value is empty the float type is *not* restyled before the\slash each object.
+ However, this package restyles \env{table} to `plaintop` and `figure` to `plain` when it is loaded.
+ The reasoning is explained in~\autocite{texexchange_caption_position}.
+
+\keydoc{caption = <text>}{storing key}
+ The caption to place above or below the float.
+
+ The appearance of the caption can be configured using `\captionsetup` defined by the \pkg{caption} package.
+ The \pkg{caption} package is loaded automatically by this package.
+ If you want to change the horizontal alignment of the caption take a look at the options `justification` and `singlelinecheck`.
+\keydoc{list caption = <text>}{storing key}
+ The caption to place in the list of `<type>`s.
+ If this is not given, the value of \key{caption} is used instead.
+\keydoc{details = <text>}{storing key}
+ This is appended to the caption which is placed above or below the object but not to the list of `<type>`s.
+ \begin{examplecodekey}
+ caption=CTAN lion drawing by Duane Bibby,
+ details=Thanks to \url{www.ctan.org}.
+ \end{examplecodekey}
+ is equivalent to
+ \begin{examplecodekey\starred}{\ExamplecodeEscapeinside $ $}
+ list caption=CTAN lion drawing by Duane Bibby,
+ caption=CTAN lion drawing by Duane Bibby.$\\$ Thanks to \url{www.ctan.org}.
+ \end{examplecodekey\starred}
+\keydoc[initial value=a full stop followed by a space]{details sep = <text>}{storing key}
+ The separator to be placed between caption and details if details are given.
+\keydoc{label = <label>}{storing key}
+ Defines a label to reference this object.
+\keydoc{add label = <label>}{storing key}
+ Defines an additional label which can be used synonymously to label.
+ If this key is given several times, only the last one will have an effect.
+\keydoc[initial value=empty]{placement = [htbp]+!? | H | I | <empty>}{storing key}
+ The optional argument passed to the floating environment.
+ Allowed values:
+ \begin{itemize}
+ \item any combination of the letters `htbp` (where no letter is occurring more than once), optionally combined with an exclamation mark.
+ This means that the object will be a floating object.
+ The order of the letters makes no difference.
+ They have the following meanings:
+ \begin{itemize}
+ \item `h`: \LaTeX\ is allowed to place the object `h`ere, where it is defined.
+ \item `t`: \LaTeX\ is allowed to place the object at the `t`op of a page.
+ \item `b`: \LaTeX\ is allowed to place the object at the `b`ottom of a page.
+ \item `p`: \LaTeX\ is allowed to place the object on a separate `p`age only for floats.
+ \item `!`: \textcquote[page~27]{latex2e}{\LaTeX\ ignores the restrictions on both the number of floats that can appear and the relative amounts of float and non-float text on the page.}
+ \end{itemize}
+ \item \valdoc{H}: \LaTeX\ places the object exactly here, no matter how unfitting that may be.
+ In contrast to a single `h` or `h!` where the object is still a floating object which may float somewhere else if it does not fit here,
+ `H` means here and nowhere else.
+ `H` is defined by the \pkg{float} package which is loaded by this package automatically.
+ \item \valdoc{I}: \LaTeX\ places the object exactly here, considering the current line width and indentation.
+ `H` uses the full `\columnwidth`, just like a real float which floats here.
+ `I` respects the indentation of an `itemize`, shrinking the max used width to `\linewidth`.
+ This is a new placement defined by this package, using the code of `H` with two small changes.
+ `I` can only be used with the environments and commands defined by this package, it cannot be passed to a normal floating environment directly.
+ \item empty: do *not* pass the optional argument.
+ In this case the placement of the float can be changed using the `\floatplacement` command of the \pkg{float} package.
+ I have defined this key instead of advertising `\floatplacement` because `\floatplacement` does not allow the value~`H`.
+ \end{itemize}
+
+\keydoc[initial value=`\centering`]{align = <code>}{storing key}
+ \TeX\ code which is inserted at the beginning of the `<type>` environment.
+\keydoc[initial value=empty]{exec = <code>}{storing key} /
+\keydoc{exec += <code>}{executed key}
+ \TeX\ code which is inserted at the beginning of the `<type>` environment before align.
+ Can be used to define a command for this object, see \cref{local-definitions-in-tables}.
+\keydoc{graphic <option> = <value>}{unknown key handler}
+\keylinktarget{graphic width}
+\keylinktarget{graphic keepaspectratio}
+ Is applied to \cmd{\includegraphicobject} and \cmd{\includegraphicsubobject}.
+ Is ignored for other objects.
+
+ `<option>` can be any key which is unique to one of these two commands and any key allowed by the `\includegraphics` command (see \pkg{graphicx}\slash \pkg{graphbox} package).
+ Unlike `\setkeys{Gin}{<options>}` this works with all keys (compare \pkg{graphicx} documentation~\autocite[section~4.6]{graphicx}, unfortunately it's not getting more specific than \enquote{Most of the keyval keys}).
+
+ I am checking if the key is existing immediately but I cannot check the value (only whether it is required).
+ Therefore if you pass a wrong value the error message will not appear where you set this option but at the object where it is applied.
+
+ If you set `graphic width` globally and want to override it locally you can use `graphic width=!`.
+ This is a feature of the graphicx package but it is not well documented in it's documentation~\autocite{graphicx}.
+ (Which is why I am mentioning it here.)
+ The exclamation mark is mentioned for the `\resizebox` command.
+
+\bigpar
+
+\keydoc[initial value=empty]{env = <env>}{storing key}
+ The name of an additional inner environment in which the body is wrapped, e.g.\ `tabular`, \env{tabularx}, `tikzpicture`.
+ If empty the body is *not* wrapped in another environment (additional to object).
+
+ Please note that using this option can lead to difficult to find errors with confusing error messages
+ if you forget that you used it or it has a different value than you think it has.
+ In this case `show env args` may help you.
+
+ Please note that due to the way how environments are implemented in \LaTeX2 (this will change in \LaTeX3~\autocite{ltx3env})
+ it is not possible to check whether a given name is an environment or a command.
+ But if you pass something that is *not* defined you will get an error.
+
+ If you have loaded the \pkg{longtable} package (either with the package option \pkgoptn{longtable} or with a `\usepackage{longtable}`)
+ you can set the value of this key to \val{longtable}.
+ In that case the necessary changes are performed
+ so that the content of this object environment is set in a \env{longtable} environment
+ and does *not* float but can span across page breaks.
+ In this case `type`, `placement` and `align` are ignored.
+
+\keydoc{<env> arg = <value>}{unknown key handler}
+\keylinktarget{(<env>) arg(s) (+)}
+\keylinktarget{(<env>) arg(s)}
+\keylinktarget{tabularx arg+}
+\keylinktarget{tabularx arg}
+\keylinktarget{\detokenize{tabular* arg}}
+\keylinktarget{tabular arg}
+\NoDescribeKey{env arg}
+ The value is wrapped in braces and passed as argument to the additional inner environment if the value of `env` is not empty and `<env>` equals the value of `env`.
+ Arguments to this environment can be given as an argument to the `*object` environment as well but this key provides the possibility to pass arguments on a global level (or to override a globally passed argument).
+ For example this can be used to give all tabularx-tables a consistent width:
+
+ \begin{examplecode}
+ % in preamble
+ \objectset[table]{tabularx arg=.8\linewidth}
+
+ % in document
+ \begin{tableobject}{caption=Test Table, label=tab1, env=tabularx}{XX}
+ ...
+ \end{tableobject}
+ \end{examplecode}
+
+\keydoc{<env> args = <value>}{unknown key handler}
+ Same like `<env> arg` except that the value is *not* wrapped in braces.
+ This can be used to pass several arguments or an optional argument.
+ Please not that this key cannot be used to pass exactly one undelimited argument consisting of more (or less) than one token because `\pgfkeys` (which I am using internally) strips several levels of braces.
+\keydoc{arg = <value>}{unknown key handler}
+ If `env` has a non-empty value this is an abbreviation of `<env> arg` where `<env>` is the value of `env`.
+
+ Please note that because this key depends on the value of another key the order in which these two keys are given is important.
+
+ The value of `env` is considered when this key is evaluated.
+ If you use `\objectset[<styles>]{<options>}` (with it's optional argument) the processing of the keys is delayed but it makes some basic error handling already so that the line numbers are as fitting as possible.
+ For this error handling only the options passed to this call of the command are considered.
+ (Trying to consider previously set values correctly would make things more difficult because you might be applying these options to several styles at once where one might have `env` set and another not.)
+ Therefore the following causes an error message:
+
+ \begin{examplecode}
+ \objectset[table]{env=tabularx}
+ \objectset[table]{arg=.8\linewidth}
+ \end{examplecode}
+
+ While this would not:
+
+ \begin{examplecode}
+ \objectset{env=tabularx}
+ \objectset{arg=.8\linewidth}
+ \end{examplecode}
+
+ Anyway, I recommend to always use this option directly after `env` (if you intend to use it).
+ `env` and it's `args` belong together:
+
+ \begin{examplecode}
+ \objectset{env=tabularx, arg=.8\linewidth}
+ \end{examplecode}
+
+\keydoc{args = <value>}{unknown key handler}
+ If `env` has a non-empty value this is an abbreviation of `<env> args` where `<env>` is the value of `env`.
+ The notes on error handling of the `arg` key apply to this key as well.
+\keydoc{(<env>) arg(s) += <value>}{unknown key handler}
+ A plus sign can be appended to the key (patterns) `<env> arg`, `<env> args`, `args` and `arg`.
+ In that case a possibly previously passed argument is not overridden but this value is appended to it.
+ For example the following pattern allows to easily switch between tabular and tabularx tables on a global level:
+
+ \begin{examplecode}
+ % in preamble
+ \objectset[table]{tabularx arg=.8\linewidth, env=tabularx}
+ \newcolumntype{Y}{>{\raggedleft\arraybackslash}X}
+
+ % in document
+ \begin{tableobject}{caption=Test Table, label=tab1, tabular arg=lr, tabularx arg+=XY}
+ ...
+ \end{tableobject}
+ \end{examplecode}
+
+\bigpar
+
+\keydoc{first head = <code>}{storing key}
+ Is inserted at the beginning of the object (if `env` is non-empty: inside of the inner environment and after possibly specified `(<env>) arg(s)`).
+ If this is not given, `head` is used instead.
+\keydoc{last foot = <code>}{storing key}
+ Is inserted at the end of the object (if `env` is non-empty: inside of the inner environment).
+ If this is not given, `foot` is used instead.
+\keydoc[initial value=empty]{head = <code>}{storing key}
+ This value is used for `first head` if `first head` is not given.
+ If `env=longtable` this is the head after a pagebreak inside of the table.
+\keydoc[initial value=empty]{foot}{storing key}
+ This value is used for `last foot` if `last foot` is not given.
+ If `env=longtable` this is the foot before a pagebreak inside of the table.
+\keydoc{table head = <code>}{executed key}
+ This is a convenience key which sets `first head`, `last foot`, `head` and `foot`.
+ The value is the column headers without rules\slash lines and without the trailing `\\`.
+\keydoc[initial value=`(to be continued)`]{table break text = <text>}{executed key}
+ A text put in the `foot` by `table head`.
+\keydoc{table head style = <code>}{executed key}
+ Defines how `table head` fills out `first head`, `last foot`, `head` and `foot`.
+
+ Initial value:
+
+ \begin{examplecode}
+ {%
+ first head =
+ \toprule
+ #1 \\
+ \midrule,
+ head =
+ #1 \\
+ \midrule,
+ foot =
+ \midrule
+ \ifx\object at tableBreakText\@empty
+ \else
+ \multicolumn{\the\LT at cols}{r@\relax}{\object at tableBreakText}%
+ \fi,
+ last foot =
+ \bottomrule,
+ }
+ \end{examplecode}
+
+ (Note the curly braces which are required because the value contains commas and equal signs, see \cref{special-characters-in-options}.
+ `\the\LT at cols` is the number of columns of the longtable and `\object at tableBreakText` is the value of `table break text`.
+ Commands containing an @ in their name are internal commands and can only be used between `\makeatletter` and `\makeatother`, see also \autocite{texexchange_make_at}.)
+
+\bigpar
+
+\keydoc[initial value=`false`, default value=`true`]{show env args =? true | false}{boolean key}
+ Show the code which is assembled from the `env` and `(<env>) arg(s) (+)` keys before executing it.
+ See \cref{help}.
+ Please note that arguments may be given as additional arguments and not as `(<env>) arg(s) (+)` like in `\begin{tableobject}{env=tabular}{cl}`.
+ Such arguments are *not* shown by this key.
+ This key applies to subobjects as well.
+
+\keydoc[initial value=`true`, default value=`true`]{warn no caption =? true | false}{boolean key}
+ Give a warning if \key{caption} is *not* given.
+\keydoc[initial value=`true`, default value=`true`]{warn no label =? true | false}{boolean key}
+ Give a warning if `label` is *not* given.
+\keydoc[initial value=`false`, default value=`true`]{warn other env =? true | false}{boolean key}
+ Give a warning when `<env> args` is given if `env` does not have the value `<env>` and the value of `env` is not empty.
+ This applies to subobjects as well.
+
+ The \cmd{\objectset} command if used with it's optional argument does not set the options immediately but stores them in different macros for different object styles.
+ Therefore if you change this value for certain styles this change does not affect following `\objectset` commands.
+ Without the optional style argument, however, the change takes effect immediately.
+
+ In order to avoid duplicates this warning is printed only where the key is passed by the user
+ and *not* where it is applied implicitly because of a previous `\objectset[<styles>]{<options>}`.
+
+\keydoc[initial value=`false`, default value=`true`]{contains subobjects =? true | false}{boolean key} /
+\keydoc{sub =? true | false}{forwarding key}
+ Specifies that this object contains subobjects, see \cref{subobject-environment}.
+ Is relevant only if `env` is set.
+ The value of `env` is applied to the subobjects instead of this object.
+ This is not executed immediately but only after all options have been processed so that you do not need to pay special attention to pass `env` before `contains subobjects`.
+
+ If this is *not* given (or more precisely: if this is false)
+ and the value of `env` is *not* empty I look ahead whether the object contains a subobject.
+ If I find a subobject I pretend you had passed this option and print a warning.
+ I insist on you explicitly passing this option because the lookahead does not work in all situations.
+ It ignores space and `\par` tokens but if there is any other token before the subobject,
+ for example a `\small` to fit two tables side by side which are a little too wide
+ (which may not be the best solution but an easy quick fix)
+ or a `\typeout` for debugging,
+ the lookahead does not find the subobject (possibly) resulting in unpredictable errors.
+ For example if you set `env=tabular` it will most likely complain about an \errormessage{Illegal pream-token}
+ or about a \errormessage{Missing number, treated as zero} with `env=tabular*` because the required arguments are missing.
+\endkeydoc
+
+
+All `(<env>) arg(s) (+)` options apply to subobjects as well.
+
+Additionally the following options are passed through to the corresponding options of all subobjects inside of this object, they are all \keytype[forwarding key]{forwarding keys}.
+\newcommand{\TargetKey}[2]{/subobject/\stripsubobject #2\relax}%
+\def\stripsubobject subobject #1\relax{\stripoptplus{#1}}%
+See \env{subobject} environment.
+\forwardingkeydoc{subobject linewidth = <dimen>}
+\forwardingkeydoc{subobject sep = <code>}
+\forwardingkeydoc{subobject hor =? <code>}
+\forwardingkeydoc{subobject hor sep (+)= <code>}
+\forwardingkeydoc{subobject ver =? <code>}
+\forwardingkeydoc{subobject ver sep (+)= <code>}
+\forwardingkeydoc{subobject exec (+)= <code>}
+\forwardingkeydoc{subobject env = <env>}
+\forwardingkeydoc[target=/subobject/subcaptionbox]{subcaptionbox}
+\forwardingkeydoc[target=/subobject/subcaptionbox inner pos]{subcaptionbox inner pos = c | l | r | s | <empty>}
+\forwardingkeydoc[target=/subobject/subpage]{subpage}
+\forwardingkeydoc[target=/subobject/subpage outer pos]{subpage outer pos = c | t | b | T | B | auto | Auto | auto-inverted | Auto-inverted | <empty>}
+\forwardingkeydoc[target=/subobject/subpage height]{subpage height = <dimen>}
+\forwardingkeydoc[target=/subobject/subpage inner pos]{subpage inner pos = c | t | b | s | <empty>}
+\forwardingkeydoc[target=/subobject/subpage align]{subpage align = <code>}
+
+\forwardingkeydoc{subobject warn no caption =? true | false}
+\forwardingkeydoc{subobject warn no label =? true | false}
+\endkeydoc
+\endgroup
+
+You can also define your own options as shown in \cref{custom-options}.
+
+
+\subsubsection{`figureobject` environment}
+\label{figureobject-environment}
+\DescribeEnv{figureobject}
+Is used for inserting figures.
+Takes the same options like the \env{object} environment.
+It differs in the following initial values:
+\begin{itemize}
+\item `type=figure`
+\end{itemize}
+
+\subsubsection{`tableobject` environment}
+\label{tableobject-environment}
+\DescribeEnv{tableobject}
+Is used for inserting tables.
+Takes the same options like the \env{object} environment.
+It differs in the following initial values:
+\begin{itemize}
+\item `type=table`
+\end{itemize}
+
+
+\subsubsection{`subobject` environment}
+\label{subobject-environment}
+\begingroup
+\keydocpath{/subobject}
+\DescribeEnv{subobject}
+To be used inside of an `*object` environment if you want to place several images\slash tables\slash whatever together.
+See also \cmd{\includegraphicsubobject}.
+
+I recommend to *not* put anything between the subobjects manually so that you can control their positioning with the `hor` and `ver` options.
+(Spaces after a subobject are ignored but empty lines are not.)
+
+Unlike the `object` environment, `\caption` and `\label` *cannot* be used inside of the subobject environment.
+Use the \key{caption} and `label` options instead.
+
+There are two different backends available, both provided by the \pkg{subcaption} package.
+See the `subcaptionbox` and `subpage` keys.
+
+The `subobject` environment has exactly one mandatory argument, a comma separated list of the following options.
+
+
+The following options correspond to those of an `object`.
+See \cref{object-environment}.
+\newcommand{\TargetKey}[2]{/object/#2}%
+\correspondingkeydoc{label = <label>}{storing key}
+
+\correspondingkeydoc{caption = <text>}{storing key}
+
+\correspondingkeydoc{list caption = <text>}{storing key}
+
+ (The \pkg{subcaption} package disables subcaptions in the list of figures\slash tables\slash whatever by default.
+ To enable them use `\captionsetup[sub]{list=true}`.)
+\correspondingkeydoc{details = <text>}{storing key}
+
+\correspondingkeydoc{details sep = <text>}{storing key}
+
+\correspondingkeydoc{exec = <code>}{storing key} /
+\correspondingkeydoc{exec += <code>}{executed key}
+
+\correspondingkeydoc{graphic <option> = <value>}{unknown key handler}
+
+ (This key is completely useless.
+ It only has a meaning in the context of \cmd{\includegraphicsubobject} but there these options can be used directly without the prefix `graphic`.
+ I am allowing it anyway in order to support the same key like in \cmd{\objectset} which is supported by \cmd{\includegraphicobject} as well.)
+\correspondingkeydoc{env = <env>}{storing key}
+
+ (See also the `contains subobjects` option of the \env{object} environment.)
+\correspondingkeydoc{(<env>) arg(s) (+) = <value>}{unknown key handler}
+
+ (All values passed to the corresponding keys of the \env{object} environment apply to this option, too.)
+
+\correspondingkeydoc{warn no caption =? true | false}{boolean key}
+
+\correspondingkeydoc{warn no label =? true | false}{boolean key}
+
+\forwardingkeydoc[target=/object]{warn other env =? true | false}
+
+\forwardingkeydoc[target=/object]{show env args =? true | false}
+
+\endkeydoc
+
+The following options are unique for the `subobject` environment:
+\keydoc[initial value=`.5\linewidth`]{linewidth = <dimen>}{storing key}
+ The horizontal space available for the subobject.
+ The content of the subobject is centered within this width.
+ If two subobjects displayed side by side have a small width they may appear too far apart from each other with the initial value.
+ Then you can decrease this value so that they come closer together.
+ (With `subcaptionbox` this value may be empty.
+ In that case the subobject takes as much space as it needs
+ and `\linewidth` inside of the subobject is the same like in the parent object.)
+
+ If you want to place more than two subobjects side by side you must decrease this value accordingly.
+ Keep in mind that you need to consider the width of `hor sep` as well if you changed it.
+
+ Dimensions can be given relative to other dimensions or in numbers.
+ Aside from absolute units like `pt` or `cm` \TeX\ also recognizes units relative to the current font size: `em` and `ex`.
+ For more information on dimensions see \mycite[chapter~10]{texbook} or \mycite[chapter~8]{texbytopic}.
+
+\keydoc{sep = <code>}{storing key}
+ A separator which is inserted before each subobject except for the first subobject inside of the current parent object.
+
+\keydoc[default value=empty]{hor =? <code>}{executed key}
+ Set the value of `sep` to the value of `hor sep` so that the subobjects are placed side by side.
+ If you pass a value the value will be appended to `sep` after setting it to `hor sep`.
+
+ Please note that options are only valid until the end of a group.
+ Therefore if you use this inside of a subobject it does *not* apply for the following subobject.
+ Instead use `subobject hor` on the parent object.
+
+\keydoc[initial value=empty]{hor sep = <code>}{storing key} /
+\keydoc{hor sep += <code>}{executed key}
+ The separator to be used if the subobjects are suppossed to be placed side by side.
+
+ Please note that `hor` must be used *after* setting this key, otherwise this option will not take effect.
+
+\keydoc[default value=empty]{ver =? <code>}{executed key}
+ Set the value of `sep` to the value of `ver sep` so that the subobjects are placed below each other.
+ If you pass a value the value will be appended to `sep` after setting it to `ver sep`.
+
+ Please note that options are only valid until the end of a group.
+ Therefore if you use this inside of a subobject it does *not* apply for the following subobject.
+ Instead use `subobject ver` on the parent object.
+
+\keydoc[initial value=`\par\bigskip`]{ver sep = <code>}{storing key} /
+\keydoc{ver sep += <code>}{executed key}
+ The separator to be used if the subobjects are suppossed to be placed below each other.
+
+ Please note that `ver` must be used *after* setting this key, otherwise this option will not take effect.
+
+\bigpar
+
+\keydoc{subcaptionbox}{executed key}
+ The \pkg{subcaption} package provides several possibilities to insert subobjects.
+ This option tells the subobject environment to use the `\subcaptionbox` command instead of the `subfigure` or `subtable` environment, see option `subpage`.
+ (This key does *not* take a value.)
+
+ This option allows to pass an empty value to `linewidth`.
+ It can be useful if you have subobjects with a small width
+ so that you don't need to try different `subobject linewidth`s.
+ The example in \cref{subobjects-2} could be rewritten as following:
+
+ \inputexamplecode{../test/exp-subcaptionbox}
+
+ Note that this works only if the subobject captions are very short.
+ If they are wider than the content the line breaks which looks ugly.
+
+ If you want to use this option with `env=tabular` (or similar) you must pass the column specification with the option `arg=lr` (instead of as a separate argument).
+ Otherwise you will get the error message \errormessage{Package array Error: Illegal pream-token (\BODY): `c' used.}
+
+ This option is *not* compatible with `env=tabularx` and does *not* allow verbatim content inside of the subobject.
+ You can try to work around the verbatim limitation
+ (1)~by saving the problematic content in a macro before hand using commands such as `\urldef` from the \pkg{url} package,
+ (2)~by using commands which replace tokens such as `\mintinline` from the \pkg{minted} package (does not work with catcodes which do not produce tokens -- most importantly the comment character \formatchar\%),
+ (3)~by changing the problematic catcodes before the `subobject` (but you still need \emph{some} escape, begin group and end group characters in order to start and end the subobject -- but which do not need to be the default characters \formatchar\\, \formatchar\{ and \formatchar\}),
+ (4)~by defining a macro before hand under what ever catcode regime you want, you can even append contents from yet another catcode regime using the `\gappto` command from the \pkg{etoolbox} if you want.
+ If you want to learn more about catcodes (category codes) see \mycite[chapter~7]{texbook} or \mycite[chapter~2]{texbytopic}.
+ But the easier way is probably to use `subpage` instead -- that's why it's the initial backend.
+
+ \MakeLinkTarget{}
+ \label{exp:subcaptionbox-limitations}
+ \inputexamplecode{../test/exp-subcaptionbox-defverb}
+
+ `\NewDocumentCommand` is documented in~\autocite{usrguide}.
+
+\keydoc{subcaptionbox inner pos = c | l | r | s | <empty>}{storing key}
+ The horizontal position of the content in the box.
+ Also allowed is any justification defined with `\DeclareCaptionJustification`
+ (see the \pkg{caption} package documentation).
+ An empty value means that this optional argument is
+ *not* passed to the `\subcaptionbox` command.
+ This option has no effect if `linewidth` is empty.
+ I discourage using this option because it destroys
+ the alignment of (sub)object and (sub)caption.
+
+\bigpar
+
+\keydoc{subpage}{executed key}
+ This is (after `subcaptionbox`) the second and initial backend for the `subobject` environment.
+ It uses the `subfigure`\slash `subtable` environment defined by the \pkg{subcaption} package.
+ (Since version 1.5 the \pkg{subcaption} package also provides the more generic `subcaptionblock` environment but this package still uses the old `subfigure` and `subtable` environments.
+ `subfigure` and `subtable` are nowadays specialized versions of `subcaptionblock` which have no other difference than that they produce if a warning if they are used with a different main object type.)
+ (This key does *not* take a value.)
+
+ The `subfigure` and `subtable` environments are minipages and take the same arguments
+ which can be set with `linewidth`, `subpage outer pos`, `subpage height` and `subpage inner pos`.
+ Both the content and the caption go inside of the minipage.
+
+ If the subobjects are placed next to each other this option requires that either the contents or the captions of the subobjects have the same height and that `subpage outer pos` is set accordingly.
+ Otherwise the captions will not be aligned.
+
+\keydoc[initial value=`auto`]{subpage outer pos = c | t | b | T | B | auto | Auto | auto-inverted | Auto-inverted | <empty>}{storing key}
+ The vertical position of the minipage (containing both content and caption) on the baseline.
+
+ Additionally to the values `t`, `c` and `b` supported by the minipage environment
+ the \pkg{subcaption} package v1.2 adds the allowed values `T` and `B`
+ and this key also allows the values `auto`, `Auto`, `auto-inverted`, `Auto-inverted` and empty.
+
+ While `t` and `b` align the top\slash bottom *baseline* of the content
+ `T` and `B` align the very top\slash bottom of the content.
+
+ `c` aligns the center of the content.
+
+ `auto` means `t` if the caption is displayed at the top
+ or `b` if the caption is displayed at the bottom
+ so that the captions are aligned if the \emph{captions} have the same height.
+
+ `auto-inverted` means `b` if the caption is displayed at the top
+ or `t` if the caption is displayed at the bottom
+ so that the captions are aligned if the \emph{contents} have the same height
+ (although the height of the top most row does not count in this regard so `auto-inverted` is also good for graphics with different heights).
+
+ `Auto` and `Auto-inverted` behave like their lower case versions but use `T`/`B` instead of `t`/`b`.
+
+ If content and captions have different heights `auto-inverted` gives good results for `\includegraphicsubobject`.
+ For tables `subcaptionbox` is required to align the caption (but note the limitations regarding verbatim content).
+ If `subcaptionbox` does not work for you you can try `subpage outer pos = c` or giving the shorter caption the same height with `\\~` and then using `subpage outer pos = auto`.
+
+ If a subobject has neither caption nor label `auto` may not work as expected.
+ Instead `Auto` can be used which is based on `T` and `B` instead of `t` and `b`.
+ Note that `Auto` requires version 1.2 or newer of the \pkg{subcaption} package.
+
+ Empty is equivalent to `c`.
+
+ Except for the values which are added by this package (e.g.\ `auto` and `auto-inverted`)
+ all other values are passed through to the `subfigure`/`subtable` environment which silently ignores invalid values.
+
+
+\keydoc[initial value=empty]{subpage height = <dimen>}{storing key}
+ The height of the minipage.
+ An empty value means that this optional argument is
+ *not* passed to the `subfigure`\slash `subtable` environment.
+
+ Dimensions can be given relative to other dimensions or in numbers.
+ Aside from absolute units like `pt` or `cm` \TeX\ also recognizes units relative to the current font size: `em` and `ex`.
+ For more information on dimensions see \mycite[chapter~10]{texbook} or \mycite[chapter~8]{texbytopic}.
+
+\keydoc[initial value=empty]{subpage inner pos = c | t | b | s | <empty>}{storing key}
+ The vertical position of the content on the minipage.
+ Empty means that this optional argument is
+ *not* passed to the `subfigure`\slash `subtable` environment.
+ This option has no effect if `subpage height` is empty.
+
+\keydoc[initial value=`\centering`]{subpage align = <code>}{storing key}
+
+ \TeX\ code which is inserted at the beginning of the `subfigure`\slash `subtable` environment.
+\endkeydoc
+
+If you want to change the numbering of subobjects please refer to the \pkg{subcaption} package documentation~\autocite[section~5 \sectionname{The `\DeclareCaptionSubType` command}]{subcaption}.
+The \pkg{subcaption} package is loaded automatically by this package.
+\endgroup
+
+
+\subsection{Commands}
+\label{commands}
+
+In this section I am describing the commands defined by this package.
+
+
+\subsubsection{`\includegraphicobject` command}
+\label{includegraphicobject-command}
+\begingroup
+\keydocpath{/graphicobject}
+\DescribeMacro{\includegraphicobject}
+`\includegraphicobject{<filename>}` \\
+`\includegraphicobject[<options>]{<filename>}` \\
+`\includegraphicobject[<style>][<options>]{<filename>}`
+
+Is used for inserting graphics from a different file.
+It is very similar to \pkg{graphicx}' `\includegraphics` command, except that the graphic is automatically set in a \env{figureobject} environment.
+You can change this by setting the object style with \cmd{\graphicobjectstyle} or an additional optional argument given *before* the usual optional argument.
+The mandatory argument is the same: The name of the graphics file to include *without* the file extension.
+The optional argument accepts---aside from all the options defined by \pkg{graphicx}\slash \pkg{graphbox}---also all options of the \env{figureobject} environment.
+Additionally there are the following unique options:
+\keydoc[initial value=`true`, default value=`true`]{auto caption =? true | false}{boolean key}
+ If no \key{caption} is given the file name is used as caption.
+ All underscores in the file name are replaced by `\textunderscore`.
+ This option is intended to be used on a global level but works in the optional argument of this command as well.
+\keydoc[initial value=`false`, default value=`true`]{auto caption strip path =? true | false}{boolean key}
+ If `auto caption` is true and the file name is used as caption
+ a possibly leading path is stripped (everything before and including the last slash in `<filename>`).
+ This is initially false because I am assuming that in most cases where the path should not be displayed `\graphicspath{{path/}}` would be used.
+\keydoc[initial value=`true`, default value=`true`]{auto label =? true | false}{boolean key}
+\keylinktarget{/object/graphic auto label}
+ If no `label` is given the file name is used as label.
+ This option is intended to be used on a global level but works in the optional argument of this command as well.
+\keydoc[initial value=`false`, default value=`true`]{auto label strip path =? true | false}{boolean key}
+ If `auto label` is true and the file name is used as label
+ a possibly leading path is stripped (everything before and including the last slash in `<filename>`).
+ This is initially false because I am assuming that in most cases where the filename without path is unique `\graphicspath{{path/}}` would be used.
+\keydoc[initial value=`<empty>`]{auto label prefix = <prefix>}{storing key}
+\keylinktarget{/object/graphic auto label prefix}
+ If `auto label` is true and the file name is used as label
+ prepend `<prefix>` to the label.
+\keydoc[initial value=`true`, default value=`true`]{warn env =? true | false}{boolean key}
+ Give a warning if `env` is not empty.
+\keydoc[initial value=`true`, default value=`true`]{no env =? true | false}{boolean key}
+ Reset `env` to an empty value.
+ This happens after evaluating `warn env`.
+\keydoc[initial value=`<empty>`]{before graphic = <code>}{storing key}
+ Arbitrary \TeX\ code to be inserted before the `\includegraphics`.
+\keydoc[initial value=`<empty>`]{after graphic = <code>}{storing key}
+ Arbitrary \TeX\ code to be inserted after the `\includegraphics`.
+\endkeydoc
+
+You may not use this command inside of an `*object` environment.
+Otherwise you will get an \errormessage{object environment may not be nested} error.
+See also \cmd{\includegraphicsubobject}.
+\endgroup
+
+\subsubsection{`\includegraphicsubobject` command}
+\label{includegraphicsubobject-command}
+\DescribeMacro{\includegraphicsubobject}
+`\includegraphicsubobject{<filename>}` \\
+`\includegraphicsubobject[<options>]{<filename>}`
+
+To be used if you want to place several graphics from different files in one object.
+
+It takes the same options like \cmd{\includegraphicobject} except that it takes options for the \env{subobject} environment instead of options for the `object` environment.
+Also it does *not* take the optional `<style>` argument.
+
+You may not use this command outside of an `*object` environment.
+Otherwise you will get a \errormessage{subobject environment may not be used outside of an object} error.
+See also \cmd{\includegraphicobject}.
+
+
+\subsubsection{`\splitobject` command}
+\label{splitobject-command}
+\DescribeMacro{\splitobject}
+`\splitobject`
+
+This can be used inside of an `object` environment which is too big to fit on one page.
+It splits an object so that it can be broken across pages.
+This command must be used directly inside of the object,
+it cannot be used inside of subgroups/environments inside of the object.
+It uses the `\ContinuedFloat` command defined by the \pkg{caption} package.
+See the example in \cref{split-object-example}.
+
+The `label` is placed on the first part of the object.
+If you want to specify the second part of the object you can use the `\label{<second-label>}` command after `\splitobject`.
+
+
+\subsubsection{Setting options globally}
+\label{setting-options-globally}
+
+\DescribeMacro{\objectset}
+`\objectset{<options>}` \\
+`\objectset[<styles>]{<options>}`
+
+Sets the passed options for all following objects until the end of the current group.
+All options of the \env{object} environment are allowed.
+
+A comma separated list of styles or style groups can be given in an optional argument.
+In that case the options are not set immediately but appended to the specified style(s).
+The options are set locally for any following object of the specified style(s) in the same group.
+Although setting the options is delayed the options are checked immediately so that error messages and warnings point to the line where the option is specified in the code, not where it is technically set.
+(In order for that to work properly it is important that options are specified with the key name only and not with the full path, see \cref{key-name-vs-key-path}.)
+However, the value can usually *not* be checked immediately, only whether it is required or not.
+Therefore if you pass a wrong value the error message will not appear where you set this option but at the object where it is applied.
+An exception is the key `env` where the value is checked immediately for plausibility whether it might be the name of an environment.
+
+If `<styles>` is empty or an empty group the options are not applied.
+No error or warning is printed.
+
+There is a style group called `all` which all styles belong to.
+`\objectset{<options>}` and `\objectset[all]{<options>}` are mostly equivalent
+except that the former (without optional argument) is more efficient because it sets the options immediately
+and the latter (with the optional argument given) is able to override options set for a style.
+
+
+\DescribeMacro{\graphicobjectstyle}
+`\graphicobjectstyle{<style>}` can be used to change the object style used by \cmd{\includegraphicobject}.
+For example, if you have a single table in a file called \filename{catcodes.pdf} you can insert it as following.
+Alternatively, you can use the optional `<style>` argument.
+
+\begin{examplecode}
+\begingroup
+\graphicobjectstyle{table}
+\includegraphicobject[caption=Catcodes]{catcodes}
+\endgroup
+\end{examplecode}
+
+
+\DescribeMacro{\graphicspath}
+`\graphicspath{{path/}}`: see \pkg{graphicx} package documentation~\autocite[section~4.5]{graphicx}.
+
+
+\subsubsection{New object styles and types}
+\label{new-object-styles-and-types}
+
+This section explains how to define a new object `<style>` in the sense of \cref{styles}.
+It is *not* about how to define a new `<floatstyle>` which can be used as value for the `float style` key.
+Examples are given in \cref{new-object-style-tikzobject} and \cref{exp:new-object-type}.
+
+\DescribeMacro{\NewObjectStyle}
+`\NewObjectStyle{<style>}{<options>}`
+defines a new environment called `<style>object` analogous to `figureobject` and `tableobject`.
+`<options>` are set for the new object style as if you had used `\objectset[<style>]{<options>}`.
+You must always specify the `type`.
+If this package is loaded without `allowstandardfloats`
+the float environment which is passed to `type` is redefined to issue a warning that `<style>object` should be used instead.
+This warning should not influence the environment's usual behavior.
+If the float environment was already passed as `type` to a previous call of `\NewObjectStyle` it is not redefined again but `<style>object` is appended to the list of replacement suggestions.
+
+If you define a new object style you may also want to define a new float type.
+The \pkg{float} package (which is automatically loaded by this package) defines the following command for doing so:
+
+\DescribeMacro{\newfloat}
+`\newfloat{<type>}{<placement>}{<ext>}[<within>]`
+\begin{itemize}
+\item `<type>` is the floating environment to be defined.
+ This value is also used as the float name which is displayed in front of the caption, therefore it should be capitalized.
+ Alternatively the name can be changed using `\floatname{<type>}{<name>}`.
+\item `<placement>` is the value to be used if the `placement` key is not given (or has an empty value).
+ This is initially `tbp` for the standard float types.
+\item `<ext>` is the extension of a file used to save the list of `<type>`s.
+ This is `lof` (list of figures) for `type=figure` and `lot` (list of tables) for `type=table`.
+ This file extension should be unique.
+\item `<within>` is a counter whose value is prepended to the `<type>` counter. The `<type>` counter is reset every time the `<within>` counter is incremented.
+\item Make sure an appropriate default float style is active when using `\newfloat`.
+ The default float style can be activated using `\floatstyle{<floatstyle>}`, see the \pkg{float} package documentation~\autocite{float}.
+ It should be `plain` for something like an image or `plaintop` for something like a table.
+ The reasoning is explained in~\autocite{texexchange_caption_position}.
+ Alternatively you can specify the float style using the `float style` key in the `<options>` of `\NewObjectStyle`.
+\end{itemize}
+
+\DescribeMacro{\crefname}
+\DescribeMacro{\Crefname}
+If you are using the \pkg{cleveref} package (which I recommend you do) you also need to tell it how to reference the new float type with `\crefname{<type>}{<singular>}{<plural>}`.
+If you want an abbreviation in the middle of a sentence but the full word at the beginning of the sentence you specify the beginning of the sentence with `\Crefname` and the middle of the sentence with `\crefname`.
+
+`\NewObjectStyle` automatically defines the corresponding environment needed for `subobject` if possible, i.e.\ if the \pkg{caption} package is new enough.
+If the \pkg{caption} package is older than August~30, 2020 and you want to use subobjects you need to define the subtype manually by putting the following line *before* loading this package \autocite{texexchange_subtype_workaround}:
+\begin{examplecode}
+\AtBeginDocument{\DeclareCaptionSubType{<type>}}
+\end{examplecode}
+
+\DescribeMacro{\trivfloat}
+The \pkg{trivfloat} package provides the `\trivfloat{<type>}` command which is an easier alternative to `\newfloat`.
+If you use it you should be aware that it does not define the new float type environment immediately but at `\begin{document}`.
+This does *not* affect `\NewObjectStyle` (you can still use it directly afterwards)
+but it means that the float style active at `\begin{document}` is applied and not the float style active at `\trivfloat`.
+Therefore I recommend to pass the `float style` option to `\NewObjectStyle`,
+then it does not matter which float style was active when the float type was defined because it is restyled before each use of an object where this option applies.
+`\trivfloat` must be used before `\AtBeginDocument{\DeclareCaptionSubType{<type>}}`.
+
+\DescribeMacro{\DeclareFloatingEnvironment}
+The \pkg{newfloat} package provides the `\DeclareFloatingEnvironment[<options>]{<type>}` command which is a newer alternative to `\newfloat` and `\trivfloat`.
+With it's key=value options it is more intuitive than `\newfloat` and more flexible than `\trivfloat`.
+Unlike `\newfloat` and `\trivfloat` it automatically capitalizes `<type>` before using it as float name.
+It seems to ignore `\floatstyle` so you need to specify that in the options.
+The \pkg{newfloat} package is written by the same author like the \pkg{subcaption} package so you don't need to worry about defining subtypes manually.
+
+
+\subsubsection{New object style groups}
+\label{new-object-style-groups}
+
+Several object styles can be combined to a group.
+You can set options for all styles contained in a group using `\objectset[<group>]{<options>}`.
+
+\DescribeMacro{\NewObjectStyleGroup}
+`\NewObjectStyleGroup{<group>}{<styles*>}`
+defines a new style group consisting of the styles `<styles*>`.
+`<styles*>` is a comma separated list of styles.
+In contrast to `<styles>` it may *not* contain style groups.
+
+\DescribeMacro{\AddObjectStyleToGroup}
+`\AddObjectStyleToGroup{<group>}{<style>}`
+adds an existing style to an existing group.
+
+
+\subsubsection{Hooks}
+\label{hooks}
+
+This package provides several commands similar to `\AtBeginDocument`
+which take one argument, \TeX\ code which is executed at a later point in time.
+
+
+\DescribeMacro{\AtBeginObject}
+`\AtBeginObject{<code>}`
+ runs `<code>` every time at the begin of an \env{object} environment
+ (including \env{figureobject}, \env{tableobject} and \cmd{\includegraphicobject}).
+ This hook is inside of the group but before any options are processed.
+
+\DescribeMacro{\AtBeginSubobject}
+`\AtBeginSubobject{<code>}`
+ runs `<code>` every time at the begin of a \env{subobject} environment
+ (including \cmd{\includegraphicsubobject}).
+ This hook is inside of the group but before any options are processed.
+
+\DescribeMacro{\AtBeginGraphicObject}
+`\AtBeginGraphicObject{<code>}`
+ runs `<code>` every time in \cmd{\includegraphicobject} and \cmd{\includegraphicsubobject}.
+ This hook is after the object\slash subobject hook but before any options are processed.
+
+\DescribeMacro{\AtEndObject}
+`\AtEndObject{<code>}`
+ runs `<code>` every time at the end of an \env{object} environment
+ (including \env{figureobject}, \env{tableobject} and \cmd{\includegraphicobject}).
+ This hook is after a potential `env` has been closed but before the caption and label are processed.
+ (Yes, caption and label are always processed in `\end` even if the caption is displayed above the float.
+ The \pkg{float} package is responsible for putting the caption where it belongs.)
+
+
+\subsection{Initialization}
+\label{initialization}
+
+This package uses the \pkg{float} package to restyle \env{table} to `plaintop` and `figure` to `plain`
+so that captions of tables appear always above the table and captions of figures always below the figure.
+The reasoning is explained in~\autocite{texexchange_caption_position}.
+If you really want to place captions differently you can do that with `\restylefloat` (see \pkg{float} package documentation~\autocite{float}) or by setting the `float style` option.
+However, I would advice to rethink why you would want to do that.
+
+Unless this package is loaded with the \pkgoptn{allowstandardfloats} option
+it redefines the \env{table} and `figure` environments to issue a warning if they are used directly.
+This warning should not influence their usual behavior, though.
+Instead of \env{table}\slash `figure` you should use \env{tableobject}\slash \env{figureobject} or \cmd{\includegraphicobject},
+otherwise this package cannot help you.
+
+Unless this package is loaded with the \pkgoptn{nographic} option
+it loads the \pkg{graphicx} package in order to include graphics.
+This also guarantees that the paper size of the generated pdf matches \LaTeX' point of view (instead of depending on the system settings).~\autocite{texexchange_papersize}
+
+Unless this package is loaded with the \pkgoptn{noarray} option
+it loads the \pkg{array} package which defines additional column specification features like `>{<prefix>}`, `<{<suffix>}` and `!{<addcolsep>}`
+and the `\newcolumntype{<col>}[<args>]{<spec>}` command.
+It also changes the implementation of how lines (rules) are drawn
+but that is irrelevant if you use the recommendations given in the \pkg{booktabs} package documentation~\autocite[section~2 \sectionname{The layout of formal tables}]{booktabs}.
+Loading the \pkg{array} package is merely for convenience. This package does not use any of it's features.
+
+Unless this package is loaded with the \pkgoptn{nobooktabs} option
+it loads the \pkg{booktabs} package which defines commands for formatting tables, most importantly `\toprule`, `\midrule` and `\bottomrule`.
+These are used by the `table head` key unless you redefine it using `table head style`.
+
+Other packages loaded by this package are listed in \cref{used-packages}.
+
+
+\subsection{Package options}
+\label{package-options}
+
+The package options are implemented using the standard \LaTeX\ package options handling functionality as described in~\autocite{clsguide}.
+Therefore they do *not* take any values but consist of keys only.
+Instead I usually provide two separate keys, one which enables an option and another which disables the option.
+The keys with a~\radioon\ are active by default and the keys with a~\radiooff\ are inactive by default.
+
+\pkgoptndoc*{graphicx} use the \pkg{graphicx} package as backend for \cmd{\includegraphicobject}.
+\pkgoptndoc{graphbox} use the \pkg{graphbox} package as backend for \cmd{\includegraphicobject}.
+\pkgoptndoc{nographic} do not load \pkg{graphicx} or \pkg{graphbox}.
+ If you use this option the commands \cmd{\includegraphicobject} and \cmd{\includegraphicsubobject} are not defined.
+
+ Warning: Without driver specific packages like \pkg{graphicx}, \pkg{geometry} or \pkg{hyperref} the paper size of the resulting pdf depends on the system settings, independent of what you set in \LaTeX. \autocite{texexchange_papersize}
+
+\pkgoptndoc*{array} load the \pkg{array} package.
+ There is no difference between using this package option or a separate `\usepackage{array}`.
+\pkgoptndoc{noarray} do *not* load the \pkg{array} package.
+
+\pkgoptndoc*{booktabs} load the \pkg{booktabs} package.
+ There is no difference between using this package option or a separate `\usepackage{booktabs}`.
+\pkgoptndoc{nobooktabs} do *not* load the \pkg{booktabs} package.
+ Please note that the `table head` key initially relies on the booktabs package.
+ If you want to use it with this package option you need to redefine it with `table head style`.
+ Please read sections 1 and~2 of the \pkg{booktabs} documentation~\autocite{booktabs} before deciding against \pkg{booktabs}.
+
+\pkgoptndoc{longtable} load the \pkg{longtable} package.
+ There is no difference between using this package option or a separate `\usepackage{longtable}`.
+\pkgoptndoc*{nolongtable} do *not* load the \pkg{longtable} package.
+
+\pkgoptndoc{allowstandardfloats} do not redefine the \env{table} and `figure` environments.
+ Without this option they are redefined to issue a warning if they are used directly.
+ This warning should not influence their usual behavior.
+ Instead of \env{table}\slash `figure` you should use \env{tableobject}\slash \env{figureobject} or the command \cmd{\includegraphicobject},
+ otherwise this package cannot help you.
+\endpkgoptndoc
+
+
+\subsection{Help}
+\label{help}
+
+If you get an error message and don't understand where it comes from
+or the output is different from what you expected
+the following features may give you a better understanding of what this package is doing.
+These features are based on the \TeX\ primitive `\show`.
+
+\DescribeMacro{\show}
+`\show` shows (among other information) the parameter text and the replacement text of a macro on the terminal and in the log file.
+If you use one of the following features you most likely want to know the replacement text which is the part between `->` and the last `.` on the line.
+In errorstopmode mode (i.e.\ without `--interaction=nonstopmode` which most IDEs pass by default) \TeX\ stops after `\show` and waits until you confirm that you have read the information and it may proceed by pressing enter.
+For more information see \mycite[section~34.1]{texbytopic}.
+
+\DescribeHandler{.show value}
+The `.show value` handler can be used to show the value of a \keytype{storing key}
+(see \pkg{pgfkeys} documentation~\autocite[section~87.4.9 \sectionname{Handlers for Key Inspection}]{tikz}).
+For example:
+
+\begin{examplecode}
+\includegraphicsubobject[sep/.show value]{<filename>}
+\end{examplecode}
+
+\DescribeHandler{.show boolean}
+This package also defines a new handler called `.show boolean` which can be used to show the value of a \keytype{boolean key}.
+For example:
+
+\begin{examplecode}
+\objectset{warn other env/.show boolean}
+\end{examplecode}
+
+\DescribeMacro{\ShowObjectStylesInGroup}
+`\ShowObjectStylesInGroup{<group>}` shows all object styles which are contained in the given group.
+The styles are wrapped in curly braces so that I can iterate over them with the \LaTeX\ command `\@tfor`.
+
+\DescribeMacro{\ShowObjectStyleOptions}
+`\ShowObjectStyleOptions{<style>}` shows the options set for a specific style.
+Please note that this does *not* show directly set options (i.e.\ options set by `\objectset` without the optional argument and options in the options argument of the object).
+
+\DescribeKey{show env args}
+See also the `show env args` key of the \env{object} and \env{subobject} environments.
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s3_documentation.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s4_installation.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/s4_installation.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/s4_installation.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,16 @@
+% !TeX root = ../easyfloats.tex
+
+\section{Installation}
+\label{installation}
+
+This package is contained in \TeX~Live (latex-extra) and MiK\TeX.
+Therefore it is probably already installed on your system if you have a full \LaTeX\ installation.
+In case it is not you can install it
+on Arch-Linux with \formatcode{pacman -S texlive-latexextra}
+or on Debian with \formatcode{apt install texlive-latex-extra}.
+
+If your \TeX\ distribution is old and you want to use the newest version of this package
+download the sty-file from \url{https://gitlab.com/erzo/latex-easyfloats/-/blob/master/easyfloats.sty?ref_type=heads}
+and put it next to your main document.
+(Or, if you care about readability of the source code, download the dtx-file instead and change it's extension to sty.
+ The dtx-file contains indentations and more comments and is therefore easier to read for humans but slower to parse for \TeX.)
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s4_installation.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s5_bug-reports-and-contributions.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/s5_bug-reports-and-contributions.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/s5_bug-reports-and-contributions.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -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}
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s5_bug-reports-and-contributions.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s6_changelog.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/s6_changelog.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/s6_changelog.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,88 @@
+% !TeX root = ../easyfloats.tex
+
+\addtocontents{toc}{\protect\setcounter{tocdepth}{1}}
+
+\section{Change log}
+The Gitlab symbols are links to the corresponding commit/tag on Gitlab.
+
+\begin{changelog}
+\changesinversion{v1.1.0}
+
+New features:
+- `placement = I`
+ \commit 05d13be6b7a6c79eb6fc2c7625372a8068d6dab9
+- `\splitobject`
+ \commit 19df2f6ba1565b7b8d1685410937c6d3cd7d22a8
+- `subpage outer pos = auto-inverted|Auto-inverted`
+ \commit 79ccf8d6b9e66f4629059fab4b93ff32f49ddfba
+- `auto label prefix`
+ \commit 0e59759ba22e26a081f5c943efdab4325593896e
+- `\AtEndObject`
+ \commit 2a38c33717406d620eb79b51f35873e50acd220c
+
+Bugfixes:
+- close all groups which `\includegraphicobject` opens
+ \commit 52783c7ca6a7ed89f4c2610e18996c5737a81274
+- don't indent subobjects on 2nd/3rd/xth line
+ \commit 1793809c2430b1c35c5b51b5bdd5ecdc23202075
+
+Documentation additions:
+- new example: custom options, \cref{custom-options}
+ \commit d6a2818d0405a5dd8e5fd581a2ae9f7588289064
+- new example: \pkg{varioref}, \cref{vref}
+ \commit f6754fe70e90aa81c201ec58fe31bf416a47efa9
+- new example: subfigures, \cref{exp:subfigures}
+ \commit ce6e49151630f74815da161e1df718092dfce9b9
+- new example: how to create new float type, \cref{exp:new-object-type}
+ \commit 73942fff3a4c3cf385c300e25efc0275083b68f5
+- new example: how to circumvent subcaptionbox limitations, \cref{exp:subcaptionbox-limitations}
+ \commit 96ae47cbab2d1d3185f2acb8ae9ca91f012d8e5e
+- added more background information to the first example
+ \commit 573f5116795fa9e2211da54ed909a04055b8ccc2
+- how to achieve a different graphics width for subfigures
+ \commit b2d1d65696675056fa35aaf8a83827b99fa2d7f3
+- revised subobjects example
+ \commit b5d368f11141e7c35cded3c10be8836d58073012
+- added note which LaTeX version has been used for testing
+ \commit d1d412bf29f3f30229c4c3b6bab38865bf39421f
+- added more info to examples
+ \commit b3b2de787075ef87da431f91c5a6f0dfb7eee8f1
+- mention TikZ library perspective
+ \commit 7b7dcda1656af9d5467e5d179ba367066890d51c
+- `\crefname`
+ \commit 9b6c609349235bf5e0779beb1eceea5f9067a7cb
+- `\Crefname`
+ \commit e0f7c551313e606e94b8b969386fb197f90a5683
+- show texdoc command to open the corresponding document in \cref{references}
+ \commit 193e5bf28b9d5fb747a74f9c049698fdabfadb27
+
+Documentation updates:
+- updated section regarding the installation
+ \commit 463f9c01ce17d45e64fe0f028216b1cace7a7ab5
+- `\floatplacement{figure}{H}` works nowadays
+ \commit 5a76cc9cccec893ccab651bcc3f263906d237120
+
+Documentation fixes:
+- fixed wrong example, \cref{new-object-style-tikzobject}
+ \commit bd9c60e89b8d2bf4b4c80e3d855261e1a53e9624
+- added initial value of `table break text` to documentation
+ \commit 4e9f3eb8e843e9826111882d1c30096652f36c40
+- table break text is an executed key, not a storing key
+ \commit c0eb27b32d1bae315a1d8c921fba1a0233411f8e
+- fixed typos
+ \commit 63d9bdcf40487a61e666045f449ff5cd8daeedd6
+ \commit 1b22b422b8a9b816f8ce67050b28e3ccd9121260
+- cleveref noabbrev: reworded to make it a neutral statement
+ \commit 556fb4888a52b5b53885a8e353d29fc5d3e152ab
+- show correct tilde symbols
+ \commit b4ba76f1d5144c6d9c4002abcd2640a1077259d7
+- updated comment on \pkg{lmodern}
+ \commit 6d62a4b0768bc16df1deeccb4c2423fff7528459
+- set label in first two examples instead of suppressing the warning
+ \commit 5b84ceed5afba69081569a460b726091ebd28fae
+- added prefixes to labels in examples
+ \commit 54a1459d8c73acaf24464411341197a914198a5f
+
+\changesinversion{v1.0.0}
+The first release.
+\end{changelog}
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s6_changelog.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s7_license.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/s7_license.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/s7_license.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,17 @@
+% !TeX root = ../easyfloats.tex
+
+\section{License}
+\label{license}
+
+This package and it's documentation are distributed under the \license{lppl}, version 1.3 or later.
+See \filename{license.txt}.
+The preamble of the documentation may alternatively, at your choice, be reused under the terms of the \license{wtfpl}, 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 \filename{easyfloats.sty} and \filename{doc/easyfloats.pdf} without other files of this work.
+The other files of this work can be found at:
+\url{https://gitlab.com/erzo/latex-easyfloats}
+
+The examples and tests are distributed under the \license{wtfpl}, version 2 or later.
+See \filename{test/license.txt}.
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/s7_license.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/titlepage.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/titlepage.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/titlepage.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,17 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\maketitle
-\thispagestyle{empty}
-\vfill
-\begin{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.
-\end{abstract}
-\vfill
-\vspace{20em}
-\url{https://gitlab.com/erzo/latex-easyfloats}
-\clearpage
-
-\tableofcontents
-\pagebreak
Deleted: trunk/Master/texmf-dist/doc/latex/easyfloats/content/used-packages.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/used-packages.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/used-packages.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,29 +0,0 @@
-% !TeX root = ../easyfloats.tex
-
-\section{Used packages}
-\label{used-packages}
-
-This package uses the following packages (but depending on the package options it may load more or less packages, see \cref{package-options}):
-\pkgdoc{float}
- for `placement=H` and `float style`.
- It also gives you the possibility to define new float types.
-\pkgdoc{caption}
- In the standard document classes there is no distance at all between a table and it's caption above.
- The caption package fixes this.
- It also defines the `\phantomcaption` command which I am using in case that no caption is given.
- (The documentation of `\phantomcaption` is in the \pkg{subcaption} package.)
- It also gives you the possibility to customize the layout of captions but I am not changing the default layout.
- And it is a dependency of the \pkg{subcaption} package.
-\pkgdoc{subcaption}
- for \hyperref[subobject-environment]{subobjects}
-\pkgdoc{graphicx}/\pkgdoc{graphbox}
- for inserting graphics
- (see \cmd{\includegraphicobject})
-\pkgdoc{pgfkeys}
- for parsing key=value lists
-\pkgdoc{etoolbox}
- is a collection of small helpers for programming.
-\pkgdoc{environ}
- to define environments which save their content in a macro.
- I am using this for the `subcaptionbox` backend of the \env{subobject} environment.
-\endpkgdoc
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/x1_motivation.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/x1_motivation.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/x1_motivation.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,377 @@
+% !TeX root = ../easyfloats.tex
+
+\section{Motivation}
+\label{motivation}
+
+In this section I will explain how to insert figures and tables in standard \LaTeX\ without this package and how this package can improve that.
+If you are only interested in how to use this package not why, see \cref{examples} for examples and \cref{documentation} for an explanation of the commands, environments and options defined by this package.
+
+\subsection{Graphics}
+\label{graphics}
+
+Inserting a graphic without using this package requires 6 lines of code (\pkg{graphicx} or \pkg{graphbox} must be loaded for `\includegraphics`):
+\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
+\begin{figure}
+ \centering
+ \includegraphics[graphic width=.8\linewidth]{ctan_lion}
+ \caption{CTAN lion drawing by Duane Bibby}
+ \label{ctan_lion}
+\end{figure}
+\end{examplecode\starred}
+
+\begin{description}
+\item[Lines 1 and 6]
+ open\slash close a floating environment.
+ The content of this environment can float around so that it won't cause a bad page break.
+ You don't need this if you really just want to insert a graphic exactly here (like a logo in a header)
+ but a graphic cannot break across pages so if it is too large for the end of the current page it will move to the next page leaving the end of this page empty.
+ This is a waste of paper and may confuse a reader by suggesting this might be the end of a chapter.
+ A floating environment can help you by putting the figure where it fits best.
+
+ The placement determines where a float is allowed to be placed.
+ Initially that's the top or bottom of a text page or a separate page just for floats.
+ The placement can be specified for a single floating object by passing an optional argument to the floating environment
+ or for all floating objects using the `\floatplacement` command defined by the \pkg{float} package.
+ (The floating environments `figure` and \env{table} are standard \LaTeX\ and do not require the \pkg{float} package.)
+ The allowed values for the placement are described in the description of the \env{object} environment's `placement` key.
+
+ There are people who are concerned that a figure not sitting at the exact position might confuse a reader.
+ However, a graphic naturally attracts the reader's attention.
+ Therefore it does not matter where it is located on the double page.
+ The reader will see it.
+
+ Of course the author must ensure that the figure does not float too far away.
+ If that is the case changing the size of this or another graphic,
+ `\usepackage[section]{placeins}`,
+ `\FloatBarrier` (defined by the \pkg{placeins} package),
+ moving this block of lines in the code,
+ changing the placement or
+ tweaking the parameters which govern the placing of floats \autocite[page~28]{latex2e}
+ can help.
+
+\item[Line 2]
+ centers the graphic horizontally on the line.
+
+ The `\centering` command is used instead of the `center` environment because the latter would insert additional vertical space.
+
+ \begin{examplecode\starred}{\ExamplecodeNoBox}
+ \begin{center}
+ ...
+ \end{center}
+ \end{examplecode\starred}
+ is in \LaTeX2\footnote{This will change in \LaTeX3~\autocite{ltx3env}.}
+ \makeatletter
+ (somewhat simplified\footnote{`\begin` checks that it's argument is defined, `\end` checks that it's argument matches that of `\begin` and deals with `\ignorespacesafterend` and `\@endparenv`. Since 2019/10/01 `\begin` and `\end` are robust. Since 2020/10/01 they include hooks. \autocite[section \sectionname{ltmiscen.dtx}]{source2e}})
+ \makeatother
+ equivalent to
+ \begin{examplecode\starred}{\ExamplecodeNoBox}
+ \begingroup
+ \center
+ ...
+ \endcenter
+ \endgroup
+ \end{examplecode\starred}
+
+ This means that if you accidentally try to use `\centering` as an environment instead of a command you will *not* get an error.
+ You might expect to get an error at least for `\endcentering` not being defined
+ but the \TeX\ primitive `\csname` which is used to produce the `\endcentering` token instead defines it to `\relax`, a no operation.
+
+ The output, however, will not be as desired: the group is closed before the end of the paragraph and `\centering` is forgotten before it can take effect.
+
+\item[Line 3]
+ inserts the graphic.
+ This requires the \pkg{graphicx} or \pkg{graphbox} package.
+
+ If you want all graphics to have the same width you can set the `width` globally with `\setkeys{Gin}{width=<dimen>}`.
+ However, that does not work with all options.
+ Unfortunately the \pkg{graphicx} package documentation~\autocite[section~4.6]{graphicx} is not getting more specific than that this works with \enquote{Most of the keyval keys}.
+
+\item[Line 4]
+ inserts the caption.
+
+ Captions for a figure should be placed *below* the figure.
+ Captions for a table should be placed *above* the table.
+ \autocite{texexchange_caption_position}
+
+ `\caption` can be used inside of a floating environment only.
+ If you need a caption for a non-floating object you can either use `\captionof{<type>}{<caption>}` defined by the \pkg{capt-of} or \pkg{caption} package
+ or use a floating environment with the placement `H` defined by the \pkg{float} package.
+
+\item[Line 5]
+ defines a label.
+ This is not visible in the output but can be referenced using `\ref{<label>}` or `\pageref{<label>}`.
+ You might want to consider using the \pkg{cleveref} package for references.
+
+ The label must be set inside of or after the caption.
+ A label always refers to the last `\refstepcounter` inside of the current group. \autocite[section \sectionname{ltxref.dtx}]{source2e}
+ `\refstepcounter` is used for example by `\caption` and `\section`.
+ Therefore if you use `\label` after the caption it refers to the caption.
+ If you use it before the caption it refers to the current section\slash subsection\slash subsubsection.
+\end{description}
+
+There are many things that a beginner can do wrong without even getting a warning.
+Three out of this six lines are always the same (lines 1, 2 and~6).
+I don't want to always write them out.
+There is no way to easily switch floating on or off globally.
+
+\bigpar
+
+This package reduces these six lines to a single command and loads \pkg{graphicx} automatically (unless this package is loaded with the `nographic` option).
+\begin{examplecode\starred}{}
+\includegraphicobject[%
+ caption = CTAN lion drawing by Duane Bibby,
+ graphic width = .8\linewidth,
+]{ctan_lion}
+\end{examplecode\starred}
+
+The floating environment is applied automatically.
+It can be changed using the `type` key but I discourage doing so manually.
+Instead I recommend to use the separate optional `<style>` argument if necessary.
+If you do not want the object to float you can pass `placement=H`.
+This works also globally with `\objectset`.
+
+`\centering` is applied automatically.
+It can be changed using the `align` key.
+
+You can set any of the options passed to the `\includegraphics` command globally using:
+\begin{examplecode\starred}{}
+\objectset[figure]{graphic width=.8\linewidth}
+\end{examplecode\starred}
+
+Caption and label can be passed as options.
+Which one is specified first makes no difference.
+I recommend to stick with caption first in case you ever need to work without this package and to not confuse other people who are not familiar with this package.
+If you omit one of them the file name is used.
+See `auto label`, `auto caption`, `auto label strip path` and `auto caption strip path`.
+
+Whether the caption is put above or below the object is specified by the `float style`.
+
+\subsection{Tables}
+\label{tables}
+
+Inserting a table is similar to inserting a graphic except that you replace the `\includegraphics` command with an environment which creates a table, place the caption above the table not below it and use another floating environment, namely \env{table} instead of `figure`.
+
+The following example (not using this package) requires the \pkg{booktabs} package for the horizontal rules and the \pkg{caption} package to have an appropriate space below the caption.
+
+\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
+\begin{table}
+ \centering
+ \caption{Some catcodes}
+ \label{catcodes}
+ \begin{tabular}{cl}
+ \toprule
+ Catcode & Meaning \\
+ \midrule
+ 0 & Escape Character \\
+ 1 & Begin Group \\
+ 2 & End Group \\
+ \vdots & \quad \vdots \\
+ \bottomrule
+ \end{tabular}
+\end{table}
+\end{examplecode\starred}
+
+What I have said about floating environments, `\centering`, `\caption` and `\label` in \cref{graphics} is also valid for tables.
+New are lines 5--14.
+We now have two environments nested inside of each other.
+The outer environment (lines 1 and~15) is the floating environment.
+The inner environment (lines 5--14) is the environment which creates the table.
+The inner environment takes a column specification telling \LaTeX\ how many columns the table has and how they are supposed to be aligned.
+In this case that is `cl`: Two columns, the first centered, the second left aligned.
+For more information about column specifications see the \pkg{array} package documentation~\autocite[section~1]{array}.
+
+`\toprule`, `\midrule` and `\bottomrule` (defined by the \pkg{booktabs} package) produce horizontal lines.
+They differ in the width of the line and\slash or spacing around them.
+In contrast to the standard \LaTeX\ `\hline` command they have proper spacing around them.
+
+`&` separates columns, `\\` separates rows.
+Indentation and spaces at the beginning and end of a cell are ignored.
+
+\bigpar
+
+Using this package we don't need two environments and we don't even need to type out the rule commands if we use `table head`.
+The packages \pkg{caption}, \pkg{booktabs} and \pkg{array} are loaded automatically (unless you load this package with `nobooktabs` or `noarray`).
+\begin{examplecode\starred}{}
+\begin{tableobject}{%
+ caption = Some catcodes,
+ label = catcodes,
+ env = tabular,
+ arg = cl,
+ table head = Catcode & Meaning,
+}
+ 0 & Escape Character \\
+ 1 & Begin Group \\
+ 2 & End Group \\
+ \vdots & \quad \vdots \\
+\end{tableobject}
+\end{examplecode\starred}
+
+Also we gain the possibility to easily switch between different tabular-like environments, see \cref{longtable} and the example given for the `(<env>) arg(s) +` key in \cref{object-environment}.
+
+\subsection{Subobjects}
+\label{subobjects}
+
+There are several packages to combine several figures\slash tables into a single floating environment.
+\mycite{l2tabu} recommends using \pkg{subcaption} over \pkg{subfig} and the long deprecated \pkg{subfigure}.
+
+The \pkg{subcaption} package provides several ways to do this.
+The first one is using the `\subcaptionbox` command.
+
+\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
+\begin{table}
+ \centering
+ \caption{Category and character codes}
+ \label{codes}
+ \subcaptionbox{Category codes\label{catcodes}}{%
+ \begin{tabular}{cl}
+ \toprule
+ Catcode & Category \\
+ \midrule
+ 0 & Escape Character \\
+ 1 & Begin Group \\
+ 2 & End Group \\
+ \vdots & \quad \vdots \\
+ \bottomrule
+ \end{tabular}%
+ }%
+ \qquad
+ \subcaptionbox{Character codes\label{charcodes}}{%
+ \begin{tabular}{cr<{\hspace{1.3em}}}
+ \toprule
+ Character & \multicolumn1c{Charcode} \\
+ \midrule
+ \textbackslash & \number`\\ \\
+ \{ & \number`\{ \\
+ \} & \number`\} \\
+ \vdots & \vdots \phantom{0} \\
+ \bottomrule
+ \end{tabular}%
+ }%
+\end{table}
+\end{examplecode\starred}
+
+As the subobjects are inside of an argument they cannot contain code which relies on changing catcodes e.g.\ `\verb`.
+Aside from that it just doesn't seem elegant to put an environment inside of an argument.
+
+If you accidentally put the label in the second argument of `\subcaptionbox` instead of in the first it refers to the parent object instead of the subobject and you won't get an error or a warning for that.
+
+Note how I have commented out line breaks in order to avoid undesired spaces.
+
+The second way is to use the `subfigure`\slash `subtable` environment.
+Because the subobject is not inside of an argument it is possible to use `\verb`.
+
+\begin{examplecode\starred}{\ExamplecodeNoBox\ExamplecodeLinenumbers}
+\begin{table}
+ \caption{Category and character codes}
+ \label{codes}
+ \begin{subtable}{.5\linewidth}
+ \centering
+ \caption{Category codes}
+ \label{catcodes}
+ \begin{tabular}{cl}
+ \toprule
+ Catcode & Category \\
+ \midrule
+ 0 & Escape Character \\
+ 1 & Begin Group \\
+ 2 & End Group \\
+ \vdots & \quad \vdots \\
+ \bottomrule
+ \end{tabular}%
+ \end{subtable}%
+ \begin{subtable}{.5\linewidth}
+ \centering
+ \caption{Character codes}
+ \label{charcodes}
+ \begin{tabular}{cr<{\hspace{1.3em}}}
+ \toprule
+ Character & \multicolumn1c{Charcode} \\
+ \midrule
+ \verb|\| & \number`\\ \\
+ \verb|{| & \number`\{ \\
+ \verb|}| & \number`\} \\
+ \vdots & \vdots \phantom{0} \\
+ \bottomrule
+ \end{tabular}%
+ \end{subtable}%
+\end{table}
+\end{examplecode\starred}
+
+But why having different environments for subfigures and subtables?
+The floating environment specifies the type already.
+
+These environments are based on a minipage and require you to always explicitly specify the width of this minipage.
+On the one hand I don't want to always type that out.
+On the other hand I want to be able to change the width once for all subobjects for easier consistency.
+
+Caption and label must be placed correctly, see \cref{graphics}.
+Even if you restyle the floating environment to always put the caption at the top or bottom using the \pkg{float} package this does *not* apply to subobjects.
+
+It is important to comment out line breaks because the widths of the two minipages add up to the line width, a space between them would cause an overfull hbox or a line break.
+
+We need two `\centering`s, one for each subobject.
+Remember what I said about `\centering` and `center` in \cref{graphics}.
+
+\bigpar
+
+This package defines an environment called `subobject` which is a unified wrapper around `\subcaptionbox` and `subfigure`\slash `subtable`.
+Which of these two backends should be used can be specified with the `subcaptionbox` and `subpage` options.
+`subpage` is used by default so that you can usually use `\verb` in the content.
+
+`subobject` can be used inside of any `*object` environment.
+If you define a new object environment with `\NewObjectStyle` it defines a corresponding subpage environment like `subfigure`\slash `subtable` if it does not exist already and if the \pkg{caption} package is new enough.
+If the \pkg{caption} package is older than August~30, 2020 you need to define the subtype manually by putting the following line *before* loading this package \autocite{texexchange_subtype_workaround}:
+\begin{examplecode\starred}{}
+\AtBeginDocument{\DeclareCaptionSubType{<type>}}
+\end{examplecode\starred}
+
+You don't need to write out the width, `.5\linewidth` is used automatically. You can change this value for all subobjects using
+\begin{examplecode\starred}{}
+\objectset{subobject linewidth=<dimen>}
+\end{examplecode\starred}
+
+Caption and label are given as options like for `tableobject`.
+Their order does not matter.
+They are placed above or below the subobject based on the internal command `\caption at iftop` defined by the \pkg{caption} package.
+
+Spaces after `\begin{subobject}` and before and after `\end{subobject}` are ignored so you don't need to comment out the line breaks.
+\unskip\footnote{Actually, spaces after `\begin{subobject}` and before `\end{subobject}` are ignored only if `env` is empty. But if `env` is not empty I am expecting it to be a tabular-like environment where spaces are ignored at the beginning and end of a cell or a tikzpicture where spaces are ignored as well. Spaces after `\end{subobject}` are ignored regardless of `env`.}
+Just make sure you don't have an empty line between the subobject environments.
+That would *not* be ignored.
+
+`\centering` is inserted automatically. It can be changed with `subpage align`.
+
+\begin{examplecode\starred}{}
+\begin{tableobject}{caption=Category and character codes, label=codes, env=tabular, sub}
+ \begin{subobject}{caption=Category codes, label=catcodes}{cl}
+ \toprule
+ Catcode & Category \\
+ \midrule
+ 0 & Escape Character \\
+ 1 & Begin Group \\
+ 2 & End Group \\
+ \vdots & \quad \vdots \\
+ \bottomrule
+ \end{subobject}
+ \begin{subobject}{caption=Character codes, label=charcodes}{cr<{\hspace{1.3em}}}
+ \toprule
+ Character & \multicolumn1c{Charcode} \\
+ \midrule
+ \verb|\| & \number`\\ \\
+ \verb|{| & \number`\{ \\
+ \verb|}| & \number`\} \\
+ \vdots & \vdots \phantom{0} \\
+ \bottomrule
+ \end{subobject}
+\end{tableobject}
+\end{examplecode\starred}
+
+A separator for the subobjects could be defined globally using `sep`, see also `hor` and `ver`.
+
+For including a graphic from an external file this package defines a wrapper command around `subobject` and `\includegraphics` in order to reduce the typing effort:
+\begin{examplecode\starred}{}
+\begin{figureobject}{caption=Two lions, label=lions, sub}
+ \includegraphicsubobject[caption=A lion]{lion-1}
+ \includegraphicsubobject[caption=Another lion]{lion-2}
+\end{figureobject}
+\end{examplecode\starred}
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/x1_motivation.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/x2_used-packages.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/x2_used-packages.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/x2_used-packages.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,32 @@
+% !TeX root = ../easyfloats.tex
+
+\section{Used packages}
+\label{used-packages}
+
+This section lists the packages which are loaded by this package in order to provide it's functionality.
+This list may be interesting for further customization or a deeper understanding how this package works.
+This list does *not* list all packages which are loaded by default, other packages which may be useful when dealing with floats are listed in \cref{other-packages}.
+
+\pkgdoc{float}
+ for `placement=H` and `float style`.
+ It also gives you the possibility to define new float types.
+\pkgdoc{caption}
+ In the standard document classes there is no distance at all between a table and it's caption above.
+ The caption package fixes this.
+ It also defines the `\phantomcaption` command which I am using in case that no caption is given.
+ (The documentation of `\phantomcaption` is in the \pkg{subcaption} package.)
+ It also gives you the possibility to customize the layout of captions but I am not changing the default layout.
+ And it is a dependency of the \pkg{subcaption} package.
+\pkgdoc{subcaption}
+ for \hyperref[subobject-environment]{subobjects}
+\pkgdoc{graphicx}/\pkgdoc{graphbox}
+ for inserting graphics with \cmd{\includegraphicobject} %or \cmd{\includegraphicsubobject}
+ (see package options \pkgoptn{graphicx}, \pkgoptn{graphbox} and \pkgoptn{nographic})
+\pkgdoc{pgfkeys}
+ for parsing key=value lists
+\pkgdoc{etoolbox},
+ a collection of small helpers for programming
+\pkgdoc{environ}
+ to define environments which save their content in a macro.
+ I am using this for the `subcaptionbox` backend of the \env{subobject} environment.
+\endpkgdoc
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/x2_used-packages.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/content/x3_other-packages.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/content/x3_other-packages.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/content/x3_other-packages.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,63 @@
+% !TeX root = ../easyfloats.tex
+
+\section{Other packages}
+\label{other-packages}
+
+This section lists other packages which may be useful in combination with this package.
+
+\pkgdoc{placeins}
+ When loaded with the `section` package option it prevents floats from floating to another section.
+ It provides the `\FloatBarrier` command which prevents floats from floating past a certain point.
+\pkgdoc{flafter}
+ ensures that floats are not placed before their inclusion in the source code.
+ (With the placement=t it is possible that they are placed on the top of the same page.)
+\pkgdoc{booktabs}
+ for formatting tables.
+ This is loaded by default unless you use the package option \pkgoptn{nobooktabs}.
+ Please read sections 1 and~2 of the \pkg{booktabs} documentation~\autocite{booktabs}.
+\pkgdoc{xcolor}
+ When loaded with the package option \pkgoptn{table} it provides commands for coloring tables.
+
+ `\rowcolor{<color>}` sets a background color for a single row. See \cref{local-definitions-in-tables}.
+
+ `\rowcolors{<firstrow>}{<oddcolor>}{<evencolor>}` can be used with the `exec` key and sets alternating row colors for the entire table.
+
+\pkgdoc{array}
+ extends the column specification syntax and defines the `\newcolumntype` command to define custom column types.
+ It also changes the approach how rules are drawn but that is irrelevant if you apply \pkg{booktabs}' guidelines~\autocite[section~2 \sectionname{The layout of formal tables}]{booktabs}.
+ This is loaded by default unless you use the package option \pkgoptn{noarray}.
+\pkgdoc{siunitx}
+ for typesetting numbers and units.
+ It provides the `S` column to align numbers at their decimal separator.
+\pkgdoc{tabularx}
+ A table where the columns adapt to the width of the table, not the other way around.
+ Unlike `tabular*` the space goes into the columns, not between the columns.
+\pkgdoc{longtable}
+ provides tables where a pagebreak is allowed,
+ see \cref{longtable}.
+ This can be loaded automatically with the package option \pkgoptn{longtable}.
+\pkgdoc{hyperref}
+ automatically creates links in the pdf document for example from references to floating objects.
+ By default links are set in a red box, you can disable the red box with the package option `hidelinks`.
+ With the package option `pdfusetitle` it automatically sets the pdf title and author based on `\title` and `\author`.
+ \pkg{hyperref} should usually be loaded last.
+\pkgdoc{varioref}
+ automatically inserts a page reference (e.g. \enquote{on the following page} or \enquote{on page~42}) after the reference if the reference is on a different page than the label when using `\vref{<label>}`/`\Vref{<label>}`, see the example in \cref{vref}.
+\pkgdoc{cleveref}
+ automatically inserts the type of reference (e.g. \enquote{figure} or \enquote{section}) in front of the reference when using `\cref{<label>}`/`\Cref{<label>}` (defined by \pkg{cleveref}) or `\vref{<label>}`/`\Vref{<label>}` (defined by \pkg{varioref}).
+ With the `nameinlink` package option the type in front of the number becomes part of the link created by hyperref.
+ By default `\cref`/`\vref` (to be used inside of a sentence) use abbreviations but `\Cref`/`\Vref` (to be used at the beginning of a sentence) do not because abbreviating at the beginning of a sentence is considered bad style~\autocite{texexchange_abbrev_bad_style}.
+ Abbreviations can be disabled with the `noabbrev` option.
+ \pkg{cleveref} must be loaded last, even after \pkg{hyperref}.
+ See the example in \cref{vref}.
+\pkgdoc{biblatex}
+ If you input graphics you need to specify the source.
+ Biblatex creates an entire bibliography for you.
+\pkgdoc{tikz}
+ is an amazingly powerful package to create your own graphics in \LaTeX.
+\pkgdoc{newfloat} provides a more modern command to define new floating environments than the \pkg{float} package.
+\pkgdoc{minted} provides syntax highlighting for source code.
+\endpkgdoc
+
+
+For more information about floats see \url{https://latexref.xyz/Floats.html} (it seems this is an html version of the above quoted pdf~\autocite{latex2e}).
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/content/x3_other-packages.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats-file-list.txt
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats-file-list.txt 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats-file-list.txt 2024-10-29 20:07:23 UTC (rev 72699)
@@ -6,7 +6,6 @@
easyfloats.ins
easyfloats.dtx
-easyfloats.sty
README.md
DEPENDS.txt
@@ -13,28 +12,35 @@
doc/easyfloats.tex
doc/easyfloats.pdf
doc/easyfloats.bib
+doc/my_biblatex_data_model.dbx
doc/links.tex
doc/undescribed-keywords.tex
-doc/content/bug-reports-and-contributions.tex
-doc/content/documentation.tex
-doc/content/examples.tex
-doc/content/installation.tex
-doc/content/license.tex
-doc/content/motivation.tex
-doc/content/other-packages.tex
-doc/content/names.tex
-doc/content/titlepage.tex
-doc/content/used-packages.tex
+doc/content/f1_titlepage.tex
+doc/content/s1_examples.tex
+doc/content/s2_names.tex
+doc/content/s3_documentation.tex
+doc/content/s4_installation.tex
+doc/content/s5_bug-reports-and-contributions.tex
+doc/content/s6_changelog.tex
+doc/content/s7_license.tex
+doc/content/x1_motivation.tex
+doc/content/x2_used-packages.tex
+doc/content/x3_other-packages.tex
doc/preamble/bibliography.tex
+doc/preamble/changelog.tex
doc/preamble/description-links.tex
doc/preamble/examplecode.tex
+doc/preamble/geometry.tex
doc/preamble/keydoc.tex
doc/preamble/link.tex
doc/preamble/macros.tex
doc/preamble/markdown.tex
doc/preamble/pdfstring.tex
+doc/preamble/todo.tex
doc/lexer/latex_atletter.py
+You can generate the sty file by running `tex easyfloats.ins`.
+
There are automated tests to test this work at
https://gitlab.com/erzo/latex-easyfloats/-/tree/master/test
These tests are licensed under the WTFPL http://www.wtfpl.net/about/.
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.bib
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.bib 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.bib 2024-10-29 20:07:23 UTC (rev 72699)
@@ -11,6 +11,7 @@
author = {Victor Eijkhout},
year = {2007},
url = {https://ctan.org/pkg/texbytopic},
+ texdoc = {texbytopic},
}
@manual{latex2e,
@@ -18,6 +19,7 @@
url = {https://ctan.org/pkg/latex2e-help-texinfo},
date = {2018-10},
language = {english},
+ texdoc = {latex2e},
}
@manual{clsguide,
@@ -25,6 +27,7 @@
author = {The \LaTeX3 Project},
url = {https://ctan.org/pkg/clsguide},
date = {2006-02-15},
+ texdoc = {clsguide},
}
@manual{source2e,
@@ -39,6 +42,7 @@
url = {https://ctan.org/pkg/source2e},
date = {2020-10-01},
language = {english},
+ texdoc = {source2e},
}
@manual{l2tabu,
@@ -48,8 +52,17 @@
date = {2016-02-03},
language = {german},
addendum = {An English translation of an older version is available at \url{https://ctan.org/pkg/l2tabu-english}},
+ texdoc = {l2tabu},
}
+ at manual{usrguide,
+ title = {\LaTeX\ for authors},
+ author = {\LaTeX\ Project Team},
+ date = {2023-05-23},
+ url = {https://ctan.org/pkg/usrguide},
+ texdoc = {usrguide},
+}
+
% ------- Joseph Wright's blog -------
@online{ltx3env,
@@ -98,6 +111,7 @@
author = {Frank Mittelbach and David Carlisle},
date = {2020-10-01},
url = {https://ctan.org/pkg/array},
+ texdoc = {array},
}
@manual{booktabs,
@@ -105,6 +119,7 @@
author = {Simon Fear},
date = {2016-04-29},
url = {https://ctan.org/pkg/booktabs},
+ texdoc = {booktabs},
}
@manual{tikz,
@@ -112,6 +127,7 @@
author = {Till Tantau},
date = {2019-05-09},
url = {https://ctan.org/pkg/pgf},
+ texdoc = {tikz},
}
@manual{graphicx,
@@ -119,6 +135,7 @@
author = {D. P. Carlisle},
date = {2017-06-01},
url = {https://ctan.org/pkg/graphicx},
+ texdoc = {graphicx},
}
@manual{float,
@@ -126,6 +143,7 @@
author = {Anselm Lingnau},
date = {2001-11-08},
url = {https://ctan.org/pkg/float},
+ texdoc = {float},
}
@manual{caption,
title = {Customizing captions of floating environments},
@@ -132,6 +150,7 @@
author = {Axel Sommerfeldt},
date = {2020-09-12},
url = {https://ctan.org/pkg/caption},
+ texdoc = {caption},
}
@manual{subcaption,
title = {The subcaption package},
@@ -138,4 +157,5 @@
author = {Axel Sommerfeldt},
date = {2020-08-24},
url = {https://ctan.org/pkg/subcaption},
+ texdoc = {subcaption},
}
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/easyfloats.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -6,12 +6,12 @@
\newif\ifunderlinelinks
\underlinelinkstrue
-\documentclass[a4paper]{ltxdoc}
+\documentclass[a4paper]{article}
-\usepackage{dtxdescribe}
-\usepackage{parskip}
+\input{preamble/geometry}
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
\usepackage{csquotes}
-
\input{preamble/bibliography}
\input{preamble/macros}
\input{preamble/examplecode}
@@ -20,10 +20,16 @@
\input{preamble/keydoc}
\input{preamble/description-links}
\input{preamble/pdfstring}
+\input{preamble/todo}
+\input{preamble/changelog}
\usepackage[hidelinks, pdfusetitle]{hyperref}
\usepackage[nameinlink, noabbrev]{cleveref}
+\usepackage{microtype}
+\usepackage{silence}
+\WarningFilter{latex}{Marginpar on page 38 moved} % caused by \DescribeMacro{\Crefname}
+
\newlicense{lppl}{\LaTeX\ Project Public License}{https://www.latex-project.org/lppl/}
\newlicense{wtfpl}{WTFPL}{http://www.wtfpl.net/}
@@ -31,9 +37,9 @@
\title{An easier interface to insert figures, tables and other objects in \LaTeX}
\author{Erik Zöllner}
-\date{December~20, 2020}
+\date{October~28, 2024}
\package{\jobname}
-\version{v1.0.0}
+\version{v1.1.0}
\newcommand{\myinput}[1]{\input{#1}\unskip}
@@ -40,21 +46,25 @@
\input{links}
\begin{document}
\myinput{undescribed-keywords}
- \myinput{content/titlepage}
- \myinput{content/examples}
- \myinput{content/names}
- \myinput{content/documentation}
- \myinput{content/installation}
- \myinput{content/bug-reports-and-contributions}
- \myinput{content/license}
+ \myinput{content/f1_titlepage}
+ \myinput{content/s1_examples}
+ \myinput{content/s2_names}
+ \myinput{content/s3_documentation}
+
+ \myinput{content/s4_installation}\notocspace
+ \myinput{content/s5_bug-reports-and-contributions}\notocspace
+ \myinput{content/s6_changelog}\notocspace
+ \myinput{content/s7_license}
+
\appendix
\addtocontents{toc}{\protect\setcounter{tocdepth}{1}}
- \myinput{content/motivation}
- \myinput{content/used-packages}
- \myinput{content/other-packages}
+ \myinput{content/x1_motivation}\notocspace
+ \myinput{content/x2_used-packages}\notocspace
+ \myinput{content/x3_other-packages}\notocspace
\section{\refname}
+ \label{references}
Works cited in this documentation (ordered by appearance in this document,
if there are several versions on CTAN I am referring to the English pdf):
\printbibliography[heading=none]
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/license.txt
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/license.txt (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/license.txt 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,416 @@
+The LaTeX Project Public License
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+
+LPPL Version 1.3c 2008-05-04
+
+Copyright 1999 2002-2008 LaTeX3 Project
+ Everyone is allowed to distribute verbatim copies of this
+ license document, but modification of it is not allowed.
+
+
+PREAMBLE
+========
+
+The LaTeX Project Public License (LPPL) is the primary license under
+which the LaTeX kernel and the base LaTeX packages are distributed.
+
+You may use this license for any work of which you hold the copyright
+and which you wish to distribute. This license may be particularly
+suitable if your work is TeX-related (such as a LaTeX package), but
+it is written in such a way that you can use it even if your work is
+unrelated to TeX.
+
+The section `WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE',
+below, gives instructions, examples, and recommendations for authors
+who are considering distributing their works under this license.
+
+This license gives conditions under which a work may be distributed
+and modified, as well as conditions under which modified versions of
+that work may be distributed.
+
+We, the LaTeX3 Project, believe that the conditions below give you
+the freedom to make and distribute modified versions of your work
+that conform with whatever technical specifications you wish while
+maintaining the availability, integrity, and reliability of
+that work. If you do not see how to achieve your goal while
+meeting these conditions, then read the document `cfgguide.tex'
+and `modguide.tex' in the base LaTeX distribution for suggestions.
+
+
+DEFINITIONS
+===========
+
+In this license document the following terms are used:
+
+ `Work'
+ Any work being distributed under this License.
+
+ `Derived Work'
+ Any work that under any applicable law is derived from the Work.
+
+ `Modification'
+ Any procedure that produces a Derived Work under any applicable
+ law -- for example, the production of a file containing an
+ original file associated with the Work or a significant portion of
+ such a file, either verbatim or with modifications and/or
+ translated into another language.
+
+ `Modify'
+ To apply any procedure that produces a Derived Work under any
+ applicable law.
+
+ `Distribution'
+ Making copies of the Work available from one person to another, in
+ whole or in part. Distribution includes (but is not limited to)
+ making any electronic components of the Work accessible by
+ file transfer protocols such as FTP or HTTP or by shared file
+ systems such as Sun's Network File System (NFS).
+
+ `Compiled Work'
+ A version of the Work that has been processed into a form where it
+ is directly usable on a computer system. This processing may
+ include using installation facilities provided by the Work,
+ transformations of the Work, copying of components of the Work, or
+ other activities. Note that modification of any installation
+ facilities provided by the Work constitutes modification of the Work.
+
+ `Current Maintainer'
+ A person or persons nominated as such within the Work. If there is
+ no such explicit nomination then it is the `Copyright Holder' under
+ any applicable law.
+
+ `Base Interpreter'
+ A program or process that is normally needed for running or
+ interpreting a part or the whole of the Work.
+
+ A Base Interpreter may depend on external components but these
+ are not considered part of the Base Interpreter provided that each
+ external component clearly identifies itself whenever it is used
+ interactively. Unless explicitly specified when applying the
+ license to the Work, the only applicable Base Interpreter is a
+ `LaTeX-Format' or in the case of files belonging to the
+ `LaTeX-format' a program implementing the `TeX language'.
+
+
+
+CONDITIONS ON DISTRIBUTION AND MODIFICATION
+===========================================
+
+1. Activities other than distribution and/or modification of the Work
+are not covered by this license; they are outside its scope. In
+particular, the act of running the Work is not restricted and no
+requirements are made concerning any offers of support for the Work.
+
+2. You may distribute a complete, unmodified copy of the Work as you
+received it. Distribution of only part of the Work is considered
+modification of the Work, and no right to distribute such a Derived
+Work may be assumed under the terms of this clause.
+
+3. You may distribute a Compiled Work that has been generated from a
+complete, unmodified copy of the Work as distributed under Clause 2
+above, as long as that Compiled Work is distributed in such a way that
+the recipients may install the Compiled Work on their system exactly
+as it would have been installed if they generated a Compiled Work
+directly from the Work.
+
+4. If you are the Current Maintainer of the Work, you may, without
+restriction, modify the Work, thus creating a Derived Work. You may
+also distribute the Derived Work without restriction, including
+Compiled Works generated from the Derived Work. Derived Works
+distributed in this manner by the Current Maintainer are considered to
+be updated versions of the Work.
+
+5. If you are not the Current Maintainer of the Work, you may modify
+your copy of the Work, thus creating a Derived Work based on the Work,
+and compile this Derived Work, thus creating a Compiled Work based on
+the Derived Work.
+
+6. If you are not the Current Maintainer of the Work, you may
+distribute a Derived Work provided the following conditions are met
+for every component of the Work unless that component clearly states
+in the copyright notice that it is exempt from that condition. Only
+the Current Maintainer is allowed to add such statements of exemption
+to a component of the Work.
+
+ a. If a component of this Derived Work can be a direct replacement
+ for a component of the Work when that component is used with the
+ Base Interpreter, then, wherever this component of the Work
+ identifies itself to the user when used interactively with that
+ Base Interpreter, the replacement component of this Derived Work
+ clearly and unambiguously identifies itself as a modified version
+ of this component to the user when used interactively with that
+ Base Interpreter.
+
+ b. Every component of the Derived Work contains prominent notices
+ detailing the nature of the changes to that component, or a
+ prominent reference to another file that is distributed as part
+ of the Derived Work and that contains a complete and accurate log
+ of the changes.
+
+ c. No information in the Derived Work implies that any persons,
+ including (but not limited to) the authors of the original version
+ of the Work, provide any support, including (but not limited to)
+ the reporting and handling of errors, to recipients of the
+ Derived Work unless those persons have stated explicitly that
+ they do provide such support for the Derived Work.
+
+ d. You distribute at least one of the following with the Derived Work:
+
+ 1. A complete, unmodified copy of the Work;
+ if your distribution of a modified component is made by
+ offering access to copy the modified component from a
+ designated place, then offering equivalent access to copy
+ the Work from the same or some similar place meets this
+ condition, even though third parties are not compelled to
+ copy the Work along with the modified component;
+
+ 2. Information that is sufficient to obtain a complete,
+ unmodified copy of the Work.
+
+7. If you are not the Current Maintainer of the Work, you may
+distribute a Compiled Work generated from a Derived Work, as long as
+the Derived Work is distributed to all recipients of the Compiled
+Work, and as long as the conditions of Clause 6, above, are met with
+regard to the Derived Work.
+
+8. The conditions above are not intended to prohibit, and hence do not
+apply to, the modification, by any method, of any component so that it
+becomes identical to an updated version of that component of the Work as
+it is distributed by the Current Maintainer under Clause 4, above.
+
+9. Distribution of the Work or any Derived Work in an alternative
+format, where the Work or that Derived Work (in whole or in part) is
+then produced by applying some process to that format, does not relax or
+nullify any sections of this license as they pertain to the results of
+applying that process.
+
+10. a. A Derived Work may be distributed under a different license
+ provided that license itself honors the conditions listed in
+ Clause 6 above, in regard to the Work, though it does not have
+ to honor the rest of the conditions in this license.
+
+ b. If a Derived Work is distributed under a different license, that
+ Derived Work must provide sufficient documentation as part of
+ itself to allow each recipient of that Derived Work to honor the
+ restrictions in Clause 6 above, concerning changes from the Work.
+
+11. This license places no restrictions on works that are unrelated to
+the Work, nor does this license place any restrictions on aggregating
+such works with the Work by any means.
+
+12. Nothing in this license is intended to, or may be used to, prevent
+complete compliance by all parties with all applicable laws.
+
+
+NO WARRANTY
+===========
+
+There is no warranty for the Work. Except when otherwise stated in
+writing, the Copyright Holder provides the Work `as is', without
+warranty of any kind, either expressed or implied, including, but not
+limited to, the implied warranties of merchantability and fitness for a
+particular purpose. The entire risk as to the quality and performance
+of the Work is with you. Should the Work prove defective, you assume
+the cost of all necessary servicing, repair, or correction.
+
+In no event unless required by applicable law or agreed to in writing
+will The Copyright Holder, or any author named in the components of the
+Work, or any other party who may distribute and/or modify the Work as
+permitted above, be liable to you for damages, including any general,
+special, incidental or consequential damages arising out of any use of
+the Work or out of inability to use the Work (including, but not limited
+to, loss of data, data being rendered inaccurate, or losses sustained by
+anyone as a result of any failure of the Work to operate with any other
+programs), even if the Copyright Holder or said author or said other
+party has been advised of the possibility of such damages.
+
+
+MAINTENANCE OF THE WORK
+=======================
+
+The Work has the status `author-maintained' if the Copyright Holder
+explicitly and prominently states near the primary copyright notice in
+the Work that the Work can only be maintained by the Copyright Holder
+or simply that it is `author-maintained'.
+
+The Work has the status `maintained' if there is a Current Maintainer
+who has indicated in the Work that they are willing to receive error
+reports for the Work (for example, by supplying a valid e-mail
+address). It is not required for the Current Maintainer to acknowledge
+or act upon these error reports.
+
+The Work changes from status `maintained' to `unmaintained' if there
+is no Current Maintainer, or the person stated to be Current
+Maintainer of the work cannot be reached through the indicated means
+of communication for a period of six months, and there are no other
+significant signs of active maintenance.
+
+You can become the Current Maintainer of the Work by agreement with
+any existing Current Maintainer to take over this role.
+
+If the Work is unmaintained, you can become the Current Maintainer of
+the Work through the following steps:
+
+ 1. Make a reasonable attempt to trace the Current Maintainer (and
+ the Copyright Holder, if the two differ) through the means of
+ an Internet or similar search.
+
+ 2. If this search is successful, then enquire whether the Work
+ is still maintained.
+
+ a. If it is being maintained, then ask the Current Maintainer
+ to update their communication data within one month.
+
+ b. If the search is unsuccessful or no action to resume active
+ maintenance is taken by the Current Maintainer, then announce
+ within the pertinent community your intention to take over
+ maintenance. (If the Work is a LaTeX work, this could be
+ done, for example, by posting to comp.text.tex.)
+
+ 3a. If the Current Maintainer is reachable and agrees to pass
+ maintenance of the Work to you, then this takes effect
+ immediately upon announcement.
+
+ b. If the Current Maintainer is not reachable and the Copyright
+ Holder agrees that maintenance of the Work be passed to you,
+ then this takes effect immediately upon announcement.
+
+ 4. If you make an `intention announcement' as described in 2b. above
+ and after three months your intention is challenged neither by
+ the Current Maintainer nor by the Copyright Holder nor by other
+ people, then you may arrange for the Work to be changed so as
+ to name you as the (new) Current Maintainer.
+
+ 5. If the previously unreachable Current Maintainer becomes
+ reachable once more within three months of a change completed
+ under the terms of 3b) or 4), then that Current Maintainer must
+ become or remain the Current Maintainer upon request provided
+ they then update their communication data within one month.
+
+A change in the Current Maintainer does not, of itself, alter the fact
+that the Work is distributed under the LPPL license.
+
+If you become the Current Maintainer of the Work, you should
+immediately provide, within the Work, a prominent and unambiguous
+statement of your status as Current Maintainer. You should also
+announce your new status to the same pertinent community as
+in 2b) above.
+
+
+WHETHER AND HOW TO DISTRIBUTE WORKS UNDER THIS LICENSE
+======================================================
+
+This section contains important instructions, examples, and
+recommendations for authors who are considering distributing their
+works under this license. These authors are addressed as `you' in
+this section.
+
+Choosing This License or Another License
+----------------------------------------
+
+If for any part of your work you want or need to use *distribution*
+conditions that differ significantly from those in this license, then
+do not refer to this license anywhere in your work but, instead,
+distribute your work under a different license. You may use the text
+of this license as a model for your own license, but your license
+should not refer to the LPPL or otherwise give the impression that
+your work is distributed under the LPPL.
+
+The document `modguide.tex' in the base LaTeX distribution explains
+the motivation behind the conditions of this license. It explains,
+for example, why distributing LaTeX under the GNU General Public
+License (GPL) was considered inappropriate. Even if your work is
+unrelated to LaTeX, the discussion in `modguide.tex' may still be
+relevant, and authors intending to distribute their works under any
+license are encouraged to read it.
+
+A Recommendation on Modification Without Distribution
+-----------------------------------------------------
+
+It is wise never to modify a component of the Work, even for your own
+personal use, without also meeting the above conditions for
+distributing the modified component. While you might intend that such
+modifications will never be distributed, often this will happen by
+accident -- you may forget that you have modified that component; or
+it may not occur to you when allowing others to access the modified
+version that you are thus distributing it and violating the conditions
+of this license in ways that could have legal implications and, worse,
+cause problems for the community. It is therefore usually in your
+best interest to keep your copy of the Work identical with the public
+one. Many works provide ways to control the behavior of that work
+without altering any of its licensed components.
+
+How to Use This License
+-----------------------
+
+To use this license, place in each of the components of your work both
+an explicit copyright notice including your name and the year the work
+was authored and/or last substantially modified. Include also a
+statement that the distribution and/or modification of that
+component is constrained by the conditions in this license.
+
+Here is an example of such a notice and statement:
+
+ %% pig.dtx
+ %% Copyright 2005 M. Y. Name
+ %
+ % This work may be distributed and/or modified under the
+ % conditions of the LaTeX Project Public License, either version 1.3
+ % of this license or (at your option) any later version.
+ % The latest version of this license is in
+ % http://www.latex-project.org/lppl.txt
+ % and version 1.3 or later is part of all distributions of LaTeX
+ % version 2005/12/01 or later.
+ %
+ % This work has the LPPL maintenance status `maintained'.
+ %
+ % The Current Maintainer of this work is M. Y. Name.
+ %
+ % This work consists of the files pig.dtx and pig.ins
+ % and the derived file pig.sty.
+
+Given such a notice and statement in a file, the conditions
+given in this license document would apply, with the `Work' referring
+to the three files `pig.dtx', `pig.ins', and `pig.sty' (the last being
+generated from `pig.dtx' using `pig.ins'), the `Base Interpreter'
+referring to any `LaTeX-Format', and both `Copyright Holder' and
+`Current Maintainer' referring to the person `M. Y. Name'.
+
+If you do not want the Maintenance section of LPPL to apply to your
+Work, change `maintained' above into `author-maintained'.
+However, we recommend that you use `maintained', as the Maintenance
+section was added in order to ensure that your Work remains useful to
+the community even when you can no longer maintain and support it
+yourself.
+
+Derived Works That Are Not Replacements
+---------------------------------------
+
+Several clauses of the LPPL specify means to provide reliability and
+stability for the user community. They therefore concern themselves
+with the case that a Derived Work is intended to be used as a
+(compatible or incompatible) replacement of the original Work. If
+this is not the case (e.g., if a few lines of code are reused for a
+completely different task), then clauses 6b and 6d shall not apply.
+
+
+Important Recommendations
+-------------------------
+
+ Defining What Constitutes the Work
+
+ The LPPL requires that distributions of the Work contain all the
+ files of the Work. It is therefore important that you provide a
+ way for the licensee to determine which files constitute the Work.
+ This could, for example, be achieved by explicitly listing all the
+ files of the Work near the copyright notice of each file or by
+ using a line such as:
+
+ % This work consists of all files listed in manifest.txt.
+
+ in that place. In the absence of an unequivocal list it might be
+ impossible for the licensee to determine what is considered by you
+ to comprise the Work and, in such a case, the licensee would be
+ entitled to make reasonable conjectures as to which files comprise
+ the Work.
+
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/license.txt
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/links.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/links.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/links.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -1,3 +1,5 @@
+% !TeX root = easyfloats.tex
+
\newurllink{etoolbox}{https://ctan.org/pkg/etoolbox}
\newurllink{environ}{https://ctan.org/pkg/environ}
\newurllink{placeins}{https://ctan.org/pkg/placeins}
@@ -5,6 +7,7 @@
\newurllink{siunitx}{https://ctan.org/pkg/siunitx}
\newurllink{tabularx}{https://ctan.org/pkg/tabularx}
\newurllink{cleveref}{https://ctan.org/pkg/cleveref}
+\newurllink{varioref}{https://ctan.org/pkg/varioref}
\newurllink{biblatex}{https://ctan.org/pkg/biblatex}
\newlabellink{storing key}{key-types}
\newlabellink{executed key}{key-types}
@@ -16,6 +19,7 @@
\newurllink{graphics}{https://ctan.org/pkg/graphicx}
\newurllink{graphbox}{https://ctan.org/pkg/graphbox}
\newurllink{tikz}{https://www.ctan.org/pkg/pgf}
+\newurllink{minted}{https://ctan.org/pkg/minted}
\newurllink{array}{https://ctan.org/pkg/array}
\newurllink{booktabs}{https://ctan.org/pkg/booktabs}
\newurllink{xcolor}{https://ctan.org/pkg/xcolor}
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/bibliography.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/bibliography.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/bibliography.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -8,6 +8,7 @@
\usepackage[%
sorting=none, % none=citation order
+ datamodel=my_biblatex_data_model,
]{biblatex}
\setcounter{biburllcpenalty}{8000}
@@ -33,3 +34,21 @@
\printtext[bibhyperref]{\printfield[citetitle]{labeltitle}}}
{\multicitedelim}
{\usebibmacro{postnote}}
+
+
+\DeclareFieldFormat{texdoc}{\texttt{texdoc #1}}
+
+\renewbibmacro*{doi+eprint+url}{%
+ \printfield{texdoc}%
+ \newunit\newblock
+ \iftoggle{bbx:doi}
+ {\printfield{doi}}
+ {}%
+ \newunit\newblock
+ \iftoggle{bbx:eprint}
+ {\usebibmacro{eprint}}
+ {}%
+ \newunit\newblock
+ \iftoggle{bbx:url}
+ {\usebibmacro{url+urldate}}
+ {}}
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/changelog.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/changelog.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/changelog.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,67 @@
+% !TeX root = ../easyfloats.tex
+
+\usepackage{fontawesome}
+\usepackage{amsmath}
+
+
+% ------- version -------
+
+\newcommand\changesinversion[1]{\CheckVersion#1\relax\subsection[#1]{\FormatTag{#1}}}
+
+\newcommand\GitlabUrl{https://gitlab.com/erzo/latex-easyfloats/-}
+\newcommand\FormatTag[1]{#1\href{\GitlabUrl/tags/#1}{\,$^\text{\normalfont\faGitlab}$}}
+\def\CheckVersion#1#2\relax{%
+ \ifx #1v%
+ % ok
+ \else
+ \PackageWarning{change log}{Version number #1#2 is missing the v in front}{}%
+ \fi
+}
+
+
+% ------- changelog environment -------
+
+\ExplSyntaxOn
+\bool_new:N \l_changelog_in_list_bool
+
+\cs_new:Nn \changelog_item: {
+ \bool_if:NF \l_changelog_in_list_bool {
+ \bool_set_true:N \l_changelog_in_list_bool
+ \begin{itemize}
+ }
+ \item
+}
+
+\cs_new:Nn \changelog_end: {
+ \bool_if:NT \l_changelog_in_list_bool {
+ \end{itemize}
+ \bool_set_false:N \l_changelog_in_list_bool
+ }
+}
+
+\cctab_begin:N \c_code_cctab
+\char_set_catcode_active:N \^^M%
+\newenvironment{changelog}{%
+ \catcode`\^^M=\active%
+ \def^^M##1{%
+ \ifx ##1-%
+ \exp_after:wN \use_i:nn%
+ \else
+ \exp_after:wN \use_ii:nn%
+ \fi%
+ {\changelog_item:}%
+ {\ifx ##1^^M%
+ \exp_after:wN \use_i:nn%
+ \else
+ \exp_after:wN \use_ii:nn%
+ \fi%
+ {\changelog_end:}%
+ {~##1}%
+ }
+ }%
+ \cs_new:Npn\commit##1^^M{\unskip\href{\GitlabUrl/commit/##1}{\,$^\text{\faGitlab}$}^^M}%
+}{%
+ \changelog_end:
+}%
+\cctab_end:%
+\ExplSyntaxOff
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/changelog.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/description-links.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/description-links.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/description-links.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -8,6 +8,7 @@
% Links all \cmd, \env and \handler to the corresponding \Describe*.
% Links all \pkg to a reference defined with \newurllink (see link.tex)
+% Links all \tikzlibrary to the TikZ manual.
% Defines \pkgoptndoc to document package otions and links all \pkgoptn to it.
%
% \pkgoptndoc{<packageoption>}
@@ -41,14 +42,17 @@
\newcommand{\Cmd}[1]{\expandafter{\detokenize{#1}\unskip}}
\newcommand{\CmdBg}{\formatcode}
\let\DlOriginalDescribeMacro=\DescribeMacro
+\newcommand\MacroLinkTarget[1]{%
+ \NewKeyword[\unexpanded]{cs}{\DlCmdLabelName{#1}}{\CmdBg}{\Cmd}{}%
+ \AbbrevKeyword[\unexpanded]{}{\DlCmdLabelName{#1}} {cs}{\DlCmdLabelName{#1}}%
+ \ignorespaces
+}
\renewcommand{\DescribeMacro}[1]{%
\begingroup
\def\cmd##1{\formatcodeinmarginpar{\Cmd{##1}}}%
\DlOriginalDescribeMacro{#1}%
\endgroup
- \NewKeyword[\unexpanded]{cs}{\DlCmdLabelName{#1}}{\CmdBg}{\Cmd}{}%
- \AbbrevKeyword[\unexpanded]{}{\DlCmdLabelName{#1}} {cs}{\DlCmdLabelName{#1}}%
- \ignorespaces
+ \MacroLinkTarget{#1}%
}
\newcommand{\NoDescribeMacro}[1]{%
\NoKeyword[\unexpanded]{cs}{\DlCmdLabelName{#1}}{\CmdBg}{\Cmd}%
@@ -99,7 +103,7 @@
}
-% --------- \NoDescribeKey, \NoDescribeVal ----------
+% --------- \NoDescribeKey, \NoDescribeVal, \valdoc ----------
\newcommand{\NoDescribeKey}[1]{%
\NoKeyword{key}{#1}{\keydoc at key@bg}{\keydoc at original@key}%
@@ -110,6 +114,9 @@
\NoKeyword{}{#1}{\formatcode}{\val}%
\ignorespaces
}
+\newcommand{\valdoc}[1]{%
+ \NewKeyword{}{#1}{\formatcode}{\val}{#1}%
+}
% --------- \DescribeMeta ----------
@@ -199,11 +206,14 @@
\else\ifx \pkgdoc at nexttoken \pkgdoc
\let\pkgdoc at lookahead@do=\relax
\let\pkgdoc at lookahead@gobble=\@empty
+ \else\ifx \pkgdoc at nexttoken ,%
+ \let\pkgdoc at lookahead@do=\relax
+ \let\pkgdoc at lookahead@gobble=\@empty
\else
\pkgdoc at descriptionsep
\let\pkgdoc at lookahead@do=\relax
\let\pkgdoc at lookahead@gobble=\@empty
- \fi \fi \fi
+ \fi \fi \fi \fi
\expandafter \pkgdoc at lookahead@do \pkgdoc at lookahead@gobble
}
@@ -221,4 +231,11 @@
\ignorespaces
}
+
+% --------- \tikzlibrary ----------
+
+\let\DlOriginalTikzLibrary=\tikzlibrary
+\newcommand{\DlTikzLibraryBg}[1]{#1}
+\renewcommand{\tikzlibrary}[1]{\LinkKeyword{pkg}{tikz}\DlTikzLibraryBg\DlOriginalTikzLibrary{#1}}
+
\makeatother
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/examplecode.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/examplecode.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/examplecode.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -28,6 +28,14 @@
% \ExamplecodeLinenumbers
% enables line numbers
%
+% \ExamplecodeVerbDelimiter|
+% code between | is treated as verbatim
+% \ExamplecodeVerbDelimiterOff
+% no code is treated as verbatim
+%
+% \ExampleCodeEscapeInside{...}
+% can be used to set \ExamplecodeVerbDelimiter in the example code
+%
% \\ is redefined to cause a linebreak marked with \ExamplecodePostBreakText.
@@ -51,6 +59,7 @@
\colorlet{brace}{aligntab}
\colorlet{controlsequence}{aligntab}
\definecolor{comment}{RGB}{"40,"80,"80}
+\colorlet{verb}{black}
\definecolor{codebackground}{rgb}{0.9,0.9,1}
\colorlet{codeborder}{codebackground!50!black}
\colorlet{codelinkcolor}{white}
@@ -103,7 +112,19 @@
\newcommand{\ExamplecodeAllowLinebreakBeforeNext}{\@examplecode at allowlinebreakbeforenexttrue}
\newcommand{\ExamplecodeLinebreak}{\newline\ExamplecodePostBreakText}
-\newcommand{\ExamplecodeFormatCmd}[1]{{\leavevmode\color{controlsequence}\LinkUnformattedKeyword{cs}{\detokenize{#1}}{\string#1}}\ExamplecodeAllowLinebreakBeforeNext} % catcode 0/16
+\ExplSyntaxOn
+\newcommand{\ExamplecodeFormatCmd}[1]{
+ {
+ \leavevmode
+ \color{controlsequence}
+ % do not try to link macros in expl syntax
+ \tl_if_in:nnTF {#1}{\textunderscore}
+ {\string#1}
+ {\LinkUnformattedKeyword{cs}{\detokenize{#1}}{\string#1}}
+ }
+ \ExamplecodeAllowLinebreakBeforeNext
+} % catcode 0/16
+\ExplSyntaxOff
\newcommand{\ExamplecodeFormatEnv}[1]{\LinkUnformattedKeyword{env}{#1}{#1}}
\newcommand{\ExamplecodeFormatPkg}[1]{\LinkUnformattedKeyword{pkg}{#1}{#1}}
@@ -167,15 +188,39 @@
\ExamplecodeAllowLinebreakAfter]
+\newcommand\ExampleCodeEscapeInside{\PackageError{examplecode}{\string\ExampleCodeEscapeInside\ should not be called outside of examplecode}{}}
+\newcommand{\ExamplecodeVerbDelimiter}[1]{%
+ \let\@examplecode at verb@delimiter=#1%
+}
+\newcommand{\ExamplecodeVerbDelimiterOff}{%
+ \let\@examplecode at verb@delimiter=\relax
+}
+\ExamplecodeVerbDelimiterOff
+
+\newcommand{\ExamplecodeFormatVerbDelimiter}[1]{\textcolor{brace}{#1}}
+\newcommand{\ExamplecodeFormatVerb}{\color{verb}}
+
+
% ---------- process ---------
\newif\ifExamplecodeInAlign
+\newcounter{@examplecode at grouplevel}
+\gdef\@examplecode at grouplevel@mathenter{-1}
\newcommand{\ExamplecodeProcessCmd}[1]{\ExamplecodePrint{\ExamplecodeFormatCmd{#1}}} % catcode 0/16
\newcommand{\ExamplecodeProcessEnv}[1]{\ExamplecodePrint{\ExamplecodeFormatEnv{#1}}}
\newcommand{\ExamplecodeProcessPkg}[1]{\ExamplecodePrint{\ExamplecodeFormatPkg{#1}}}
-\newcommand{\ExamplecodeProcessBeginGroup}[1]{\ExamplecodePrint{\ExamplecodeFormatBeginGroup{#1}}} % catcode 1
-\newcommand{\ExamplecodeProcessEndGroup}[1]{\ExamplecodePrint{\ExamplecodeFormatEndGroup{#1}}} % catcode 2
+\newcommand{\ExamplecodeProcessBeginGroup}[1]{%
+ \stepcounter{@examplecode at grouplevel}%
+ \ExamplecodePrint{\ExamplecodeFormatBeginGroup{#1}}%
+} % catcode 1
+\newcommand{\ExamplecodeProcessEndGroup}[1]{%
+ \ifnum \value{@examplecode at grouplevel} = \@examplecode at grouplevel@mathenter \relax
+ \@examplecode at math@end
+ \fi
+ \addtocounter{@examplecode at grouplevel}{-1}%
+ \ExamplecodePrint{\ExamplecodeFormatEndGroup{#1}}%
+} % catcode 2
\newcommand{\ExamplecodeProcessMathShift}[1]{\ExamplecodePrint{\ExamplecodeFormatMathShift{#1}}} % catcode 3
\newcommand{\ExamplecodeProcessBeginMath}{\ExamplecodePrint{\begingroup\ExamplecodeFormatMath}} % catcode 3
\newcommand{\ExamplecodeProcessEndMath}{\ExamplecodePrint{\endgroup}}
@@ -435,6 +480,7 @@
\parskip=0pt
\parindent=0pt\relax
\let\\=\ExamplecodeLinebreak
+ \setcounter{@examplecode at grouplevel}{0}%
\@examplecode at state@firstindent
\@examplecode at gobblefirsteol
}{%
@@ -548,10 +594,59 @@
\ExamplecodeAllowLinebreak
\@examplecode at allowlinebreakbeforenextfalse
\fi
- \expandafter \@examplecode at check@ii
+ \expandafter \@examplecode at check@i
\fi
}
+\newcommand{\@examplecode at check@i}{%
+ \ifx \@examplecode at nexttoken \ExampleCodeEscapeInside
+ \def\@examplecode at do##1##2{##2\@examplecode at loop}%
+ \expandafter \@gobble
+ \else
+ \expandafter \@firstofone
+ \fi
+ {\ifx \@examplecode at verb@delimiter \relax
+ \def\@examplecode at do{\@examplecode at check@ii}%
+ \expandafter \@gobble
+ \else
+ \expandafter \@firstofone
+ \fi
+ % I cannot nest the if statments because \@examplecode at nexttoken can be an if
+ {\ifx \@examplecode at nexttoken \@examplecode at verb@delimiter
+ \def\@examplecode at do{\@examplecode at handle@verb}%
+ \else
+ \def\@examplecode at do{\@examplecode at check@ii}%
+ \fi}}%
+ \@examplecode at do
+}
+\newcommand{\@examplecode at handle@verb}[1]{%
+ \ExamplecodeFormatVerbDelimiter{\string#1}%
+ \begingroup
+ \ExamplecodeFormatVerb
+ \@examplecode at handle@verb at loop
+}
+\newcommand{\@examplecode at handle@verb at loop}{%
+ \futurelet \@examplecode at nexttoken \@examplecode at handle@verb at check
+}
+\newcommand{\@examplecode at handle@verb at check}{%
+ \ifx \@examplecode at nexttoken \@examplecode at verb@delimiter
+ \def\@examplecode at do{\@examplecode at handle@verb at end}%
+ \else \ifx \@examplecode at nexttoken \bgroup
+ \def\@examplecode at do{\{\afterassignment\@examplecode at handle@verb at loop\let\@examplecode at trash=}%
+ \else \ifx \@examplecode at nexttoken \egroup
+ \def\@examplecode at do{\}\afterassignment\@examplecode at handle@verb at loop\let\@examplecode at trash=}%
+ \else
+ \def\@examplecode at do##1{\string##1\@examplecode at handle@verb at loop}%
+ \fi \fi \fi
+ \@examplecode at do
+}
+\newcommand{\@examplecode at handle@verb at end}[1]{%
+ \ExamplecodeFormatVerbDelimiter{\string#1}%
+ \endgroup
+ \@examplecode at loop
+}
+
+
\newcommand{\@examplecode at check@ii}{%
\ifcat \noexpand\@examplecode at nexttoken \relax
\def\@examplecode at do{\@examplecode at handle@cs}%
@@ -561,11 +656,46 @@
\@examplecode at do
}
\newcommand{\@examplecode at handle@cs}[1]{%
+ \ifx\ExplSyntaxOn#1
+ \@examplecode at explsyntaxon
+ \fi
+ \ifx\ExplSyntaxOff#1
+ \@examplecode at explsyntaxoff
+ \fi
\ExamplecodeSetCmd{#1}%
\@examplecode at state@normal
\ExamplecodeProcessCmd{#1}%
\@examplecode at loop
}
+\let \@examplecode at handle@cs at normal = \@examplecode at handle@cs
+
+\newcommand{\@examplecode at explsyntaxon}{%
+ \let \@examplecode at handle@cs = \@examplecode at handle@cs at expl
+}
+\newcommand{\@examplecode at explsyntaxoff}{%
+ \let \@examplecode at handle@cs = \@examplecode at handle@cs at normal
+}
+
+\newcommand{\@examplecode at handle@cs at expl}[1]{%
+ \def\@examplecode at tmp@csname{#1}%
+ \@examplecode at handle@cs at expl@loop
+}
+\newcommand{\@examplecode at handle@cs at expl@loop}{%
+ \futurelet \@examplecode at nexttoken \@examplecode at handle@cs at expl@check
+}
+\newcommand{\@examplecode at handle@cs at expl@check}{%
+ \ifx \@examplecode at nexttoken _%
+ \def\@examplecode at do##1{\appto\@examplecode at tmp@csname{\textunderscore}\@examplecode at handle@cs at expl@loop}%
+ \else\ifx \@examplecode at nexttoken :%
+ \def\@examplecode at do##1{\appto\@examplecode at tmp@csname{##1}\@examplecode at handle@cs at expl@loop}%
+ \else\ifcat \noexpand\@examplecode at nexttoken a%
+ \def\@examplecode at do##1{\appto\@examplecode at tmp@csname{##1}\@examplecode at handle@cs at expl@loop}%
+ \else
+ \def\@examplecode at do{\expandafter\@examplecode at handle@cs at normal\expandafter{\@examplecode at tmp@csname}}%
+ \fi\fi\fi
+ \@examplecode at do
+}
+
\newcommand{\ExamplecodeSetCmd}[1]{\edef\@examplecode at cs{\detokenize{#1}}}
\newcommand{\ExamplecodeNoCmd}{\def\@examplecode at cs{}}
\ExamplecodeNoCmd
@@ -705,12 +835,13 @@
\@examplecode at loop
}
\newcommand{\@examplecode at math@begin}{%
+ \xdef\@examplecode at grouplevel@mathenter{\the at examplecode@grouplevel}%
\@examplecode at state@normal
\begingroup
\let\@examplecode at handlemeta=\@examplecode at handlenormaltoken
\ExamplecodeProcessBeginMath
\let\@examplecode at math@begin=\relax
- \def\@examplecode at math@end{\def\@examplecode at math@end{\ExamplecodeProcessEndMath\endgroup}}%
+ \def\@examplecode at math@end{\def\@examplecode at math@end{\ExamplecodeProcessEndMath\endgroup\gdef\@examplecode at grouplevel@mathenter{-1}}}%
}
\newcommand{\@examplecode at handleparameter}[1]{%
@@ -775,4 +906,44 @@
\@examplecode at loop
}%
}%
+
+
+% ---------- input command ---------
+
+\begingroup\@examplecode at setcatcodes\gdef\@examplecode at magic@comment at prefix{% !}\gdef\@examplecode at empty@line{
+}\gdef\@examplecode at input@testmarkup{\input{preamble/testmarkup}
+}\endgroup
+
+\ExplSyntaxOn
+\newcommand\inputexamplecode[1]{%
+ \group_begin:
+ \@examplecode at setcatcodes
+ \ior_open:Nn \g_tmpa_ior {#1}
+ \tl_clear:N \l_file_contents_tl
+ \bool_set_false:N \l_tmpa_bool
+ \ior_map_inline:Nn \g_tmpa_ior {
+ \bool_if:NF \l_tmpa_bool {
+ \tl_set:Nx\l_tmpa_tl{\tl_range:nnn{##1}{1}{3}}
+ \tl_if_eq:NNTF \@examplecode at magic@comment at prefix \l_tmpa_tl {
+ % do nothing
+ }{\tl_if_eq:NNTF \@examplecode at empty@line \l_tmpa_tl {
+ % do nothing
+ }{\tl_if_eq:NNTF \@examplecode at input@testmarkup \l_tmpa_tl {
+ % do nothing
+ }{
+ \bool_set_true:N \l_tmpa_bool
+ }}}
+ }
+ \bool_if:NT \l_tmpa_bool {
+ \tl_put_right:Nn \l_file_contents_tl {##1}
+ }
+ }
+ \ior_close:N \g_tmpa_ior
+ \def\l_tmpa_tl{\begin{examplecode}\EolOther}
+ \expandafter \l_tmpa_tl \l_file_contents_tl
+ \end{examplecode}
+ \group_end:
+}
+\ExplSyntaxOff
+
\makeatother
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/geometry.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/geometry.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/geometry.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,12 @@
+% !TeX root = ../easyfloats.tex
+
+\reversemarginpar
+\marginparpush=0pt
+
+% copied from ltxdoc.cls
+\setlength{\textwidth}{355pt}
+\addtolength\marginparwidth{30pt}
+\addtolength\oddsidemargin{20pt}
+\addtolength\evensidemargin{20pt}
+
+\usepackage{parskip}
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/geometry.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/keydoc.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/keydoc.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/keydoc.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -602,7 +602,7 @@
\let\keydoc at lookahead@gobble=\@empty
\else
\ifkeydoc at isrelated
- \PackageError{keydoc}{expexcted another keydoc command after /}{}%
+ \PackageError{keydoc}{expected another keydoc command after /}{}%
\fi
\keydoc at printvalues
\keydoc at descriptionsep
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/macros.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/macros.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/macros.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -28,11 +28,19 @@
% \radiooff
% draws a deactivated radio button
%
-% \DescribeHandler[<class>]{<name>}
-% Typesets the handler name as a \marginpar.
-% The same like all other \Describe* macros defined by dtxdescribe
-% just for handlers.
+% \DescribeMacro{<name>}
+% \DescribeEnv{<name>}
+% \DescribeKey{<name>}
+% \DescribeHandler{<name>}
+% Prints the name in the margin, similar to the dtxdescribe package.
+% A link target and \ignorespaces are added in description-links.tex.
%
+% \cmd{<name>}
+% To reference a command described with \DescribeMacro.
+%
+% \env{<name>}
+% To reference an environment described with \DescribeEnv.
+%
% \handler{<name>}
% To reference a handler described with \DescribeHandler.
%
@@ -39,11 +47,20 @@
% \filename{<filename>}
% Typesets a file name in the pdf.
%
+% \pkg{<name>}
+% To reference a package.
+%
+% \tikzlibrary{<name>}
+% To reference a TikZ library.
+%
+% \meta{<name>}
+% Similar to the dtxdescribe package.
+%
% \pkgoptn{<option>}
% Typesets a package option in the pdf.
% \key{<option>}
% Typesets a macro/environment option in the pdf.
-% Usually \optn is used for both macro options and package options.
+% When using the dtxdescribe package \optn is used for both macro options and package options.
% However, I am using pgfkeys for macro options and standard LaTeX
% for package options making the two types of options quite different.
% Unlike some other packages the easyfloats package does not allow to
@@ -55,7 +72,7 @@
% \DescribeKey for macro/environment options.
% So it is only consistent to have two different macros for typesetting
% macro/environment and package/class options.
-% I have redefined \optn to print an error in order to avoid ambiguity.
+% I have defined \optn to print an error in order to avoid confusion.
% \val{<value>}
% typesets the value of a key. Package options don't have values.
%
@@ -79,6 +96,16 @@
% Formats inline code.
% It does not change catcodes or performs any other kind of magic.
% <texcode> is executed as TeX code.
+%
+% \formatlabel{<label>}
+% How to format the name of a label used in an example.
+%
+% \formatcaption{<label>}
+% How to format the caption used in an example.
+%
+% \notocspace
+% inserts a negative vertical space in the table of contents
+% in order to cancel out an undesired space after a section
\usepackage{relsize}
@@ -126,6 +153,14 @@
\newcommand{\filename}{\emph}
+% links are added in description-links.tex
+\newcommand\cmd[1]{\texttt{\string#1}}
+\newcommand\env[1]{\texttt{#1}}
+\newcommand\optn[1]{\texttt{#1}}
+\newcommand\meta[1]{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}
+\newcommand\pkg[1]{\textsf{#1}}
+\newcommand\tikzlibrary[1]{\textsf{#1}}
+
\newcommand{\pkgoptn}{\optn}
\newcommand{\key}{\optn}
\let\pkgoptn=\optn
@@ -138,7 +173,33 @@
\newcommand{\val}[1]{#1}
\makeatletter
-\newcommand*{\DescribeHandler}[2][]{\DTXD at margintagindex{#1}{#2}{Handler}{handler}{usage}}
+\newcommand\MacroFont{%
+ % copied from dtxdescribe.sty
+ \fontencoding\encodingdefault
+ \fontfamily\ttdefault
+ \fontseries\mddefault
+ \fontshape\updefault
+ \small
+}
+\DeclareDocumentCommand{\MarginParForDescribe}{om}{%
+ \leavevmode
+ \marginpar{%
+ \raggedleft
+ \makebox[0pt][r]{%
+ \strut
+ \IfValueT{#1}{{\scriptsize\sffamily#1}\quad}%
+ \MacroFont
+ #2%
+ }%
+ }%
+}
+% link target and \ignorespaces are added in description-links.tex
+\NewDocumentCommand{\DescribeMacro}{m}{\MarginParForDescribe{\string#1}}
+\NewDocumentCommand{\DescribeEnv}{m}{\MarginParForDescribe[Env]{#1}}
+\NewDocumentCommand{\DescribeKey}{m}{\MarginParForDescribe[Key]{#1}}
+\NewDocumentCommand{\DescribeHandler}{m}{\MarginParForDescribe[Handler]{#1}}
+% \valdoc (defined in description-links.tex) is used for values to keys
+% \pkgoptndoc (defined in description-links.tex) is used for package options
\newcommand{\errormessage}{%
\begingroup
@@ -186,9 +247,26 @@
}
+\newcommand\notocspace{\addtocontents{toc}{\vspace*{-.8em}}}
+
+
+\newcommand\UnderscoreSubscript{_}
+\ExplSyntaxOn
+\NewDocumentCommand\formatlabel{m}{%
+ \group_begin:
+ \def\l_format_label_name_tl{#1}
+ \exp_args:NNo \tl_replace_all:Nnn \l_format_label_name_tl {\UnderscoreSubscript}{\textunderscore}
+ \texttt{\l_format_label_name_tl}
+ \group_end:
+}
+\ExplSyntaxOff
+\let\formatcaption=\formatlabel
+
+
% ---------- \formatcode ---------
\newcommand{\formatcode}[1]{{\ttfamily\smaller[.5]\fboxsep=.5pt\colorbox{codebackground!50}{\vphantom\}\colorlet{linkcolor}{codelinkcolor}#1}}}
+\newcommand{\formatchar}[1]{\formatcode{\char`#1}}
\newcommand{\formatcodeinsection}[1]{{\ttfamily#1}}
\newcommand{\formatcodeinmarginpar}[1]{\formatcodeinsection{\small#1}}
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/markdown.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/markdown.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/markdown.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -150,4 +150,8 @@
}%
}
+\AtEndDocument{%
+ \@makeother*
+}
+
\makeatother
Added: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/todo.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/todo.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/todo.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,12 @@
+% !TeX root = ../easyfloats.tex
+
+\newcommand{\TODO}[1]{%
+ \par
+ \fcolorbox{red}{white}{%
+ \begin{minipage}{\dimexpr\linewidth - 2\fboxsep - 2\fboxrule}%
+ \textcolor{red}{\textbf{TODO}}
+ #1%
+ \end{minipage}%
+ }%
+ \par
+}
Property changes on: trunk/Master/texmf-dist/doc/latex/easyfloats/preamble/todo.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/easyfloats/undescribed-keywords.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/easyfloats/undescribed-keywords.tex 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/doc/latex/easyfloats/undescribed-keywords.tex 2024-10-29 20:07:23 UTC (rev 72699)
@@ -12,6 +12,9 @@
\NoDescribePkg{geometry}
\NoDescribePkg{fontenc}
\NoDescribePkg{lmodern}
+\NoDescribePkg{calc}
+\NoDescribePkg{url}
+\NoDescribePkg{lastpage}
% standard preamble
\NoDescribeMacro\documentclass
@@ -26,6 +29,7 @@
\NoDescribeMacro\typeout
\NoDescribeMacro\@empty
\NoDescribeMacro\@tfor
+\NoDescribeMacro\NewDocumentCommand
% standard document
\NoDescribeEnv{document}
@@ -33,10 +37,12 @@
\NoDescribeMacro\begin
\NoDescribeMacro\end
\NoDescribeEnv{center}
+\NoDescribeEnv{itemize}
\NoDescribeMacro\centering
\NoDescribeMacro\caption
\NoDescribeMacro\label
\NoDescribeMacro\texttt
+\NoDescribeMacro\emph
\NoDescribeMacro\small
\NoDescribeMacro\href
\NoDescribeMacro\vdots
@@ -45,10 +51,16 @@
\NoDescribeMacro\ref
\NoDescribeMacro\pageref
\NoDescribeMacro\raggedleft
+\NoDescribeMacro\raggedright
\NoDescribeMacro\bigskip
\NoDescribeMacro\verb
\NoDescribeMacro\hspace
\NoDescribeMacro\phantom
+\NoDescribeMacro\rule
+\NoDescribeMacro\columnwidth
+\NoDescribeMacro\clearpage
+\NoDescribeMacro\TeX
+\NoDescribeMacro\ %
% escape sequences
\NoDescribeMacro\textbackslash
@@ -70,7 +82,6 @@
\NoDescribeVal{t}
\NoDescribeVal{b}
\NoDescribeVal{p}
-\NoDescribeVal{H}
\NoDescribeVal{h!}
\NoDescribeVal{c}
\NoDescribeVal{T}
@@ -77,9 +88,10 @@
\NoDescribeVal{B}
\NoDescribeVal{auto}
\NoDescribeVal{Auto}
+\NoDescribeVal{auto-inverted}
+\NoDescribeVal{Auto-inverted}
\NoDescribeVal{l}
\NoDescribeVal{r}
-\NoDescribeVal{s}
\NoDescribeVal{tbp}
\NoDescribeVal{lof}
\NoDescribeVal{lot}
@@ -92,9 +104,22 @@
\NoDescribeVal{boxed}
% plain TeX
+\NoDescribeMacro\let
\NoDescribeMacro\csname
\NoDescribeMacro\number
+\NoDescribeMacro\leavevmode
+% eTeX
+\NoDescribeMacro\dimexpr
+% expl
+\NoDescribeMacro\ExplSyntaxOn
+\NoDescribeMacro\ExplSyntaxOff
+
+% etoolbox
+\NoDescribeMacro\appto
+\NoDescribeMacro\gappto
+\NoDescribeMacro\AtEndPreamble
+
% units
\NoDescribeVal{cm}
\NoDescribeVal{pt}
@@ -109,11 +134,15 @@
\NoDescribeKey{/object/<options>}
\NoDescribeMacro\object at tableBreakText
+% float
+\NoDescribeMacro\listof
+
% tables
\NoDescribeEnv{table}
\NoDescribeEnv{tabular}
\NoDescribeEnv{tabular*}
\NoDescribeEnv{tabularx}
+\NoDescribeVal{X}
\NoDescribeMacro\\
\NoDescribeMacro\multicolumn
\NoDescribeMacro\hline
@@ -136,6 +165,7 @@
\NoDescribeMacro\includegraphics
\NoDescribeMacro\linewidth
\NoDescribeMacro\listoffigures
+\NoDescribeMacro\listoftables
\NoDescribeMacro\resizebox
% float
@@ -146,13 +176,19 @@
% (sub)caption
\NoDescribeMacro\captionsetup
+\NoDescribeMacro\subcaptionsetup
\NoDescribeMacro\DeclareCaptionJustification
\NoDescribeMacro\DeclareCaptionSubType
+\NoDescribeMacro\DeclareCaptionLabelFormat
\NoDescribeMacro\phantomcaption
\NoDescribeEnv{subfigure}
\NoDescribeEnv{subtable}
+\NoDescribeEnv{subcaptionblock}
\NoDescribeMacro\subcaptionbox
\NoDescribeMacro\captionof
+\NoDescribeMacro\ContinuedFloat
+\NoDescribeKey{justification}
+\NoDescribeKey{singlelinecheck}
% placeins
\NoDescribePkgoptn{section}
@@ -165,8 +201,10 @@
\NoDescribePkgoptn{table}
% siunitx
+\NoDescribeMacro\qty
\NoDescribeMacro\si
\NoDescribeMacro\degree
+\NoDescribeMacro\percent
\NoDescribeVal{S}
% plain
@@ -174,6 +212,7 @@
\NoDescribeMacro\catcode
\NoDescribeMacro\active
\NoDescribeMacro\the
+\NoDescribeMacro\numexpr
\NoDescribeMacro\string
\NoDescribeMacro\par
\NoDescribeMacro\ifx
@@ -195,27 +234,46 @@
% tikz
\NoDescribeEnv{tikzpicture}
+\NoDescribeMacro\tikz
\NoDescribeMacro\tikzset
\NoDescribeMacro\draw
\NoDescribeMacro\node
\NoDescribeMacro\foreach
+\NoDescribeMacro\pgfmathparse
+\NoDescribeMacro\pgfmathresult
+% minted
+\NoDescribeMacro\mintinline
+
% cleveref
+\NoDescribePkgoptn{nameinlink}
+\NoDescribePkgoptn{noabbrev}
\NoDescribeMacro\cref
+\NoDescribeMacro\Cref
\NoDescribeMacro\cpageref
-\NoDescribePkgoptn{nameinlink}
-\NoDescribePkgoptn{noabbrev}
+% varioref
+\NoDescribeMacro\vref
+\NoDescribeMacro\Vref
+\NoDescribeMacro\fullref
+
% hyperref
\NoDescribeMacro\url
\NoDescribePkgoptn{pdfusetitle}
+\NoDescribePkgoptn{hidelinks}
% pgfkeys
\NoDescribeMacro\pgfkeys
+\NoDescribeMacro\pgfqkeys
\NoDescribeVal{true}
\NoDescribeVal{false}
\NoDescribeHandler{.expand once}
+\NoDescribeHandler{.code}
+\NoDescribeHandler{.value forbidden}
+% url
+\NoDescribeMacro\urldef
+
% keyval
\NoDescribeMacro\setkeys
@@ -227,8 +285,27 @@
\NoDescribeMacro\n
\NoDescribeMacro\i
\NoDescribeMacro\w
+\NoDescribeMacro\includediagramobject
+\NoDescribeMacro\listofdiagrams
+\NoDescribeMacro\composition
+\NoDescribeMacro\element
+\NoDescribeMacro\percentage
+\NoDescribeMacro\col
+\NoDescribeMacro\angle
+\NoDescribeMacro\nextangle
+\NoDescribeMacro\radius
+\NoDescribeMacro\trimspaces
+\NoDescribeMacro\defcalc
+\NoDescribeMacro\verbdef
+\NoDescribeMacro\leftcontent
+\NoDescribeMacro\rightcontent
\NoDescribeEnv{tikzobject}
\NoDescribeEnv{tikz3dobject}
+\NoDescribeEnv{diagramobject}
+\NoDescribeKey{center subcaptions}
+\NoDescribeKey{/object/center subcaptions}
+\NoDescribeKey{diagram}
+\NoDescribeVal{M}
% not used directly
\NoDescribeMacro\center
Modified: trunk/Master/texmf-dist/source/latex/easyfloats/easyfloats.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/easyfloats/easyfloats.dtx 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/source/latex/easyfloats/easyfloats.dtx 2024-10-29 20:07:23 UTC (rev 72699)
@@ -29,9 +29,11 @@
% easyfloats.ins reads this file, strips comments and indentation using docstrip
% and writes the result to the sty file in order to make it faster.
+%TODO: \footnotetext
+
\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{easyfloats}[2020/12/20 v1.0.0]
+\ProvidesPackage{easyfloats}[2024/10/28 v1.1.0]
% ========== options ==========
@@ -186,10 +188,12 @@
\newif\ifobject at isgraphic
\newcommand{\object at hook}{}
+\newcommand{\object at endhook}{}
\newcommand{\subobject at hook}{}
\newcommand{\object at graphic@hook}{}
\newrobustcmd{\AtBeginObject}[1]{\appto\object at hook{#1}}
+\newrobustcmd{\AtEndObject}[1]{\appto\object at endhook{#1}}
\newrobustcmd{\AtBeginSubobject}[1]{\appto\subobject at hook{#1}}
\newrobustcmd{\AtBeginGraphicObject}[1]{\appto\object at graphic@hook{#1}}
@@ -926,11 +930,13 @@
\def\object at longtable@caption at sep{\ObjectDefineEnvargs{longtable}{\\}}%
}
+\newtoks\object at last@arg
\newenvironment{object}[1]{% #1: options
\if at inobject
\PackageError{easyfloats}{object environment may not be nested}{Did you mean to use the subobject environment instead?}%
\fi
\@inobjecttrue
+ \object at last@arg={#1}%
%
\object at restorestandardfloats
%
@@ -992,12 +998,23 @@
\fi
\edef\object at floatenv@begin{\expandonce{\csname\esf at tmp@type\endcsname}}%
\edef\object at floatenv@end{\expandonce{\csname end\esf at tmp@type\endcsname}}%
+ \def\esf at text@I{I}%
\pgfkeysgetvalue{/object/placement}{\esf at tmp@placement}%
\ifx \esf at tmp@placement \@empty
% do nothing
+ \else\ifx \esf at tmp@placement \esf at text@I
+ % I am using placement H with two changes:
+ % - redefined \columnwidth to \linewidth
+ % - added \leavevmode before setting the float in order to get correct indentation
+ % see texdoc float
+ \preto\object at floatenv@begin{%
+ \columnwidth = \linewidth
+ \let \float at endH = \esf at float@endI
+ }%
+ \appto\object at floatenv@begin{[H]}%
\else
\eappto\object at floatenv@begin{[\esf at tmp@placement]}%
- \fi
+ \fi \fi
\fi
%
\pgfkeysgetvalue{/object/details}{\object at details}%
@@ -1030,6 +1047,7 @@
% ---------- execute ---------
%
\object at floatenv@begin
+ \preto\par{\global\@firstsubobjecttrue}%
\let\esf at original@label=\label
\let\esf at original@caption=\caption
\let\label=\object at label
@@ -1044,6 +1062,7 @@
\PackageWarning{easyfloats}{'contains subobjects' is true but the object does not contain any subobjects.}%
\fi
\fi
+ \object at endhook
\let\label=\esf at original@label
\let\caption=\esf at original@caption
\object at processCaptionAndLabel
@@ -1050,6 +1069,18 @@
\object at floatenv@end
}
+% copied from texdoc float, page 8, the definition of \float at endH
+\newcommand\esf at float@endI{%
+ \@endfloatbox
+ \vskip\intextsep
+ \if at flstyle
+ \setbox\@currbox\float at makebox\columnwidth
+ \fi
+ \leavevmode% added by me
+ \box\@currbox
+ \vskip\intextsep\relax
+}
+
\newcommand{\object at processCaptionAndLabel}{%
% position of caption (above/below) is handled by float package (see float style)
\esf at ifpgfkeyhasvalue{/object/caption}{%
@@ -1056,7 +1087,11 @@
\esf at ifpgfkeyhasvalue{/object/list caption}%
{\pgfkeysgetvalue{/object/list caption}{\esf at tmp@caption at short}}%
{\pgfkeysgetvalue{/object/caption}{\esf at tmp@caption at short}}%
- \caption[\esf at tmp@caption at short]{\pgfkeysvalueof{/object/caption}\object at details}%
+ \ifx \esf at tmp@caption at short \@empty
+ \else
+ \edef \esf at tmp@caption at short {{\expandonce{\esf at tmp@caption at short}}}%
+ \fi
+ \expandafter\caption\expandafter[\esf at tmp@caption at short]{\pgfkeysvalueof{/object/caption}\object at details}%
}{%
\ifobject at warnnocaption
\PackageWarning{easyfloats}{%
@@ -1137,6 +1172,21 @@
}
+% ---------- split object environment ----------
+
+\newcommand{\splitobject}{%
+ % does not work inside of \begingroup ... \endgroup
+ % I cannot use anything not expandable here in case a table foot needs to be inserted
+ \expanded{%
+ \noexpand\end{\@currenvir}%
+ \noexpand\begin{\@currenvir}{\the\object at last@arg, warn no label=false, list caption=, exec+={\unexpanded{%
+ \pgfkeyssetvalue{/object/label}{\pgfkeysnovalue}%
+ \ContinuedFloat
+ }}}%
+ }%
+}
+
+
% ---------- lookahead for subobjects ----------
\newcommand{\object at lookahead@nosubobject}{%
@@ -1417,25 +1467,31 @@
auto label strip path/.is if=graphicobject at autolabel@strippath,
auto label strip path=false,
%
+ auto label prefix/.initial=,
+ auto label prefix/.value required,
+ %
warn env/.is if=graphicobject at warnenv,
warn env=true,
%
no env/.is if=graphicobject at noenv,
no env=true,
+ %
+ before graphic/.initial=,
+ before graphic/.value required,
+ %
+ after graphic/.initial=,
+ after graphic/.value required,
}
\newrobustcmd{\includegraphicobject}{% [#1: graphicstyle], [#2: options], #3: graphic filename without extension
- \let\includegraphicobject at after=\@empty
+ \begingroup
\@ifnextchar [%
\includegraphicobject at firstarg
\includegraphicobject at parseoptions
}
\def\includegraphicobject at firstarg[#1]{%
- \begingroup
\@ifnextchar [%
{%
- \begingroup
- \let\includegraphicobject at after=\endgroup
\graphicobjectstyle{#1}%
\includegraphicobject at parseoptions
}%
@@ -1489,6 +1545,7 @@
\ifgraphicobject at autolabel@strippath
\protected at edef\graphicobject at label{\strippath\graphicobject at label}%
\fi
+ \epreto\graphicobject at label{\pgfkeysvalueof{/graphicobject/auto label prefix}}%
\pgfkeyslet{\object at graphic@path/label}{\graphicobject at label}%
}%
\fi
@@ -1511,10 +1568,14 @@
\fi
,
}
+ \pgfkeysvalueof{/graphicobject/before graphic}%
\expandafter\includegraphics\expandafter[\object at graphic@options at tmp]{#3}%
+ \pgfkeysvalueof{/graphicobject/after graphic}%
\end{#1}%
- % if this is \@empty it should not interfere with \ignorespacesafterend (\ignorespaces) or \@endparenv (\@doendpe)
- \includegraphicobject at after
+ % This command is supposed to insert a floating object which can float somewhere else.
+ % Therefore it should not influence the paragraph indentation of the next paragraph (\@endparenv/\@doendpe).
+ \endgroup
+ \ignorespaces
}
\newrobustcmd{\includegraphicsubobject}{%
@@ -1521,7 +1582,6 @@
\begingroup
\def\object at graphic@env{subobject}%
\def\object at graphic@path{/subobject}%
- \def\includegraphicobject at after{\endgroup\ignorespaces}%
\includegraphicobject at parseoptions
}
@@ -1607,11 +1667,15 @@
% http://tug.org/texinfohtml/latex2e.html#minipage
%
% The vertical position of the minipage on the baseline.
- % Allowed values: c, t, b, auto, <empty>.
+ % Allowed values: c, t, b, auto, auto-inverted, <empty>.
% auto means t if the caption is displayed at the top
% or b if the caption is displayed at the bottom
- % so that the captions are aligned if the minipages
+ % so that the captions are aligned if the captions
% have the same height.
+ % auto-inverted means b if the caption is displayed at the top
+ % or t if the caption is displayed at the bottom
+ % so that the captions are aligned if the bodies
+ % have the same height.
% <empty> is equivalent to c.
subpage outer pos/.initial=auto,
subpage outer pos/.value required,
@@ -1849,9 +1913,17 @@
\caption at iftop
{\eappto\subobject at subpage@begin{[T]}}%
{\eappto\subobject at subpage@begin{[B]}}%
+ }{\ifdefstring \subobject at outerpos {auto-inverted}{%
+ \caption at iftop
+ {\eappto\subobject at subpage@begin{[b]}}%
+ {\eappto\subobject at subpage@begin{[t]}}%
+ }{\ifdefstring \subobject at outerpos {Auto-inverted}{%
+ \caption at iftop
+ {\eappto\subobject at subpage@begin{[B]}}%
+ {\eappto\subobject at subpage@begin{[T]}}%
}{%
\eappto\subobject at subpage@begin{[\subobject at outerpos]}%
- }}\fi
+ }}}}\fi
\pgfkeysgetvalue{/subobject/subpage height}{\subobject at height}%
\ifx \subobject at height \@empty
\else
Modified: trunk/Master/texmf-dist/tex/latex/easyfloats/easyfloats.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/easyfloats/easyfloats.sty 2024-10-29 20:07:04 UTC (rev 72698)
+++ trunk/Master/texmf-dist/tex/latex/easyfloats/easyfloats.sty 2024-10-29 20:07:23 UTC (rev 72699)
@@ -28,8 +28,9 @@
%% This work consists of the files listed in easyfloats-file-list.txt.
+
\NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{easyfloats}[2020/12/20 v1.0.0]
+\ProvidesPackage{easyfloats}[2024/10/28 v1.1.0]
\newif\ifesf at loadgraphics
@@ -132,10 +133,12 @@
\newif\ifobject at isgraphic
\newcommand{\object at hook}{}
+\newcommand{\object at endhook}{}
\newcommand{\subobject at hook}{}
\newcommand{\object at graphic@hook}{}
\newrobustcmd{\AtBeginObject}[1]{\appto\object at hook{#1}}
+\newrobustcmd{\AtEndObject}[1]{\appto\object at endhook{#1}}
\newrobustcmd{\AtBeginSubobject}[1]{\appto\subobject at hook{#1}}
\newrobustcmd{\AtBeginGraphicObject}[1]{\appto\object at graphic@hook{#1}}
@@ -685,11 +688,13 @@
\def\object at longtable@caption at sep{\ObjectDefineEnvargs{longtable}{\\}}%
}
+\newtoks\object at last@arg
\newenvironment{object}[1]{% #1: options
\if at inobject
\PackageError{easyfloats}{object environment may not be nested}{Did you mean to use the subobject environment instead?}%
\fi
\@inobjecttrue
+\object at last@arg={#1}%
\object at restorestandardfloats
\object at hook
\ifobject at isgraphic
@@ -738,12 +743,19 @@
\fi
\edef\object at floatenv@begin{\expandonce{\csname\esf at tmp@type\endcsname}}%
\edef\object at floatenv@end{\expandonce{\csname end\esf at tmp@type\endcsname}}%
+\def\esf at text@I{I}%
\pgfkeysgetvalue{/object/placement}{\esf at tmp@placement}%
\ifx \esf at tmp@placement \@empty
+\else\ifx \esf at tmp@placement \esf at text@I
+\preto\object at floatenv@begin{%
+\columnwidth = \linewidth
+\let \float at endH = \esf at float@endI
+}%
+\appto\object at floatenv@begin{[H]}%
\else
\eappto\object at floatenv@begin{[\esf at tmp@placement]}%
+\fi \fi
\fi
-\fi
\pgfkeysgetvalue{/object/details}{\object at details}%
\ifx \object at details \@empty
\else
@@ -767,6 +779,7 @@
\fi
\global \@firstsubobjecttrue
\object at floatenv@begin
+\preto\par{\global\@firstsubobjecttrue}%
\let\esf at original@label=\label
\let\esf at original@caption=\caption
\let\label=\object at label
@@ -781,6 +794,7 @@
\PackageWarning{easyfloats}{'contains subobjects' is true but the object does not contain any subobjects.}%
\fi
\fi
+\object at endhook
\let\label=\esf at original@label
\let\caption=\esf at original@caption
\object at processCaptionAndLabel
@@ -787,12 +801,27 @@
\object at floatenv@end
}
+\newcommand\esf at float@endI{%
+\@endfloatbox
+\vskip\intextsep
+\if at flstyle
+\setbox\@currbox\float at makebox\columnwidth
+\fi
+\leavevmode% added by me
+\box\@currbox
+\vskip\intextsep\relax
+}
+
\newcommand{\object at processCaptionAndLabel}{%
\esf at ifpgfkeyhasvalue{/object/caption}{%
\esf at ifpgfkeyhasvalue{/object/list caption}%
{\pgfkeysgetvalue{/object/list caption}{\esf at tmp@caption at short}}%
{\pgfkeysgetvalue{/object/caption}{\esf at tmp@caption at short}}%
-\caption[\esf at tmp@caption at short]{\pgfkeysvalueof{/object/caption}\object at details}%
+\ifx \esf at tmp@caption at short \@empty
+\else
+\edef \esf at tmp@caption at short {{\expandonce{\esf at tmp@caption at short}}}%
+\fi
+\expandafter\caption\expandafter[\esf at tmp@caption at short]{\pgfkeysvalueof{/object/caption}\object at details}%
}{%
\ifobject at warnnocaption
\PackageWarning{easyfloats}{%
@@ -861,6 +890,17 @@
}
+\newcommand{\splitobject}{%
+\expanded{%
+\noexpand\end{\@currenvir}%
+\noexpand\begin{\@currenvir}{\the\object at last@arg, warn no label=false, list caption=, exec+={\unexpanded{%
+\pgfkeyssetvalue{/object/label}{\pgfkeysnovalue}%
+\ContinuedFloat
+}}}%
+}%
+}
+
+
\newcommand{\object at lookahead@nosubobject}{%
\object at lookahead@begin
}
@@ -1115,24 +1155,27 @@
auto caption strip path=false,
auto label strip path/.is if=graphicobject at autolabel@strippath,
auto label strip path=false,
+auto label prefix/.initial=,
+auto label prefix/.value required,
warn env/.is if=graphicobject at warnenv,
warn env=true,
no env/.is if=graphicobject at noenv,
no env=true,
+before graphic/.initial=,
+before graphic/.value required,
+after graphic/.initial=,
+after graphic/.value required,
}
\newrobustcmd{\includegraphicobject}{% [#1: graphicstyle], [#2: options], #3: graphic filename without extension
-\let\includegraphicobject at after=\@empty
+\begingroup
\@ifnextchar [%
\includegraphicobject at firstarg
\includegraphicobject at parseoptions
}
\def\includegraphicobject at firstarg[#1]{%
-\begingroup
\@ifnextchar [%
{%
-\begingroup
-\let\includegraphicobject at after=\endgroup
\graphicobjectstyle{#1}%
\includegraphicobject at parseoptions
}%
@@ -1182,6 +1225,7 @@
\ifgraphicobject at autolabel@strippath
\protected at edef\graphicobject at label{\strippath\graphicobject at label}%
\fi
+\epreto\graphicobject at label{\pgfkeysvalueof{/graphicobject/auto label prefix}}%
\pgfkeyslet{\object at graphic@path/label}{\graphicobject at label}%
}%
\fi
@@ -1204,9 +1248,12 @@
\fi
,
}
+\pgfkeysvalueof{/graphicobject/before graphic}%
\expandafter\includegraphics\expandafter[\object at graphic@options at tmp]{#3}%
+\pgfkeysvalueof{/graphicobject/after graphic}%
\end{#1}%
-\includegraphicobject at after
+\endgroup
+\ignorespaces
}
\newrobustcmd{\includegraphicsubobject}{%
@@ -1213,7 +1260,6 @@
\begingroup
\def\object at graphic@env{subobject}%
\def\object at graphic@path{/subobject}%
-\def\includegraphicobject at after{\endgroup\ignorespaces}%
\includegraphicobject at parseoptions
}
@@ -1418,9 +1464,17 @@
\caption at iftop
{\eappto\subobject at subpage@begin{[T]}}%
{\eappto\subobject at subpage@begin{[B]}}%
+}{\ifdefstring \subobject at outerpos {auto-inverted}{%
+\caption at iftop
+{\eappto\subobject at subpage@begin{[b]}}%
+{\eappto\subobject at subpage@begin{[t]}}%
+}{\ifdefstring \subobject at outerpos {Auto-inverted}{%
+\caption at iftop
+{\eappto\subobject at subpage@begin{[B]}}%
+{\eappto\subobject at subpage@begin{[T]}}%
}{%
\eappto\subobject at subpage@begin{[\subobject at outerpos]}%
-}}\fi
+}}}}\fi
\pgfkeysgetvalue{/subobject/subpage height}{\subobject at height}%
\ifx \subobject at height \@empty
\else
Added: trunk/Master/texmf-dist/tex/latex/easyfloats/my_biblatex_data_model.dbx
===================================================================
--- trunk/Master/texmf-dist/tex/latex/easyfloats/my_biblatex_data_model.dbx (rev 0)
+++ trunk/Master/texmf-dist/tex/latex/easyfloats/my_biblatex_data_model.dbx 2024-10-29 20:07:23 UTC (rev 72699)
@@ -0,0 +1,5 @@
+% default data model is included automatically
+% if undesired it would need to be cleared with
+% \ResetDatamodelEntrytypes \ResetDatamodelFields \ResetDatamodelEntryfields \ResetDatamodelConstraints
+
+\DeclareDatamodelFields[type=field, datatype=literal]{texdoc}
More information about the tex-live-commits
mailing list.