diff options
Diffstat (limited to 'Master/texmf-dist')
-rw-r--r-- | Master/texmf-dist/doc/latex/fewerfloatpages/README.md | 23 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/fewerfloatpages/changes.txt | 1 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.pdf | bin | 0 -> 595536 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.tex | 4 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.pdf | bin | 0 -> 421147 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.tex | 10 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/fewerfloatpages/l3doc-TUB.cls | 2306 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.dtx | 1350 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.ins | 66 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/fewerfloatpages/fewerfloatpages.sty | 248 |
10 files changed, 4008 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/fewerfloatpages/README.md b/Master/texmf-dist/doc/latex/fewerfloatpages/README.md new file mode 100644 index 00000000000..25a2f6d771b --- /dev/null +++ b/Master/texmf-dist/doc/latex/fewerfloatpages/README.md @@ -0,0 +1,23 @@ +# fewerfloatpages package + +----- + +This package implements a float algorithm extension for handling float +pages. It attempts to reduce the number of unnecessary (fairly empty) +float pages while making sure that floats nevertheless stay close to +their call-outs. Several aspects of the algorithm behavior are +adjustable. + +Package source can be found below: + +https://github.com/FrankMittelbach/fmitex/ + +The license is LPPL 1.3c. + +----- + +Copyright (C) 2019-2020 Frank Mittelbach<br /> +<https://latex-project.org/> <br /> +All rights reserved. + + diff --git a/Master/texmf-dist/doc/latex/fewerfloatpages/changes.txt b/Master/texmf-dist/doc/latex/fewerfloatpages/changes.txt new file mode 100644 index 00000000000..67a21fc352e --- /dev/null +++ b/Master/texmf-dist/doc/latex/fewerfloatpages/changes.txt @@ -0,0 +1 @@ +No changes yet diff --git a/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.pdf b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.pdf Binary files differnew file mode 100644 index 00000000000..305431fc07e --- /dev/null +++ b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.pdf diff --git a/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.tex b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.tex new file mode 100644 index 00000000000..97d00e08772 --- /dev/null +++ b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-code.tex @@ -0,0 +1,4 @@ +% this will typeset documentation + code + +\AtBeginDocument{\AlsoImplementation} +\input{fewerfloatpages.dtx} diff --git a/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.pdf b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.pdf Binary files differnew file mode 100644 index 00000000000..df15415a7d3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.pdf diff --git a/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.tex b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.tex new file mode 100644 index 00000000000..0d4c6d779f4 --- /dev/null +++ b/Master/texmf-dist/doc/latex/fewerfloatpages/fewerfloatpages-doc.tex @@ -0,0 +1,10 @@ +% this will typeset only documentation but not the code + +\AtBeginDocument{\OnlyDescription +% \let\tableofcontents\relax + \IndexPrologue + {\section*{Index} + \markboth{Index}{Index} + \addcontentsline{toc}{section}{Index}} + } +\input{fewerfloatpages.dtx} diff --git a/Master/texmf-dist/doc/latex/fewerfloatpages/l3doc-TUB.cls b/Master/texmf-dist/doc/latex/fewerfloatpages/l3doc-TUB.cls new file mode 100644 index 00000000000..f18911e685a --- /dev/null +++ b/Master/texmf-dist/doc/latex/fewerfloatpages/l3doc-TUB.cls @@ -0,0 +1,2306 @@ +%% +%% This is file `l3doc-TUB.cls' +%% +%% The original source files were: +%% +%% l3doc.dtx (with options: `class') + several manual changes! +%% +%% Copyright (C) 1990-2018 The LaTeX3 Project +%% +%% It may be distributed and/or modified under the conditions of +%% the LaTeX Project Public License (LPPL), either version 1.3c of +%% this license or (at your option) any later version. The latest +%% version of this license is in the file: +%% +%% https://www.latex-project.org/lppl.txt +%% +%% File: l3doc.dtx Copyright (C) 1990-2018 The LaTeX3 project +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% This is really a temporary file intended for a single article +%% written for TugBoat It is a copy of l3doc.cls with a couple of +%% changes, nothing more. Eventually this will get replaced by a real +%% class once l3doc.cls gets properly split into a class part and a +%% support part. +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% +%% If you use this for anything other than processing the documents it +%% was meant for (which so far is 2) you are on your own :-) +%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\RequirePackage{expl3,xparse,calc} +\ProvidesExplClass{l3doc-TUB}{2020/02/14}{} + {L3 Experimental documentation class (special version for TUGboat with fixes)} +\clist_new:N \g_docinput_clist +\seq_new:N \g_doc_functions_seq +\seq_new:N \g_doc_macros_seq +\bool_new:N \l__codedoc_detect_internals_bool +\bool_set_true:N \l__codedoc_detect_internals_bool +\tl_new:N \l__codedoc_detect_internals_tl +\tl_new:N \l__codedoc_detect_internals_cs_tl +\coffin_new:N \l__codedoc_output_coffin +\coffin_new:N \l__codedoc_functions_coffin +\coffin_new:N \l__codedoc_descr_coffin +\coffin_new:N \l__codedoc_syntax_coffin +\box_new:N \g__codedoc_syntax_box +\bool_new:N \l__codedoc_in_function_bool +\bool_new:N \l__codedoc_long_name_bool +\dim_new:N \l__codedoc_trial_width_dim +\int_new:N \l__codedoc_nested_macro_int +\bool_new:N \l__codedoc_macro_tested_bool +\prop_new:N \g__codedoc_missing_tests_prop +\seq_new:N \g__codedoc_not_tested_seq +\seq_new:N \g__codedoc_testfiles_seq +\bool_new:N \l__codedoc_macro_internal_set_bool +\bool_new:N \l__codedoc_macro_internal_bool +\bool_new:N \l__codedoc_macro_TF_bool +\bool_new:N \l__codedoc_macro_pTF_bool +\bool_new:N \l__codedoc_macro_noTF_bool +\bool_new:N \l__codedoc_macro_EXP_bool +\bool_new:N \l__codedoc_macro_rEXP_bool +\bool_new:N \l__codedoc_macro_var_bool +\tl_new:N \l__codedoc_override_module_tl +\tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } +\tl_new:N \l__codedoc_macro_documented_tl +\bool_new:N \g__codedoc_lmodern_bool +\bool_new:N \g__codedoc_checkfunc_bool +\bool_new:N \g__codedoc_checktest_bool +\bool_new:N \g__codedoc_kernel_bool +\tl_new:N \l__codedoc_tmpa_tl +\tl_new:N \l__codedoc_tmpb_tl +\int_new:N \l__codedoc_tmpa_int +\int_new:N \l__codedoc_tmpa_seq +\tl_new:N \l__codedoc_names_block_tl +\seq_new:N \g__codedoc_variants_seq +\bool_new:N \l__codedoc_names_verb_bool +\seq_new:N \l__codedoc_names_seq +\seq_new:N \g__codedoc_nested_names_seq +\tl_const:Nx \c__codedoc_backslash_tl { \iow_char:N \\ } +\exp_last_unbraced:NNo + \cs_new_eq:NN \c__codedoc_backslash_token { \c__codedoc_backslash_tl } +\tl_new:N \l__codedoc_index_macro_tl +\tl_new:N \l__codedoc_index_key_tl +\tl_new:N \l__codedoc_index_module_tl +\bool_new:N \l__codedoc_index_internal_bool +\tl_new:N \g__codedoc_module_name_tl +\tl_const:Nn \c__codedoc_iow_rule_tl + { ======================================== } +\tl_const:Nn \c__codedoc_iow_mid_rule_tl + { -------------------------------------- } +\box_new:N \l__codedoc_macro_box +\box_new:N \l__codedoc_macro_index_box +\int_new:N \l__codedoc_macro_int +\tl_new:N \l__codedoc_cmd_tl +\tl_new:N \l__codedoc_cmd_index_tl +\tl_new:N \l__codedoc_cmd_module_tl +\bool_new:N \l__codedoc_cmd_noindex_bool +\bool_new:N \l__codedoc_cmd_replace_bool +\bool_new:N \l__codedoc_in_implementation_bool +\bool_new:N \g__codedoc_typeset_documentation_bool +\bool_new:N \g__codedoc_typeset_implementation_bool +\bool_set_true:N \g__codedoc_typeset_documentation_bool +\bool_set_true:N \g__codedoc_typeset_implementation_bool +\tl_new:N \g__codedoc_base_name_tl +\prop_new:N \l__codedoc_variants_prop +\clist_new:N \l__codedoc_function_label_clist +\bool_new:N \l__codedoc_no_label_bool +\tl_new:N \l__codedoc_date_added_tl +\tl_new:N \l__codedoc_date_updated_tl +\tl_new:N \l__codedoc_macro_argument_tl +\cs_new_eq:NN \__codedoc_tmpa:w ? +\cs_new_eq:NN \__codedoc_tmpb:w ? +\cs_generate_variant:Nn \seq_set_split:Nnn { NoV } +\cs_generate_variant:Nn \seq_gput_right:Nn { Nf } +\cs_generate_variant:Nn \str_case:nn { fn } +\cs_generate_variant:Nn \tl_count:n { f } +\cs_generate_variant:Nn \tl_greplace_all:Nnn { Nx , Nno } +\cs_generate_variant:Nn \tl_if_empty:nTF { f } +\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNTF { o } +\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNT { o } +\cs_generate_variant:Nn \tl_if_head_eq_charcode:nNF { o } +\cs_generate_variant:Nn \tl_if_head_eq_meaning:nNF { V } +\cs_generate_variant:Nn \tl_if_in:nnTF { no , oo } +\cs_generate_variant:Nn \tl_if_in:NnTF { No } +\cs_generate_variant:Nn \tl_if_in:NnT { No } +\cs_generate_variant:Nn \tl_if_in:NnF { No } +\cs_generate_variant:Nn \tl_remove_all:Nn { Nx } +\cs_generate_variant:Nn \tl_replace_all:Nnn { Nx , Nnx, No , Nno } +\cs_generate_variant:Nn \tl_replace_once:Nnn { Noo } +\cs_generate_variant:Nn \tl_to_str:n { f , o } +\cs_generate_variant:Nn \prop_get:NnNTF { Nx } +\cs_generate_variant:Nn \prop_put:Nnn { Nx } +\cs_generate_variant:Nn \prop_gput:Nnn { NVx } +\prg_new_protected_conditional:Npnn \__codedoc_if_almost_str:n #1 { TF , T , F } + { + \int_compare:nNnTF + { \tl_count:n {#1} } + < { \tl_count:f { \tl_to_str:f {#1} } } + { \prg_return_false: } + { \prg_return_true: } + } +\cs_generate_variant:Nn \__codedoc_if_almost_str:nT { V } +\cs_new_protected:Npn \__codedoc_trim_right:Nn #1#2 + { + \cs_set:Npn \__codedoc_tmp:w ##1 #2 ##2 \q_stop { \exp_not:n {##1} } + \tl_set:Nx #1 { \exp_after:wN \__codedoc_tmp:w #1 #2 \q_stop } + } +\cs_generate_variant:Nn \__codedoc_trim_right:Nn { No } +\prg_new_protected_conditional:Npnn \__codedoc_str_if_begin:nn #1#2 { TF , T , F } + { + \tl_if_in:ooTF + { \exp_after:wN \scan_stop: \tl_to_str:n {#1} } + { \exp_after:wN \scan_stop: \tl_to_str:n {#2} } + { \prg_return_true: } + { \prg_return_false: } + } +\prg_generate_conditional_variant:Nnn \__codedoc_str_if_begin:nn + { oo } { TF , T , F } +\cs_new_protected:Npn \__codedoc_replace_at_at:N #1 + { + \bool_if:NT \l__codedoc_in_implementation_bool + { + \bool_if:NT \l__codedoc_detect_internals_bool + { \__codedoc_detect_internals:N #1 } + } + \tl_if_empty:NF \g__codedoc_module_name_tl + { + \exp_args:NNo \__codedoc_replace_at_at_aux:Nn + #1 \g__codedoc_module_name_tl + } + } +\cs_new_protected:Npx \__codedoc_replace_at_at_aux:Nn #1#2 + { + \tl_replace_all:Nnn #1 { \token_to_str:N @ } { @ } + \tl_replace_all:Nnn #1 { \token_to_str:N _ } { _ } + \tl_replace_all:Nnn #1 { @ @ @ @ } { \token_to_str:N a a } + \tl_replace_all:Nnn #1 { _ _ @ @ } { _ _ #2 } + \tl_replace_all:Nnn #1 { _ @ @ } { _ _ #2 } + \tl_replace_all:Nnn #1 { @ @ } { _ _ #2 } + \tl_replace_all:Nnn #1 { \token_to_str:N a a } { @ @ } + } +\group_begin: + \char_set_catcode_active:N \^^M + \cs_new_protected:Npn \__codedoc_detect_internals:N #1 + { + \tl_set_eq:NN \l__codedoc_detect_internals_tl #1 + \tl_replace_all:Non \l__codedoc_detect_internals_tl { \token_to_str:N _ } { _ } + \seq_set_split:NnV \l__codedoc_tmpa_seq { _ _ } \l__codedoc_detect_internals_tl + \seq_pop_left:NN \l__codedoc_tmpa_seq \l__codedoc_detect_internals_tl + \seq_map_variable:NNn \l__codedoc_tmpa_seq \l__codedoc_detect_internals_tl + { + \__codedoc_trim_right:No \l__codedoc_detect_internals_tl + \c_catcode_active_space_tl + \__codedoc_trim_right:Nn \l__codedoc_detect_internals_tl ^^M + \__codedoc_if_detect_internals_ok:NF \l__codedoc_detect_internals_tl + { + \tl_set_eq:NN \l__codedoc_detect_internals_cs_tl \l__codedoc_detect_internals_tl + \__codedoc_trim_right:Nn \l__codedoc_detect_internals_tl _ + \__codedoc_trim_right:Nn \l__codedoc_detect_internals_tl : + \__codedoc_trim_right:No \l__codedoc_detect_internals_tl { \token_to_str:N : } + \msg_warning:nnxxx { l3doc-TUB } { foreign-internal } + { \tl_to_str:N \l__codedoc_detect_internals_cs_tl } + { \tl_to_str:N \l__codedoc_detect_internals_tl } + { \tl_to_str:N \g__codedoc_module_name_tl } + } + } + } +\group_end: +\prg_new_protected_conditional:Npnn \__codedoc_if_detect_internals_ok:N #1 { F } + { + \__codedoc_str_if_begin:ooTF {#1} { \g__codedoc_module_name_tl _ } + { \prg_return_true: } + { + \__codedoc_str_if_begin:ooTF {#1} { \g__codedoc_module_name_tl : } + { \prg_return_true: } + { + \bool_if:NTF \g__codedoc_kernel_bool + { + \__codedoc_str_if_begin:ooTF {#1} { kernel _ } + { \prg_return_true: } + { \prg_return_false: } + } + { \prg_return_false: } + } + } + } +\cs_new:Npn \__codedoc_signature_base_form:n #1 + { \__codedoc_signature_base_form_aux:n #1 \q_stop } +\cs_new:Npn \__codedoc_signature_base_form_aux:n #1 + { + \str_case:nnTF {#1} + { + { N } { N } + { c } { N } + { n } { n } + { o } { n } + { f } { n } + { x } { n } + { V } { n } + { v } { n } + } + { \__codedoc_signature_base_form_aux:n } + { \__codedoc_signature_base_form_aux:w #1 } + } +\cs_new:Npn \__codedoc_signature_base_form_aux:w #1 \q_stop + { \exp_not:n {#1} } +\cs_new:Npn \__codedoc_predicate_from_base:n #1 + { + \__codedoc_get_function_name:n {#1} + \tl_to_str:n { _p: } + \__codedoc_get_function_signature:n {#1} + } +\cs_new:Npn \__codedoc_get_function_name:n #1 + { \__codedoc_split_function_do:nn {#1} { \use_i:nnn } } +\cs_new:Npn \__codedoc_get_function_signature:n #1 + { \__codedoc_split_function_do:nn {#1} { \use_ii:nnn } } +\cs_set_protected:Npn \__codedoc_tmpa:w #1 + { + \cs_new:Npn \__codedoc_split_function_do:nn ##1 + { + \exp_after:wN \__codedoc_split_function_auxi:w + \tl_to_str:n {##1} \q_mark \c_true_bool + #1 \q_mark \c_false_bool + \q_stop + } + \cs_new:Npn \__codedoc_split_function_auxi:w + ##1 #1 ##2 \q_mark ##3##4 \q_stop ##5 + { \__codedoc_split_function_auxii:w {##5} ##1 \q_mark \q_stop {##2} ##3 } + \cs_new:Npn \__codedoc_split_function_auxii:w + ##1##2 \q_mark ##3 \q_stop + { ##1 {##2} } + } +\exp_args:No \__codedoc_tmpa:w { \token_to_str:N : } +\cs_generate_variant:Nn \__codedoc_split_function_do:nn { o } +\cs_new_protected:Npn \__codedoc_key_get_base:nN #1#2 + { + \__codedoc_if_almost_str:nTF {#1} + { + \__codedoc_key_get_base_TF:nN {#1} \l__codedoc_tmpa_tl + \tl_set:Nx #2 + { \__codedoc_split_function_do:on \l__codedoc_tmpa_tl { \__codedoc_base_form_aux:nnN } } + } + { \tl_set:Nn #2 {#1} } + } +\cs_new:Npx \__codedoc_key_get_base_TF:nN #1#2 + { + \tl_set:Nx #2 { \exp_not:N \tl_to_str:n {#1} \scan_stop: } + \tl_if_in:NnTF #2 { \tl_to_str:n { F } \scan_stop: } + { + \tl_if_in:NnF #2 { \tl_to_str:n { TF } \scan_stop: } + { + \tl_replace_once:Nnn #2 + { \tl_to_str:n { F } \scan_stop: } + { \tl_to_str:n { TF } \scan_stop: } + } + } + { + \tl_replace_once:Nnn #2 + { \tl_to_str:n { T } \scan_stop: } + { \tl_to_str:n { TF } \scan_stop: } + } + \tl_remove_once:Nn #2 { \scan_stop: } + } +\cs_new:Npn \__codedoc_base_form_aux:nnN #1#2#3 + { + \exp_not:n {#1} + \bool_if:NT #3 + { + \token_to_str:N : + \str_if_eq:nnTF { #1 ~ } { \exp_args } + { \exp_not:n {#2} } + { \__codedoc_signature_base_form:n {#2} } + } + } +\cs_new_protected:Npn \__codedoc_base_form_signature_do:nnn #1#2#3 + { + \__codedoc_split_function_do:nn {#1} + { \__codedoc_base_form_aux:nnnnnN {#1} {#2} {#3} } + } +\cs_new_protected:Npn \__codedoc_base_form_aux:nnnnnN #1#2#3#4#5#6 + { + \bool_if:NTF #6 + { + \tl_if_head_eq_charcode:nNTF {#4} : + { #2 {#1} } + { + \use:x + { + \exp_not:n {#3} + { \__codedoc_base_form_aux:nnN {#4} {#5} #6 } + } + {#4} {#5} + } + } + { #2 {#1} } + } +\prg_new_conditional:Npnn \__codedoc_date_compare:nNn #1#2#3 { TF , T , F , p } + { \__codedoc_date_compare_aux:w #1--- \q_mark #2 #3--- \q_stop } +\cs_new:Npn \__codedoc_date_compare_aux:w + #1 - #2 - #3 - #4 \q_mark #5 #6 - #7 - #8 - #9 \q_stop + { + \__codedoc_date_compare_aux:nnnNnnn + { \tl_if_empty:nTF {#1} { 0 } {#1} } + { \tl_if_empty:nTF {#2} { 0 } {#2} } + { \tl_if_empty:nTF {#3} { 0 } {#3} } + #5 + { \tl_if_empty:nTF {#6} { 0 } {#6} } + { \tl_if_empty:nTF {#7} { 0 } {#7} } + { \tl_if_empty:nTF {#8} { 0 } {#8} } + } +\cs_new:Npn \__codedoc_date_compare_aux:nnnNnnn #1#2#3#4#5#6#7 + { + \int_compare:nNnTF {#1} = {#5} + { + \int_compare:nNnTF {#2} = {#6} + { + \int_compare:nNnTF {#3} #4 {#7} + { \prg_return_true: } { \prg_return_false: } + } + { + \int_compare:nNnTF {#2} #4 {#6} + { \prg_return_true: } { \prg_return_false: } + } + } + { + \int_compare:nNnTF {#1} #4 {#5} + { \prg_return_true: } { \prg_return_false: } + } + \use_none:n + \q_stop + } +\cs_new:Npn \__codedoc_gprop_name:n #1 { g__codedoc ~ \tl_to_str:n {#1} } +\cs_new:Npn \__codedoc_lseq_name:n #1 { l__codedoc ~ \tl_to_str:n {#1} } +\msg_new:nnnn { l3doc-TUB } { no-signature-TF } + { Function/macro~'#1'~cannot~be~turned~into~a~conditional. } + { + A~function~or~macro~environment~with~option~pTF,~TF~or~noTF~ + received~the~argument~'#1'.~This~function's~name~has~no~ + ':'~hence~it~is~not~clear~where~to~add~'_p'~or~'TF'.~ + Please~follow~expl3~naming~conventions. + } +\msg_new:nnn { l3doc-TUB } { deprecated-function } + { The~deprecated~function(s)~'#1'~should~have~been~removed~on~#2. } +\msg_new:nnn { l3doc-TUB } { date-format } + { The~date~'#1'~should~be~given~in~YYYY-MM-DD~format. } +\msg_new:nnn { l3doc-TUB } { syntax-nested-function } + { + The~'syntax'~environment~should~be~used~in~the~ + innermost~'function'~environment. + } +\msg_new:nnn { l3doc-TUB } { multiple-syntax } + { + The~'syntax'~environment~should~only~be~used~once~in~ + a~'function'~environment. + } +\msg_new:nnn { l3doc-TUB } { deprecated-option } + { The~option~'#1'~has~been~deprecated~for~'#2'. } +\msg_new:nnn { l3doc-TUB } { foreign-internal } + { + A~control~sequence~of~the~form~'...__#1'~was~used.~ + It~should~only~be~used~in~the~module~'#2' + \tl_if_empty:nF {#3} { ,~not~in~'#3' } . + } +\DeclareOption { a5paper } { \@latexerr { Option~not~supported } { } } +\DeclareOption { full } + { + \bool_gset_true:N \g__codedoc_typeset_documentation_bool + \bool_gset_true:N \g__codedoc_typeset_implementation_bool + } +\DeclareOption { onlydoc } + { + \bool_gset_true:N \g__codedoc_typeset_documentation_bool + \bool_gset_false:N \g__codedoc_typeset_implementation_bool + } +\DeclareOption { check } + { \bool_gset_true:N \g__codedoc_checkfunc_bool } +\DeclareOption { nocheck } + { \bool_gset_false:N \g__codedoc_checkfunc_bool } +\DeclareOption { checktest } + { \bool_gset_true:N \g__codedoc_checktest_bool } +\DeclareOption { nochecktest } + { \bool_gset_false:N \g__codedoc_checktest_bool } +\DeclareOption { kernel } + { \bool_gset_true:N \g__codedoc_kernel_bool } +\DeclareOption { stdmodule } + { \bool_gset_false:N \g__codedoc_kernel_bool } +\DeclareOption { cm-default } + { \bool_gset_false:N \g__codedoc_lmodern_bool } +\DeclareOption { lm-default } + { \bool_gset_true:N \g__codedoc_lmodern_bool } +\DeclareOption* { \PassOptionsToClass { \CurrentOption } { ltugboat } } +\ExecuteOptions { full, kernel, nocheck, nochecktest, lm-default } +%%FMi \PassOptionsToClass { a4paper } { article } +\msg_new:nnn { l3doc-TUB } { input-cfg } + { Local~config~file~l3doc-TUB.cfg~loaded. } +\file_if_exist:nT { l3doc-TUB.cfg } + { + \file_input:nT { l3doc-TUB.cfg } + { + \cs_if_exist:cF { ExplMakeTitle } + { \msg_info:nn { l3doc-TUB } { input-cfg } } + } + } +\ProcessOptions +\LoadClass[final]{ltugboat} +\RequirePackage{doc} + +\newcommand\bibname{References} % otherwise \bibname is undefined at \Finale +\TBtocsectionspace=0pt plus 1pt + +\IndexPrologue + {\section*{Index} + \markboth{Index}{Index} + \addcontentsline{toc}{section}{Index} + \noindent + Underlined numbers point to the definition, + italicized numbers denote the pages where the + corresponding entry is described, + all others indicate the places where it is used.} +%\EnableCrossrefs +%\CodelineIndex + +\RequirePackage + { + microtype, + array, + alphalph, + amsmath, + amssymb, + booktabs, + color, + colortbl, + hologo, + enumitem, + pifont, + textcomp, + trace, + underscore, + csquotes, + fancyvrb, + verbatim + } +\raggedbottom +\bool_if:NT \g__codedoc_lmodern_bool + { + \RequirePackage[T1]{fontenc} + \RequirePackage{lmodern} + \group_begin: + \ttfamily + \DeclareFontShape{T1}{lmtt}{m}{it}{<->ec-lmtto10}{} + \group_end: + } + +\RequirePackage{hypdoc} + +%%FMi: +\hypersetup{allcolors=black} + +\cs_gset:Npn \MakePrivateLetters + { + \char_set_catcode_letter:N \@ + \char_set_catcode_letter:N \_ + \char_set_catcode_letter:N \: + } +\setcounter{StandardModuleDepth}{1} +\@addtoreset{CodelineNo}{part} +\tl_replace_once:Nnn \theCodelineNo + { \HDorg@theCodelineNo } + { \textcolor[gray]{0.5} { \sffamily\tiny\arabic{CodelineNo} } } +\fvset{gobble=2} +\cs_gset_eq:NN \verbatim \Verbatim +\cs_gset_eq:NN \endverbatim \endVerbatim +\cs_set_protected:Npn \ifnot@excluded + { + \exp_args:Nxx \expanded@notin + { \c__codedoc_backslash_tl \tl_to_str:N \macro@namepart , } + { \exp_args:NV \tl_to_str:n \index@excludelist } + } +\cs_new:Npn \pdfstringnewline { : ~ } +\DeclareExpandableDocumentCommand + { \__codedoc_pdfstring_newline:w } { s o m } { \pdfstringnewline #3 } +\pdfstringdefDisableCommands + { \cs_set_eq:NN \\ \__codedoc_pdfstring_newline:w } +\setlength \textwidth { 385pt } +\addtolength \marginparwidth { 30pt } +\addtolength \oddsidemargin { 20pt } +\addtolength \evensidemargin { 20pt } +\cs_new_eq:NN \__codedoc_oldlist:nn \list +\cs_gset:Npn \list #1 #2 + { \__codedoc_oldlist:nn {#1} { #2 \dim_zero:N \listparindent } } +\setlength \parindent { 2em } +\setlength \itemindent { 0pt } +\setlength \parskip { 1pt plus 3pt minus 0pt } +\tl_gset:Nn \partname {File} +\@addtoreset{section}{part} +\cs_gset:Npn \l@section #1#2 + { + \ifnum \c@tocdepth >\z@ + \addpenalty\@secpenalty + \addvspace{\TBtocsectionspace}% + \setlength\@tempdima{2.5em} % was 1.5em + \begingroup + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + \leavevmode \TBtocsectionfont + \advance\leftskip\@tempdima + \hskip -\leftskip + #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par + \endgroup + \fi + } +\cs_gset:Npn \l@subsection + { \@dottedtocline{2}{2.5em}{2.3em} } % #2 = 1.5em +\AtBeginDocument + { + \MakeShortVerb \" + \MakeShortVerb \| + \onecolumn + \SelfDocumenting + } +\AtEndDocument + { + \DeleteShortVerb \" + \DeleteShortVerb \| + } +\providecommand*\eTeX{\hologo{eTeX}} +\providecommand*\IniTeX{\hologo{iniTeX}} +\providecommand*\Lua{Lua} +\providecommand*\LuaTeX{\hologo{LuaTeX}} +\providecommand*\pdfTeX{\hologo{pdfTeX}} +\providecommand*\XeTeX{\hologo{XeTeX}} +\providecommand*\pTeX{p\kern-.2em\hologo{TeX}} +\providecommand*\upTeX{up\kern-.2em\hologo{TeX}} +\providecommand*\epTeX{$\varepsilon$-\pTeX} +\providecommand*\eupTeX{$\varepsilon$-\upTeX} +\DeclareDocumentCommand \cmd { O{} m } + { \__codedoc_cmd:no {#1} { \token_to_str:N #2 } } +\DeclareDocumentCommand \cs { O{} m } + { \__codedoc_cmd:no {#1} { \c__codedoc_backslash_tl #2 } } +\DeclareDocumentCommand \tn { O{} m } + { + \__codedoc_cmd:no + { module = TeX , replace = false , #1 } + { \c__codedoc_backslash_tl #2 } + } +\DeclareDocumentCommand \meta { m } + { \__codedoc_meta:n {#1} } +\DeclareExpandableDocumentCommand + { \__codedoc_pdfstring_cmd:w } { o m } { \token_to_str:N #2 } +\DeclareExpandableDocumentCommand + { \__codedoc_pdfstring_cs:w } { o m } { \textbackslash \tl_to_str:n {#2} } +\cs_new:Npn \__codedoc_pdfstring_meta:w #1 + { < \tl_to_str:n {#1} > } +\pdfstringdefDisableCommands + { + \cs_set_eq:NN \cmd \__codedoc_pdfstring_cmd:w + \cs_set_eq:NN \cs \__codedoc_pdfstring_cs:w + \cs_set_eq:NN \tn \__codedoc_pdfstring_cs:w + \cs_set_eq:NN \meta \__codedoc_pdfstring_meta:w + } +\newcommand\Arg[1] + { \texttt{\char`\{} \meta{#1} \texttt{\char`\}} } +\providecommand\marg[1]{ \Arg{#1} } +\providecommand\oarg[1]{ \texttt[ \meta{#1} \texttt] } +\providecommand\parg[1]{ \texttt( \meta{#1} \texttt) } +\DeclareRobustCommand \file {\nolinkurl} +\DeclareRobustCommand \env {\texttt} +\DeclareRobustCommand \pkg {\textsf} +\DeclareRobustCommand \cls {\textsf} +\NewDocumentCommand \EnableDocumentation { } + { \bool_gset_true:N \g__codedoc_typeset_documentation_bool } +\NewDocumentCommand \EnableImplementation { } + { \bool_gset_true:N \g__codedoc_typeset_implementation_bool } +\NewDocumentCommand \DisableDocumentation { } + { \bool_gset_false:N \g__codedoc_typeset_documentation_bool } +\NewDocumentCommand \DisableImplementation { } + { \bool_gset_false:N \g__codedoc_typeset_implementation_bool } +\NewDocumentEnvironment { documentation } { } + { + \bool_if:NTF \g__codedoc_typeset_documentation_bool + { \bool_set_false:N \l__codedoc_in_implementation_bool } + { \comment } + } + { \bool_if:NF \g__codedoc_typeset_documentation_bool { \endcomment } } +\NewDocumentEnvironment { implementation } { } + { + \bool_if:NTF \g__codedoc_typeset_implementation_bool + { \bool_set_true:N \l__codedoc_in_implementation_bool } + { \comment } + } + { \bool_if:NF \g__codedoc_typeset_implementation_bool { \endcomment } } +\DeclareDocumentEnvironment { variable } { O{} +v } + { + \bool_if:NTF \l__codedoc_in_implementation_bool + { \__codedoc_macro:nnw { var , #1 } {#2} } + { \__codedoc_function:nnw {#1} {#2} } + } + { + \bool_if:NTF \l__codedoc_in_implementation_bool + { \__codedoc_macro_end: } + { \__codedoc_function_end: } + } +\DeclareDocumentEnvironment { function } { O{} +v } + { \__codedoc_function:nnw {#1} {#2} } + { \__codedoc_function_end: } +\DeclareDocumentEnvironment { macro } { O{} +v } + { \__codedoc_macro:nnw {#1} {#2} } + { \__codedoc_macro_end: } +\NewDocumentEnvironment { syntax } { } + { \__codedoc_syntax:w } + { + \__codedoc_syntax_end: + \ignorespacesafterend + } +\NewDocumentEnvironment { texnote } { } + { + \endgraf + \vspace{3mm} + \small\textbf{\TeX~hackers~note:} + } + { + \vspace{3mm} + } +\NewDocumentEnvironment { arguments } { } + { + \enumerate [ + nolistsep , + label = \texttt{\#\arabic*} ~ : , + labelsep = * , + ] + } + { + \endenumerate + } +\NewDocumentCommand { \CodedocExplain } { } + { \CodedocExplainEXP \ \CodedocExplainREXP \ \CodedocExplainTF } +\NewDocumentCommand { \CodedocExplainEXP } { } + { + \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{expstar}{}}% + \__codedoc_typeset_exp:\ indicates~fully~expandable~functions,~which~ + can~be~used~within~an~\texttt{x}-type~argument~(in~plain~ + \TeX{}~terms,~inside~an~\cs{edef}),~as~well~as~within~an~ + \texttt{f}-type~argument. + } +\NewDocumentCommand { \CodedocExplainREXP } { } + { + \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{rexpstar}{}}% + \__codedoc_typeset_rexp:\ indicates~ + restricted~expandable~functions,~which~can~be~used~within~an~ + \texttt{x}-type~argument~but~cannot~be~fully~expanded~within~an~ + \texttt{f}-type~argument. + } +\NewDocumentCommand { \CodedocExplainTF } { } + { + \raisebox{\baselineskip}[0pt][0pt]{\hypertarget{explTF}{}}% + \__codedoc_typeset_TF:\ indicates~conditional~(\texttt{if})~functions~ + whose~variants~with~\texttt{T},~\texttt{F}~and~\texttt{TF}~ + argument~specifiers~expect~different~ + \enquote{true}/\enquote{false}~branches. + } +\keys_define:nn { l3doc-TUB/cmd } + { + index .tl_set:N = \l__codedoc_cmd_index_tl , + module .tl_set:N = \l__codedoc_cmd_module_tl , + no-index .bool_set:N = \l__codedoc_cmd_noindex_bool , + replace .bool_set:N = \l__codedoc_cmd_replace_bool , + } +\cs_new_protected:Npn \__codedoc_cmd:nn #1#2 + { + \bool_set_false:N \l__codedoc_cmd_noindex_bool + \bool_set_true:N \l__codedoc_cmd_replace_bool + \tl_set:Nn \l__codedoc_cmd_index_tl { \q_no_value } + \tl_set:Nn \l__codedoc_cmd_module_tl { \q_no_value } + \keys_set:nn { l3doc-TUB/cmd } {#1} + \tl_set:Nn \l__codedoc_cmd_tl {#2} + \bool_if:NT \l__codedoc_cmd_replace_bool + { + \tl_set_rescan:Nnn \l__codedoc_tmpb_tl { } { _ } + \tl_replace_all:Non \l__codedoc_cmd_tl \l__codedoc_tmpb_tl { _ } + \__codedoc_replace_at_at:N \l__codedoc_cmd_tl + \tl_replace_all:Nno \l__codedoc_cmd_tl { _ } \l__codedoc_tmpb_tl + } + \mode_if_math:T { \mbox } + { + \verbatim@font + \__codedoc_if_almost_str:VT \l__codedoc_cmd_tl + { + \tl_set:Nx \l__codedoc_cmd_tl { \tl_to_str:N \l__codedoc_cmd_tl } + \tl_replace_all:Non \l__codedoc_cmd_tl + { \token_to_str:N _ } { \_ } + } + \tl_replace_all:Nnn \l__codedoc_cmd_tl { ~ } { \@xobeysp } + \l__codedoc_cmd_tl + \@ + } + \bool_if:NF \l__codedoc_cmd_noindex_bool + { + \quark_if_no_value:NF \l__codedoc_cmd_index_tl + { + \tl_set:Nx \l__codedoc_cmd_tl + { \c_backslash_str \exp_not:o { \l__codedoc_cmd_index_tl } } + } + + \exp_args:No \__codedoc_key_get:n { \l__codedoc_cmd_tl } + \quark_if_no_value:NF \l__codedoc_cmd_module_tl + { + \tl_set:Nx \l__codedoc_index_module_tl + { \tl_to_str:N \l__codedoc_cmd_module_tl } + } + \__codedoc_special_index_module:ooonN + { \l__codedoc_index_key_tl } + { \l__codedoc_index_macro_tl } + { \l__codedoc_index_module_tl } + { usage } + \l__codedoc_index_internal_bool + } + } +\cs_generate_variant:Nn \__codedoc_cmd:nn { no } +\cs_new_protected:Npn \__codedoc_meta:n #1 + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \tl_map_inline:nn + { { 3 } { 4 } { 7 } { 8 } { 11 } { 12 } { 13 } } + { + \tl_set_rescan:Nnn \l__codedoc_tmpb_tl + { \char_set_catcode:nn { `_ } {##1} } { _ } + \tl_replace_all:Non \l__codedoc_tmpa_tl \l__codedoc_tmpb_tl + { \__codedoc_ensuremath_sb:n } + } + \exp_args:NV \__codedoc_meta_original:n \l__codedoc_tmpa_tl + } +\cs_new_protected:Npn \__codedoc_ensuremath_sb:n #1 + { \ensuremath { \sb {#1} } } +\cs_new_protected:Npn \__codedoc_meta_original:n #1 + { + \ensuremath \langle + \mode_if_math:T { \nfss@text } + { + \meta@font@select + \edef \meta@hyphen@restore + { \hyphenchar \the \font \the \hyphenchar \font } + \hyphenchar \font \m@ne + \language \l@nohyphenation + #1 \/ + \meta@hyphen@restore + } + \ensuremath \rangle + } +\cs_new_protected:Npn \__codedoc_typeset_exp: + { \hyperlink{expstar} {$\star$} } +\cs_new_protected:Npn \__codedoc_typeset_rexp: + { \hyperlink{rexpstar} {\ding{73}} } % hollow star +\cs_new_protected:Npn \__codedoc_typeset_TF: + { + \hyperlink{explTF} + { + \color{black} + \itshape TF + \makebox[0pt][r] + { + \color{red} + \underline { \phantom{\itshape TF} \kern-0.1em } + } + } + } +\cs_new_protected:Npn \__codedoc_typeset_aux:n #1 + { + { \color[gray]{0.5} #1 } + } +\cs_new_protected:Npn \__codedoc_get_hyper_target:nN #1#2 + { + \tl_set:Nx #2 { \tl_to_str:n {#1} } + \tl_replace_all:Nxn #2 { \iow_char:N \_ } { / } + \tl_remove_all:Nx #2 { \iow_char:N \\ } + \tl_put_left:Nn #2 { doc/function// } + } +\cs_generate_variant:Nn \__codedoc_get_hyper_target:nN { o , x } +\cs_new_protected:Npn \__codedoc_names_get_seq:nN #1#2 + { + \tl_set:Nx \l__codedoc_tmpa_tl { \tl_to_str:n {#1} } + \bool_if:NTF \l__codedoc_names_verb_bool + { + \seq_clear:N #2 + \seq_put_right:NV #2 \l__codedoc_tmpa_tl + } + { + \tl_remove_all:Nx \l__codedoc_tmpa_tl + { \iow_char:N \^^M \iow_char:N \% } + \tl_remove_all:Nx \l__codedoc_tmpa_tl { \tl_to_str:n { ^ ^ A } } + \tl_remove_all:Nx \l__codedoc_tmpa_tl { \iow_char:N \^^I } + \tl_remove_all:Nx \l__codedoc_tmpa_tl { \iow_char:N \^^M } + \__codedoc_replace_at_at:N \l__codedoc_tmpa_tl + \exp_args:NNx \seq_set_from_clist:Nn #2 + { \tl_to_str:N \l__codedoc_tmpa_tl } + } + } +\cs_new_protected:Npn \__codedoc_names_parse: + { + \tl_clear:N \l__codedoc_names_block_tl + \seq_map_function:NN + \l__codedoc_names_seq + \__codedoc_names_parse_one:n + } +\cs_new_protected:Npn \__codedoc_names_parse_one:n #1 + { + \__codedoc_split_function_do:nn {#1} + { \__codedoc_names_parse_one_aux:nnNn } + {#1} + } +\cs_new_protected:Npn \__codedoc_names_parse_one_aux:nnNn #1#2#3#4 + { + \bool_if:NTF #3 + { + \tl_if_head_eq_charcode:nNTF {#2} : + { \__codedoc_names_parse_aux:nnn {#4} {#4} { \scan_stop: } } + { + \exp_args:Nx \__codedoc_names_parse_aux:nnn + { \__codedoc_base_form_aux:nnN {#1} {#2} #3 } + {#1} {#2} + } + } + { + \bool_if:NT \l__codedoc_macro_TF_bool + { \msg_error:nnx { l3doc-TUB } { no-signature-TF } {#4} } + \__codedoc_names_parse_aux:nnn {#4} {#4} { \scan_stop: } + } + } +\cs_new_protected:Npn \__codedoc_names_parse_aux:nnn #1 + { \exp_args:Nc \__codedoc_names_parse_aux:Nnn { \__codedoc_lseq_name:n {#1} } } +\cs_new_protected:Npn \__codedoc_names_parse_aux:Nnn #1#2#3 + { + \tl_if_in:NnF \l__codedoc_names_block_tl {#1} + { + \tl_put_right:Nn \l__codedoc_names_block_tl {#1} + \seq_clear_new:N #1 + \seq_put_right:Nn #1 {#2} + } + \seq_put_right:Nn #1 {#3} + } +\cs_new_protected:Npn \__codedoc_names_typeset: + { + \tl_map_function:NN \l__codedoc_names_block_tl + \__codedoc_names_typeset_auxi:n + } +\cs_new_protected:Npn \__codedoc_names_typeset_auxi:n #1 + { + \seq_pop:NN #1 \l__codedoc_tmpa_tl + \tl_gset_eq:NN \g__codedoc_base_name_tl \l__codedoc_tmpa_tl + \tl_greplace_all:Nno \g__codedoc_base_name_tl + { ~ } { \c_catcode_other_space_tl } + \seq_get:NN #1 \l__codedoc_tmpa_tl + \str_if_eq:eeTF { \l__codedoc_tmpa_tl } { \scan_stop: } + { + \seq_gclear:N \g__codedoc_variants_seq + \__codedoc_names_typeset_auxii:x { \g__codedoc_base_name_tl } + } + { + \seq_gset_eq:NN \g__codedoc_variants_seq #1 + \seq_gpop:NN \g__codedoc_variants_seq \l__codedoc_tmpb_tl + \__codedoc_names_typeset_auxii:x + { \g__codedoc_base_name_tl : \l__codedoc_tmpb_tl } + } + } +\cs_new_protected:Npn \__codedoc_names_typeset_auxii:n #1 + { + \bool_if:NT \l__codedoc_macro_pTF_bool + { + \__codedoc_names_typeset_block:xN + { \__codedoc_predicate_from_base:n {#1} } + \c_false_bool + } + \bool_if:NT \l__codedoc_macro_noTF_bool + { \__codedoc_names_typeset_block:nN {#1} \c_false_bool } + \__codedoc_names_typeset_block:nN {#1} \l__codedoc_macro_TF_bool + } +\cs_generate_variant:Nn \__codedoc_names_typeset_auxii:n { x } +\cs_new_protected:Npn \__codedoc_names_typeset_block:nN + { + \int_compare:nNnTF \l__codedoc_nested_macro_int = 0 + { \__codedoc_typeset_function_block:nN } + { \__codedoc_macro_typeset_block:nN } + } +\cs_generate_variant:Nn \__codedoc_names_typeset_block:nN { x } +\prg_new_conditional:Npnn \__codedoc_if_macro_internal:n #1 { p , T , F , TF } + { + \bool_if:NTF \l__codedoc_macro_internal_set_bool + { + \bool_if:NTF \l__codedoc_macro_internal_bool + { \prg_return_true: } { \prg_return_false: } + } + { + \tl_if_empty:fTF + { + \exp_after:wN \__codedoc_if_macro_internal_aux:w + \tl_to_str:n { #1 ~ __ } + } + { \prg_return_false: } { \prg_return_true: } + } + } +\exp_last_unbraced:NNNNo + \cs_new:Npn \__codedoc_if_macro_internal_aux:w #1 { \tl_to_str:n { __ } } { } +\cs_new_protected:Npn \__codedoc_names_block_base_map:N #1 + { + \tl_map_inline:Nn \l__codedoc_names_block_tl + { + \group_begin: + \seq_set_eq:NN \l__codedoc_tmpa_seq ##1 + \seq_pop:NN \l__codedoc_tmpa_seq \l__codedoc_tmpa_tl + \seq_get:NN \l__codedoc_tmpa_seq \l__codedoc_tmpb_tl + \exp_args:NNx + \group_end: + #1 + { + \l__codedoc_tmpa_tl + \str_if_eq:eeF { \l__codedoc_tmpb_tl } { \scan_stop: } + { : \l__codedoc_tmpb_tl } + \bool_if:NT \l__codedoc_macro_TF_bool { TF } + } + } + } +\keys_define:nn { l3doc-TUB/function } + { + TF .value_forbidden:n = true , + TF .code:n = + { + \bool_set_true:N \l__codedoc_macro_TF_bool + } , + EXP .value_forbidden:n = true , + EXP .code:n = + { + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + rEXP .value_forbidden:n = true , + rEXP .code:n = + { + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_true:N \l__codedoc_macro_rEXP_bool + } , + pTF .value_forbidden:n = true , + pTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_pTF_bool + \bool_set_true:N \l__codedoc_macro_TF_bool + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + noTF .value_forbidden:n = true , + noTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_noTF_bool + \bool_set_true:N \l__codedoc_macro_TF_bool + } , + added .code:n = { \__codedoc_date_set:Nn \l__codedoc_date_added_tl {#1} }, + updated .code:n = { \__codedoc_date_set:Nn \l__codedoc_date_updated_tl {#1} } , + deprecated .code:n = { \__codedoc_deprecated_on:n {#1} } , + tested .code:n = { } , + label .code:n = + { + \clist_set:Nn \l__codedoc_function_label_clist {#1} + \bool_set_true:N \l__codedoc_no_label_bool + } , + verb .value_forbidden:n = true , + verb .bool_set:N = \l__codedoc_names_verb_bool , + module .tl_set:N = \l__codedoc_override_module_tl , + } +\cs_new_protected:Npn \__codedoc_date_set:Nn #1#2 + { + \tl_set:Nn #1 {#2} + \regex_replace_once:nnNF + { \A(\d\d\d\d)[-/](\d\d?)[-/](\d\d?)\Z } { \1-\2-\3 } #1 + { + \msg_error:nnn { l3doc-TUB } { date-format } {#2} + \tl_set:Nn #1 { 1970-01-01 } + } + } +\cs_new_protected:Npn \__codedoc_deprecated_on:n #1 + { + \__codedoc_date_set:Nn \l__codedoc_tmpa_tl {#1} + \exp_args:No \__codedoc_date_compare:nNnT + { \l__codedoc_tmpa_tl } < { \tex_year:D - \tex_month:D - \tex_day:D } + { + \msg_error:nnxx { l3doc-TUB } { deprecated-function } + { \tl_to_str:N \l__codedoc_macro_argument_tl } + { \l__codedoc_tmpa_tl } + } + \bool_set_true:N \l__codedoc_macro_internal_bool + \bool_set_true:N \l__codedoc_macro_internal_set_bool + } +\cs_new_protected:Npn \__codedoc_function:nnw #1#2 + { + \__codedoc_function_typeset_start: + \__codedoc_function_init: + \tl_set:Nn \l__codedoc_macro_argument_tl {#2} + \keys_set:nn { l3doc-TUB/function } {#1} + \__codedoc_names_get_seq:nN {#2} \l__codedoc_names_seq + \__codedoc_names_parse: + \__codedoc_function_typeset: + \__codedoc_function_reset: + \__codedoc_function_descr_start:w + } +\cs_new_protected:Npn \__codedoc_function_end: + { + \__codedoc_function_descr_stop: + \__codedoc_function_assemble: + \__codedoc_function_typeset_stop: + } +\cs_new_protected:Npn \__codedoc_function_typeset_start: + { + \par \bigskip \noindent + } +\cs_new_protected:Npn \__codedoc_function_typeset_stop: + { + \par + \allowbreak + } +\cs_new_protected:Npn \__codedoc_function_init: + { + \box_if_empty:NF \g__codedoc_syntax_box + { \msg_error:nn { l3doc-TUB } { syntax-nested-function } } + \coffin_clear:N \l__codedoc_descr_coffin + \box_gclear:N \g__codedoc_syntax_box + \coffin_clear:N \l__codedoc_syntax_coffin + \coffin_clear:N \l__codedoc_functions_coffin + \bool_set_false:N \l__codedoc_macro_TF_bool + \bool_set_false:N \l__codedoc_macro_pTF_bool + \bool_set_false:N \l__codedoc_macro_noTF_bool + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + \bool_set_false:N \l__codedoc_no_label_bool + \bool_set_false:N \l__codedoc_names_verb_bool + \bool_set_true:N \l__codedoc_in_function_bool + \clist_clear:N \l__codedoc_function_label_clist + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + \char_set_active_eq:NN \< \__codedoc_shorthand_meta: + \char_set_catcode_active:N \< + } +\cs_new_protected:Npn \__codedoc_shorthand_meta: + { \mode_if_math:TF { < } { \__codedoc_shorthand_meta:w } } +\cs_new_protected_nopar:Npn \__codedoc_shorthand_meta:w #1 > { \meta {#1} } +\cs_new_protected:Npn \__codedoc_function_reset: + { + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + } +\cs_new_protected:Npn \__codedoc_function_typeset: + { + \dim_zero:N \l__codedoc_trial_width_dim + \hcoffin_set:Nn \l__codedoc_functions_coffin { \__codedoc_typeset_functions: } + \dim_set:Nn \l__codedoc_trial_width_dim + { \box_wd:N \l__codedoc_functions_coffin } + \bool_set:Nn \l__codedoc_long_name_bool + { \dim_compare_p:nNn \l__codedoc_trial_width_dim > {\marginparwidth + 1cm} } % FMi crude fix + } +\cs_new_protected:Npn \__codedoc_function_descr_start:w + { + \vcoffin_set:Nnw \l__codedoc_descr_coffin { \textwidth } + \noindent \ignorespaces + } +\cs_new_protected:Npn \__codedoc_function_descr_stop: + { \vcoffin_set_end: } +\cs_new_protected:Npn \__codedoc_function_assemble: + { + \hcoffin_set:Nn \l__codedoc_syntax_coffin + { \box_use_drop:N \g__codedoc_syntax_box } + \bool_if:NTF \l__codedoc_long_name_bool + { + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {hc} {vc} + \l__codedoc_syntax_coffin {l} {T} + {0pt} {0pt} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {t} + \l__codedoc_functions_coffin {r} {t} + {-\marginparsep} {0pt} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {b} + \l__codedoc_descr_coffin {l} {t} + {0.75\marginparwidth + \marginparsep} {-\medskipamount} + \coffin_typeset:Nnnnn \l__codedoc_output_coffin + {\l__codedoc_descr_coffin-l} {\l__codedoc_descr_coffin-t} + {0pt} {0pt} + } + { + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {hc} {vc} + \l__codedoc_syntax_coffin {l} {t} + {0pt} {0pt} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {b} + \l__codedoc_descr_coffin {l} {t} + {0pt} {-\medskipamount} + \coffin_join:NnnNnnnn + \l__codedoc_output_coffin {l} {t} + \l__codedoc_functions_coffin {r} {t} + {-\marginparsep} {0pt} + \coffin_typeset:Nnnnn \l__codedoc_output_coffin + {\l__codedoc_syntax_coffin-l} {\l__codedoc_syntax_coffin-T} + {0pt} {0pt} + } + } +\cs_new_protected:Npn \__codedoc_typeset_functions: + { + \small\ttfamily + \HD@savedestfalse + \HD@target + \Hy@MakeCurrentHref { HD. \int_use:N \c@HD@hypercount } + \begin{tabular} [t] { @{} l @{} >{\hspace{\tabcolsep}} r @{} } + \toprule + \__codedoc_function_extra_labels: + \__codedoc_names_typeset: + \__codedoc_typeset_dates: + \bottomrule + \end{tabular} + \normalfont\normalsize + } +\cs_new_protected:Npn \__codedoc_typeset_function_block:nN #1#2 + { + \__codedoc_function_index:x + { #1 \bool_if:NT #2 { \tl_to_str:n {TF} } } + \__codedoc_function_label:xN {#1} #2 + #1 + \bool_if:NT #2 { \__codedoc_typeset_TF: } + \__codedoc_typeset_expandability: + \seq_if_empty:NF \g__codedoc_variants_seq + { \__codedoc_typeset_variant_list:nN {#1} #2 } + \\ + } +\cs_generate_variant:Nn \__codedoc_typeset_function_block:nN { x } +\cs_new_protected:Npn \__codedoc_function_index:n #1 + { + \seq_gput_right:Nn \g_doc_functions_seq {#1} + \__codedoc_special_index:nn {#1} { usage } + } +\cs_generate_variant:Nn \__codedoc_function_index:n { x } +\cs_new_protected:Npn \__codedoc_typeset_expandability: + { + & + \bool_if:NT \l__codedoc_macro_EXP_bool { \__codedoc_typeset_exp: } + \bool_if:NT \l__codedoc_macro_rEXP_bool { \__codedoc_typeset_rexp: } + } +\cs_new_protected:Npn \__codedoc_typeset_variant_list:nN #1#2 + { + \\ + \__codedoc_typeset_aux:n { \__codedoc_get_function_name:n {#1} } + : + \int_compare:nTF { \seq_count:N \g__codedoc_variants_seq == 1 } + { \seq_use:Nn \g__codedoc_variants_seq { } } + { + \textrm( + \seq_use:Nn \g__codedoc_variants_seq { \textrm| } + \textrm) + } + \bool_if:NT #2 { \__codedoc_typeset_TF: } + \__codedoc_typeset_expandability: + } +\cs_new_protected:Npn \__codedoc_function_extra_labels: + { + \bool_if:NT \l__codedoc_no_label_bool + { + \clist_map_inline:Nn \l__codedoc_function_label_clist + { + \__codedoc_get_hyper_target:oN { \token_to_str:N ##1 } + \l__codedoc_tmpa_tl + \exp_args:No \label { \l__codedoc_tmpa_tl } + } + } + } +\cs_new_protected:Npn \__codedoc_function_label:nN #1#2 + { + \bool_if:NF \l__codedoc_no_label_bool + { + \__codedoc_get_hyper_target:xN + { + \exp_not:n {#1} + \bool_if:NT #2 { \tl_to_str:n {TF} } + } + \l__codedoc_tmpa_tl + \exp_args:No \label { \l__codedoc_tmpa_tl } + } + } +\cs_generate_variant:Nn \__codedoc_function_label:nN { x } +\cs_new:Npn \__codedoc_typeset_dates: + { + \bool_lazy_and:nnF + { \tl_if_empty_p:N \l__codedoc_date_added_tl } + { \tl_if_empty_p:N \l__codedoc_date_updated_tl } + { \midrule } + \tl_if_empty:NF \l__codedoc_date_added_tl + { + \multicolumn { 2 } { @{} r @{} } + { \scriptsize New: \, \l__codedoc_date_added_tl } \\ + } + + \tl_if_empty:NF \l__codedoc_date_updated_tl + { + \multicolumn { 2 } { @{} r @{} } + { \scriptsize Updated: \, \l__codedoc_date_updated_tl } \\ + } + } +\dim_new:N \l__codedoc_syntax_dim +\cs_new_protected:Npn \__codedoc_syntax:w + { + \box_if_empty:NF \g__codedoc_syntax_box + { \msg_error:nn { l3doc-TUB } { multiple-syntax } } + \dim_set:Nn \l__codedoc_syntax_dim + { + \textwidth + \bool_if:NT \l__codedoc_long_name_bool + { + 0.75 \marginparwidth - \l__codedoc_trial_width_dim } + } + \hbox_gset:Nw \g__codedoc_syntax_box + \small \ttfamily + \arrayrulecolor{white} + \begin{tabular} { @{} l @{} } + \toprule + \begin{minipage}[t]{\l__codedoc_syntax_dim} + \raggedright + \obeyspaces + \obeylines + } +\cs_new_protected:Npn \__codedoc_syntax_end: + { + \end{minipage} + \end{tabular} + \arrayrulecolor{black} + \hbox_gset_end: + \bool_if:NF \l__codedoc_in_function_bool + { + \begin{quote} + \mode_leave_vertical: + \box_use_drop:N \g__codedoc_syntax_box + \end{quote} + } + } +\keys_define:nn { l3doc-TUB/macro } + { + aux .value_forbidden:n = true , + aux .code:n = + { + \msg_warning:nnnn { l3doc-TUB } { deprecated-option } + { aux } { function/macro } + } , + internal .value_forbidden:n = true , + internal .code:n = + { + \bool_set_true:N \l__codedoc_macro_internal_bool + \bool_set_true:N \l__codedoc_macro_internal_set_bool + } , + int .value_forbidden:n = true , + int .code:n = + { + \bool_set_true:N \l__codedoc_macro_internal_bool + \bool_set_true:N \l__codedoc_macro_internal_set_bool + } , + var .value_forbidden:n = true , + var .code:n = + { \bool_set_true:N \l__codedoc_macro_var_bool } , + TF .value_forbidden:n = true , + TF .code:n = + { \bool_set_true:N \l__codedoc_macro_TF_bool } , + pTF .value_forbidden:n = true , + pTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_TF_bool + \bool_set_true:N \l__codedoc_macro_pTF_bool + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + noTF .value_forbidden:n = true , + noTF .code:n = + { + \bool_set_true:N \l__codedoc_macro_TF_bool + \bool_set_true:N \l__codedoc_macro_noTF_bool + } , + EXP .value_forbidden:n = true , + EXP .code:n = + { + \bool_set_true:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + } , + rEXP .value_forbidden:n = true , + rEXP .code:n = + { + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_true:N \l__codedoc_macro_rEXP_bool + } , + tested .code:n = + { + \bool_set_true:N \l__codedoc_macro_tested_bool + } , + added .code:n = {} , % TODO + updated .code:n = {} , % TODO + deprecated .code:n = { \__codedoc_deprecated_on:n {#1} } , + verb .bool_set:N = \l__codedoc_names_verb_bool , + module .tl_set:N = \l__codedoc_override_module_tl , + documented-as .tl_set:N = \l__codedoc_macro_documented_tl , + } +\cs_new_protected:Npn \__codedoc_macro:nnw #1#2 + { + \__codedoc_macro_init: + \tl_set:Nn \l__codedoc_macro_argument_tl {#2} + \keys_set:nn { l3doc-TUB/macro } {#1} + \__codedoc_names_get_seq:nN {#2} \l__codedoc_names_seq + \__codedoc_names_parse: + \__codedoc_macro_save_names: + \__codedoc_names_typeset: + \__codedoc_macro_dump: + \__codedoc_macro_reset: + } +\cs_new_protected:Npn \__codedoc_macro_init: + { + \int_incr:N \l__codedoc_nested_macro_int + \bool_set_false:N \l__codedoc_macro_internal_bool + \bool_set_false:N \l__codedoc_macro_internal_set_bool + \bool_set_false:N \l__codedoc_macro_TF_bool + \bool_set_false:N \l__codedoc_macro_pTF_bool + \bool_set_false:N \l__codedoc_macro_noTF_bool + \bool_set_false:N \l__codedoc_macro_EXP_bool + \bool_set_false:N \l__codedoc_macro_rEXP_bool + \bool_set_false:N \l__codedoc_macro_var_bool + \bool_set_false:N \l__codedoc_macro_tested_bool + \bool_set_false:N \l__codedoc_names_verb_bool + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + \tl_clear:N \l__codedoc_macro_documented_tl + \cs_set_eq:NN \testfile \__codedoc_print_testfile:n + \box_clear:N \l__codedoc_macro_index_box + \vbox_set:Nn \l__codedoc_macro_box + { + \hbox:n + { + \strut + \int_compare:nNnT \l__codedoc_macro_int = 0 + { \HD@target } + } + \vskip \int_eval:n { \l__codedoc_macro_int - 1 } \baselineskip + } + } +\cs_new_protected:Npn \__codedoc_macro_reset: + { + \tl_set:Nn \l__codedoc_override_module_tl { \q_no_value } + } +\cs_new_protected:Npn \__codedoc_macro_save_names: + { + \tl_if_empty:NTF \l__codedoc_macro_documented_tl + { \__codedoc_names_block_base_map:N \__codedoc_macro_save_names_aux:n } + { + \seq_gput_right:Nf \g__codedoc_nested_names_seq + { \exp_after:wN \token_to_str:N \l__codedoc_macro_documented_tl } + } + } +\cs_new_protected:Npn \__codedoc_macro_save_names_aux:n #1 + { \seq_gput_right:Nn \g__codedoc_nested_names_seq {#1} } +\cs_new_protected:Npn \__codedoc_macro_dump: + { + \topsep\MacroTopsep + \trivlist + \cs_set:Npn \makelabel ##1 + { + \llap + { + \hbox_unpack_clear:N \l__codedoc_macro_index_box + \vtop to \baselineskip + { + \vbox_unpack_clear:N \l__codedoc_macro_box + \vss + } + } + } + \item [ ] + } +\cs_new_protected:Npn \__codedoc_macro_typeset_block:nN #1#2 + { + \__codedoc_macro_single:nNN {#1} \c_true_bool #2 + \seq_if_empty:NF \g__codedoc_variants_seq + { + \__codedoc_macro_typeset_variant_list:xN + { \__codedoc_get_function_name:n {#1} } #2 + } + } +\cs_generate_variant:Nn \__codedoc_macro_typeset_block:nN { x } +\cs_new_protected:Npn \__codedoc_macro_typeset_variant_list:nN #1#2 + { + \seq_map_inline:Nn \g__codedoc_variants_seq + { \__codedoc_macro_single:nNN { #1 : ##1 } \c_false_bool #2 } + } +\cs_generate_variant:Nn \__codedoc_macro_typeset_variant_list:nN { x } +\cs_new_protected:Npn \__codedoc_macro_single:nNN #1#2#3 + { + \tl_set:Nn \saved@macroname {#1} + \__codedoc_macro_typeset_one:nN {#1} #3 + \bool_if:NT #3 { \DoNotIndex {#1} } + \exp_args:Nx \__codedoc_macro_index:nN + { #1 \bool_if:NT #3 { \tl_to_str:n { TF } } } + #2 + } +\cs_new_protected:Npn \__codedoc_macro_index:nN #1#2 + { + \DoNotIndex {#1} + \bool_if:NT #2 + { + \__codedoc_if_macro_internal:nF {#1} + { \seq_gput_right:Nn \g_doc_macros_seq {#1} } + \hbox_set:Nw \l__codedoc_macro_index_box + \hbox_unpack_clear:N \l__codedoc_macro_index_box + \int_gincr:N \c@CodelineNo + \__codedoc_special_index:nn {#1} { main } + \int_gdecr:N \c@CodelineNo + \exp_args:NNNo \hbox_set_end: + \tl_set:Nn \saved@indexname { \l__codedoc_index_key_tl } + } + } +\cs_new_protected:Npn \__codedoc_macro_typeset_one:nN #1#2 + { + \vbox_set:Nn \l__codedoc_macro_box + { + \vbox_unpack_clear:N \l__codedoc_macro_box + \hbox { \llap { \__codedoc_print_macroname:nN {#1} #2 \ } } + } + \int_incr:N \l__codedoc_macro_int + } +\cs_new_protected:Npn \__codedoc_print_macroname:nN #1#2 + { + \strut + \__codedoc_get_hyper_target:xN + { + \exp_not:n {#1} + \bool_if:NT #2 { \tl_to_str:n {TF} } + } + \l__codedoc_tmpa_tl + \cs_if_exist:cTF { r@ \l__codedoc_tmpa_tl } + { \exp_last_unbraced:NNo \hyperref [ \l__codedoc_tmpa_tl ] } + { \use:n } + { + \int_compare:nTF { \str_count:n {#1} <= 28 } + { \MacroFont } { \MacroLongFont } + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \tl_replace_all:Nno \l__codedoc_tmpa_tl + { ~ } { \c_catcode_other_space_tl } + \__codedoc_macroname_prefix:o \l__codedoc_tmpa_tl + \__codedoc_macroname_suffix:N #2 + } + } +\cs_new_protected:Npn \__codedoc_macroname_prefix:n #1 + { + \__codedoc_if_macro_internal:nTF {#1} + { \__codedoc_typeset_aux:n {#1} } {#1} + } +\cs_generate_variant:Nn \__codedoc_macroname_prefix:n { o } +\cs_new_protected:Npn \__codedoc_macroname_suffix:N #1 + { \bool_if:NTF #1 { \__codedoc_typeset_TF: } { } } +\providecommand \MacroLongFont + { + \fontfamily{lmtt}\fontseries{lc}\small + } +\cs_new_protected:Npn \__codedoc_print_testfile:n #1 + { + \bool_set_true:N \l__codedoc_macro_tested_bool + \tl_if_eq:nnF {#1} {*} + { + \seq_if_in:NnF \g__codedoc_testfiles_seq {#1} + { + \seq_gput_right:Nn \g__codedoc_testfiles_seq {#1} + \par + \__codedoc_print_testfile_aux:n {#1} + } + } + } +\cs_new_protected:Npn \__codedoc_print_testfile_aux:n #1 + { + \footnotesize + ( + \textit + { + The~ test~ suite~ for~ this~ command,~ + and~ others~ in~ this~ file,~ is~ \textsf{#1} + }. + )\par + } +\DeclareDocumentCommand \TestFiles {m} + { + \par + \textit + { + The~ following~ test~ files~ are~ + used~ for~ this~ code:~ \textsf{#1}. + } + \par \ignorespaces + } +\DeclareDocumentCommand \UnitTested { } { \testfile* } +\DeclareDocumentCommand \TestMissing { m } + { \__codedoc_test_missing:n {#1} } +\cs_new_protected:Npn \__codedoc_test_missing:n #1 + { + \__codedoc_test_missing_aux:Nxn + \g__codedoc_missing_tests_prop + { \seq_use:Nn \l__codedoc_names_seq { , } } + { { \g_file_curr_name_str \iow_char:N \ (#1) } } + } +\cs_new_protected:Npn \__codedoc_test_missing_aux:Nnn #1#2#3 + { + \prop_get:NnNTF #1 {#2} \l__codedoc_tmpa_tl + { \tl_put_right:Nn \l__codedoc_tmpa_tl { , #3 } } + { \tl_set:Nn \l__codedoc_tmpa_tl {#3} } + \prop_put:Nno #1 {#2} \l__codedoc_tmpa_tl + } +\cs_generate_variant:Nn \__codedoc_test_missing_aux:Nnn { Nx } +\cs_new_protected:Npn \__codedoc_macro_end: + { + \endtrivlist + \__codedoc_macro_end_check_tested: + \int_compare:nNnT \l__codedoc_nested_macro_int = 1 + { \__codedoc_macro_end_style:n { \__codedoc_print_end_definition: } } + } +\cs_new_protected:Npn \__codedoc_macro_end_check_tested: + { + \bool_lazy_all:nT + { + { \g__codedoc_checktest_bool } + { ! \l__codedoc_macro_var_bool } + { ! \l__codedoc_macro_tested_bool } + } + { + \seq_set_filter:NNn \l__codedoc_tmpa_seq \l__codedoc_names_seq + { ! \__codedoc_if_macro_internal_p:n {##1} } + \seq_gput_right:Nx \g__codedoc_not_tested_seq + { + \seq_use:Nn \l__codedoc_tmpa_seq { , } + \bool_if:NTF \l__codedoc_macro_pTF_bool {~(pTF)} + { \bool_if:NT \l__codedoc_macro_TF_bool {~(TF)} } + } + } + } +\cs_new_protected:Npn \__codedoc_macro_end_style:n #1 + { + \nobreak \noindent + { \footnotesize ( \emph{#1} ) \par } + } +\cs_new_protected:Npn \__codedoc_macro_end_wrap_item:n #1 + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \tl_replace_all:Non \l__codedoc_tmpa_tl + { \token_to_str:N _ } { \_ } + \texttt { \l__codedoc_tmpa_tl } + } +\cs_new_protected:Npn \__codedoc_print_end_definition: + { + \seq_set_map:NNn \l__codedoc_tmpa_seq + \g__codedoc_nested_names_seq + { \exp_not:n { \__codedoc_macro_end_wrap_item:n {##1} } } + End~ definition~ for~ + \int_compare:nTF { \seq_count:N \l__codedoc_tmpa_seq <= 3 } + { + \seq_use:Nnnn \l__codedoc_tmpa_seq + { \,~and~ } { \,,~ } { \,,~and~ } + } + { \seq_item:Nn \l__codedoc_tmpa_seq {1}\,~and~others } + \@. + \__codedoc_print_documented: + } +\cs_new_protected:Npn \__codedoc_print_documented: + { + \seq_gset_filter:NNn \g__codedoc_nested_names_seq + \g__codedoc_nested_names_seq + { ! \__codedoc_if_macro_internal_p:n {##1} } + \seq_if_empty:NF \g__codedoc_nested_names_seq + { + \int_set:Nn \l__codedoc_tmpa_int + { \seq_count:N \g__codedoc_nested_names_seq } + \int_compare:nNnTF \l__codedoc_tmpa_int = 1 {~This~} {~These~} + \bool_if:NTF \l__codedoc_macro_var_bool {variable} {function} + \int_compare:nNnTF \l__codedoc_tmpa_int = 1 {~is~} {s~are~} + documented~on~page~ + \__codedoc_get_hyper_target:xN + { \seq_item:Nn \g__codedoc_nested_names_seq { 1 } } + \l__codedoc_tmpa_tl + \exp_args:Nx \pageref { \l__codedoc_tmpa_tl } . + } + \seq_gclear:N \g__codedoc_nested_names_seq + } +\newcommand*{\DescribeOption} + { + \leavevmode + \@bsphack + \begingroup + \MakePrivateLetters + \Describe@Option + } +\newcommand*{\Describe@Option}[1] + { + \endgroup + \marginpar{ + \raggedleft + \PrintDescribeEnv{#1} + } + \SpecialOptionIndex{#1} + \@esphack + \ignorespaces + } +\newcommand*{\SpecialOptionIndex}[1] + { + \@bsphack + \begingroup + \HD@target + \let\HDorg@encapchar\encapchar + \edef\encapchar usage + { + \HDorg@encapchar hdclindex{\the\c@HD@hypercount}{usage} + } + \index + { + #1\actualchar{\protect\ttfamily#1}~(option) + \encapchar usage + } + \index + { + options:\levelchar#1\actualchar{\protect\ttfamily#1} + \encapchar usage + } + \endgroup + \@esphack + } +\font \manual = manfnt \scan_stop: +\cs_gset:Npn \dbend { {\manual\char127} } +\newenvironment {danger} + { + \begin{trivlist}\item[]\noindent + \begingroup\hangindent=2pc\hangafter=-2 + \cs_set:Npn \par{\endgraf\endgroup} + \hbox to0pt{\hskip-\hangindent\dbend\hfill}\ignorespaces + } + { + \par\end{trivlist} + } +\newenvironment {ddanger} + { + \begin{trivlist}\item[]\noindent + \begingroup\hangindent=3.5pc\hangafter=-2 + \cs_set:Npn \par{\endgraf\endgroup} + \hbox to0pt{\hskip-\hangindent\dbend\kern2pt\dbend\hfill}\ignorespaces + }{ + \par\end{trivlist} + } +\newenvironment{TemplateInterfaceDescription}[1] + { + \subsection{The~object~type~`#1'} + \begingroup + \@beginparpenalty\@M + \description + \def\TemplateArgument##1##2{\item[Arg:~##1]##2\par} + \def\TemplateSemantics + { + \enddescription\endgroup + \subsubsection*{Semantics:} + } + } + { + \par\bigskip + } +\newenvironment{TemplateDescription}[2] + { + \subsection{The~template~`#2'~(object~type~#1)} + \subsubsection*{Attributes:} + \begingroup + \@beginparpenalty\@M + \description + \def\TemplateKey##1##2##3##4 + { + \item[##1~(##2)]##3% + \ifx\TemplateKey##4\TemplateKey\else + \hfill\penalty500\hbox{}\hfill Default:~##4% + \nobreak\hskip-\parfillskip\hskip0pt\relax + \fi + \par + } + \def\TemplateSemantics + { + \enddescription\endgroup + \subsubsection*{Semantics~\&~Comments:} + } + } + { \par \bigskip } +\newenvironment{InstanceDescription}[4][xxxxxxxxxxxxxxx] + { + \subsubsection{The~instance~`#3'~(template~#2/#4)} + \subsubsection*{Attribute~values:} + \begingroup + \@beginparpenalty\@M + \def\InstanceKey##1##2{\>\textbf{##1}\>##2\\} + \def\InstanceSemantics{\endtabbing\endgroup + \vskip-30pt\vskip0pt + \subsubsection*{Layout~description~\&~Comments:}} + \tabbing + xxxx\=#1\=\kill + } + { \par \bigskip } +\DeclareDocumentCommand \OnlyDescription { } + { \bool_gset_false:N \g__codedoc_typeset_implementation_bool } +\DeclareDocumentCommand \AlsoImplementation { } + { \bool_gset_true:N \g__codedoc_typeset_implementation_bool } +\DeclareDocumentCommand \StopEventually { m } + { + \bool_if:NTF \g__codedoc_typeset_implementation_bool + { + \@bsphack + \tl_gset:Nn \g__codedoc_finale_tl { #1 \check@checksum } + \init@checksum + \@esphack + } + { #1 \endinput } + } +\DeclareDocumentCommand \Finale { } + { \tl_use:N \g__codedoc_finale_tl } +\tl_new:N \g__codedoc_finale_tl +\cs_new_protected:Npn \__codedoc_input:n #1 + { + \tl_gclear:N \g__codedoc_module_name_tl + \MakePercentIgnore + \input{#1} + \MakePercentComment + } +\DeclareDocumentCommand \DocInput { m } + { + \clist_map_inline:nn {#1} + { + \clist_put_right:Nn \g_docinput_clist {##1} + \__codedoc_input:n {##1} + } + } +\DeclareDocumentCommand \DocInputAgain { } + { \clist_map_function:NN \g_docinput_clist \__codedoc_input:n } +\NewDocumentCommand \DocInclude { m } + { + \relax\clearpage + \docincludeaux + \IfFileExists{#1.fdd} + { \cs_set:Npn \currentfile{#1.fdd} } + { \cs_set:Npn \currentfile{#1.dtx} } + \int_compare:nNnTF \@auxout = \@partaux + { \@latexerr{\string\include\space cannot~be~nested}\@eha } + { \@docinclude #1 } + } +\cs_gset:Npn \@docinclude #1 + { + \clearpage + \immediate\write\@mainaux{\string\@input{#1.aux}} + \@tempswatrue + \if@partsw + \@tempswafalse + \cs_set:Npx \@tempb{#1} + \@for\@tempa:=\@partlist\do + { + \ifx\@tempa\@tempb\@tempswatrue\fi + } + \fi + \if@tempswa + \cs_set_eq:NN \@auxout \@partaux + \immediate\openout\@partaux #1.aux + \immediate\write\@partaux{\relax} + \cs_set_eq:NN \@ltxdoc@PrintIndex \PrintIndex + \cs_set_eq:NN \PrintIndex \relax + \cs_set_eq:NN \@ltxdoc@PrintChanges \PrintChanges + \cs_set_eq:NN \PrintChanges \relax + \cs_set_eq:NN \@ltxdoc@theglossary \theglossary + \cs_set_eq:NN \@ltxdoc@endtheglossary \endtheglossary + \part{\currentfile} + { + \cs_set_eq:NN \ttfamily\relax + \cs_gset:Npx \filekey + { \filekey, \thepart = { \ttfamily \currentfile } } + } + \DocInput{\currentfile} + \cs_set_eq:NN \PrintIndex \@ltxdoc@PrintIndex + \cs_set_eq:NN \PrintChanges \@ltxdoc@PrintChanges + \cs_set_eq:NN \theglossary \@ltxdoc@theglossary + \cs_set_eq:NN \endtheglossary \@ltxdoc@endtheglossary + \clearpage + \@writeckpt{#1} + \immediate \closeout \@partaux + \else + \@nameuse{cp@#1} + \fi + \cs_set_eq:NN \@auxout \@mainaux + } +\cs_gset:Npn \codeline@wrindex #1 + { + \immediate\write\@indexfile + { + \string\indexentry{#1} + { \filesep \int_use:N \c@CodelineNo } + } + } +\tl_gclear:N \filesep +\cs_gset:Npn \docincludeaux + { + \tl_set:Nn \thepart { \alphalph { part } } + \tl_set:Nn \filesep { \thepart - } + \cs_set_eq:NN \filekey \use_none:n + \tl_gput_right:Nn \index@prologue + { + \cs_gset:Npn \@oddfoot + { + \parbox { \textwidth } + { + \strut \footnotesize + \raggedright { \bfseries File~Key: } ~ \filekey + } + } + \cs_set_eq:NN \@evenfoot \@oddfoot + } + \cs_gset_eq:NN \docincludeaux \relax + \cs_gset:Npn \@oddfoot + { + \cs_if_exist:cTF { ver @ \currentfile } + { File~\thepart :~{\ttfamily\currentfile}~ } + { + \GetFileInfo{\currentfile} + File~\thepart :~{\ttfamily\filename}~ + Date:~\ExplFileDate\ % space + Version~\ExplFileVersion + } + \hfill \thepage + } + \cs_set_eq:NN \@evenfoot \@oddfoot + } +\group_begin: + \char_set_catcode_other:N \^^A + \char_set_catcode_active:N \^^S + \char_set_catcode_active:N \^^B + \char_set_catcode_other:N \^^L + \char_set_catcode_other:N \^^R + \char_set_lccode:nn { `\^^A } { `\% } + \char_set_lccode:nn { `\^^S } { `\ } + \char_set_lccode:nn { `\^^B } { `\\ } + \char_set_lccode:nn { `\^^L } { `\{ } + \char_set_lccode:nn { `\^^R } { `\} } + \tex_lowercase:D + { + \group_end: + \cs_set_protected:Npn \xmacro@code + #1 ^^A ^^S^^S^^S^^S ^^Bend ^^Lmacrocode^^R + { \__codedoc_xmacro_code:n {#1} \end{macrocode} } + } +\group_begin: + \char_set_catcode_active:N \< + \char_set_catcode_active:N \> + \cs_new_protected:Npn \__codedoc_xmacro_code:n #1 + { + \tl_if_in:nnTF {#1} { < @ @ = } + { \__codedoc_xmacro_code:w #1 \q_stop } + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \__codedoc_replace_at_at:N \l__codedoc_tmpa_tl + \tl_use:N \l__codedoc_tmpa_tl + } + } + \cs_new_protected:Npn \__codedoc_xmacro_code:w #1 < @ @ = #2 > #3 \q_stop + { + \tl_set:Nn \l__codedoc_tmpa_tl {#1} + \__codedoc_replace_at_at:N \l__codedoc_tmpa_tl + + \tl_gset:Nn \g__codedoc_module_name_tl {#2} + \tl_put_right:Nn \l__codedoc_tmpa_tl { < @ @ = #2 > } + + \tl_set:Nn \l__codedoc_tmpb_tl {#3} + \__codedoc_replace_at_at:N \l__codedoc_tmpb_tl + \tl_put_right:No \l__codedoc_tmpa_tl { \l__codedoc_tmpb_tl } + + \tl_use:N \l__codedoc_tmpa_tl + } +\group_end: +\iow_new:N \g__codedoc_func_iow +\tl_new:N \l__codedoc_doc_def_tl +\tl_new:N \l__codedoc_doc_undef_tl +\tl_new:N \l__codedoc_undoc_def_tl +\cs_new_protected:Npn \__codedoc_show_functions_defined: + { + \bool_lazy_and:nnT + { \g__codedoc_typeset_implementation_bool } { \g__codedoc_checkfunc_bool } + { + \iow_term:x { \c__codedoc_iow_separator_tl \iow_newline: } + \iow_open:Nn \g__codedoc_func_iow { \c_sys_jobname_str .cmds } + + \tl_clear:N \l__codedoc_doc_def_tl + \tl_clear:N \l__codedoc_doc_undef_tl + \tl_clear:N \l__codedoc_undoc_def_tl + \seq_map_inline:Nn \g_doc_functions_seq + { + \seq_if_in:NnTF \g_doc_macros_seq {##1} + { + \tl_put_right:Nx \l__codedoc_doc_def_tl + { ##1 \iow_newline: } + \iow_now:Nn \g__codedoc_func_iow { > ~ ##1 } + } + { + \tl_put_right:Nx \l__codedoc_doc_undef_tl + { ##1 \iow_newline: } + \iow_now:Nn \g__codedoc_func_iow { ! ~ ##1 } + } + } + \seq_map_inline:Nn \g_doc_macros_seq + { + \seq_if_in:NnF \g_doc_functions_seq {##1} + { + \tl_put_right:Nx \l__codedoc_undoc_def_tl + { ##1 \iow_newline: } + \iow_now:Nn \g__codedoc_func_iow { ? ~ ##1 } + } + } + \__codedoc_functions_typeout:nN + { + Functions~both~documented~and~defined: \iow_newline: + (In~order~of~being~documented) + } + \l__codedoc_doc_def_tl + \__codedoc_functions_typeout:nN + { Functions~documented~but~not~defined: } + \l__codedoc_doc_undef_tl + \__codedoc_functions_typeout:nN + { Functions~defined~but~not~documented: } + \l__codedoc_undoc_def_tl + + \iow_close:N \g__codedoc_func_iow + \iow_term:x { \c__codedoc_iow_separator_tl } + } + } +\AtEndDocument { \__codedoc_show_functions_defined: } +\cs_new_protected:Npn \__codedoc_functions_typeout:nN #1#2 + { + \tl_if_empty:NF #2 + { + \typeout + { + \c__codedoc_iow_midrule_tl \iow_newline: + #1 \iow_newline: + \c__codedoc_iow_midrule_tl \iow_newline: + #2 + } + \tl_clear:N #2 + } + } +\cs_new_protected:Npn \__codedoc_show_not_tested: + { + \bool_if:NT \g__codedoc_checktest_bool + { + \tl_clear:N \l__codedoc_tmpa_tl + \prop_if_empty:NF \g__codedoc_missing_tests_prop + { + \cs_set:Npn \__codedoc_tmpa:w ##1##2 + { + \iow_newline: + \space\space\space\space \exp_not:n {##1} + \clist_map_function:nN {##2} \__codedoc_tmpb:w + } + \cs_set:Npn \__codedoc_tmpb:w ##1 + { + \iow_newline: + \space\space\space\space\space\space * ~ ##1 + } + \tl_put_right:Nx \l__codedoc_tmpa_tl + { + \iow_newline: \iow_newline: + The~ following~ macro(s)~ have~ incomplete~ tests: + \iow_newline: + \prop_map_function:NN + \g__codedoc_missing_tests_prop \__codedoc_tmpa:w + } + } + \seq_if_empty:NF \g__codedoc_not_tested_seq + { + \cs_set:Npn \__codedoc_tmpa:w ##1 + { \clist_map_function:nN {##1} \__codedoc_tmpb:w } + \cs_set:Npn \__codedoc_tmpb:w ##1 + { + \iow_newline: + \space\space\space\space ##1 + } + \tl_put_right:Nx \l__codedoc_tmpa_tl + { + \iow_newline: + \iow_newline: + The~ following~ macro(s)~ do~ not~ have~ any~ tests: + \iow_newline: + \seq_map_function:NN + \g__codedoc_not_tested_seq \__codedoc_tmpa:w + } + } + \tl_if_empty:NF \l__codedoc_tmpa_tl + { + \int_set:Nn \l__codedoc_tmpa_int { \etex_interactionmode:D } + \errorstopmode + \ClassError { l3doc-TUB } { \l__codedoc_tmpa_tl } { } + \int_set:Nn \etex_interactionmode:D { \l__codedoc_tmpa_int } + } + } + } +\AtEndDocument { \__codedoc_show_not_tested: } +\g@addto@macro \theindex { \MakePrivateLetters } +\cs_gset:Npn \verbatimchar {&} +\setcounter { IndexColumns } { 2 } +\IndexPrologue + { + \section*{Index} + \markboth{Index}{Index} + \addcontentsline{toc}{section}{Index} + The~italic~numbers~denote~the~pages~where~the~ + corresponding~entry~is~described,~ + numbers~underlined~point~to~the~definition,~ + all~others~indicate~the~places~where~it~is~used. + } +\cs_gset_protected:Npn \SpecialIndex #1 + { + \@bsphack + \__codedoc_special_index:nn {#1} { } + \@esphack + } +\msg_new:nnn { l3doc-TUB } { print-index-howto } + { + Generate~the~index~by~executing\\ + \iow_indent:n + { makeindex~-s~gind.ist~-o~\c_sys_jobname_str.ind~\c_sys_jobname_str.idx } + } +\tl_gput_right:Nn \PrintIndex + { \AtEndDocument { \msg_info:nn { l3doc-TUB } { print-index-howto } } } +\cs_gset_protected:Npn \it@is@a #1 + { + \use:x + { + \__codedoc_special_index_module:nnnnN + {#1} + { \bslash #1 } + { } + { } + \c_false_bool + } + } +\cs_new_protected:Npn \__codedoc_special_index:nn #1#2 + { + \__codedoc_key_get:n {#1} + \quark_if_no_value:NF \l__codedoc_override_module_tl + { \tl_set_eq:NN \l__codedoc_index_module_tl \l__codedoc_override_module_tl } + \__codedoc_special_index_module:ooonN + { \l__codedoc_index_key_tl } + { \l__codedoc_index_macro_tl } + { \l__codedoc_index_module_tl } + {#2} + \l__codedoc_index_internal_bool + } +\cs_generate_variant:Nn \__codedoc_special_index:nn { o } +\tl_new:N \l__codedoc_index_escaped_macro_tl +\tl_new:N \l__codedoc_index_escaped_key_tl +\cs_new_protected:Npn \__codedoc_special_index_module:nnnnN #1#2#3#4#5 + { + \use:x + { + \exp_not:n { \__codedoc_special_index_aux:nnnnnn {#1} {#2} } + \tl_if_empty:nTF {#3} + { { } { } { } } + { + \str_if_eq:eeTF {#3} { TeX } + { + { TeX~and~LaTeX2e } + { \string\TeX{}~and~\string\LaTeXe{} } + } + { + {#3} + { \string\pkg{#3} } + } + { \bool_if:NT #5 { ~internal } ~commands: } + } + } + {#4} + } +\cs_generate_variant:Nn \__codedoc_special_index_module:nnnnN { ooo } +\cs_new_protected:Npn \__codedoc_special_index_aux:nnnnnn #1#2#3#4#5#6 + { + \tl_set:Nn \l__codedoc_index_escaped_key_tl {#1} + \__codedoc_quote_special_char:N \l__codedoc_index_escaped_key_tl + \__codedoc_special_index_set:Nn \l__codedoc_index_escaped_macro_tl {#2} + \str_if_eq:onTF { \@currenvir } { macrocode } + { \codeline@wrindex } + { + \str_case:nnF {#6} + { + { main } { \codeline@wrindex } + { usage } { \index } + } + { \HD@target \index } + } + { + \tl_if_empty:nF { #3 #4 #5 } + { #3 #5 \actualchar #4 #5 \levelchar } + \l__codedoc_index_escaped_key_tl + \actualchar + { + \token_to_str:N \verbatim@font \c_space_tl + \l__codedoc_index_escaped_macro_tl + } + \encapchar + hdclindex{\the\c@HD@hypercount}{#6} + } + } +\cs_new_protected:Npn \__codedoc_special_index_set:Nn #1#2 + { + \tl_set:Nx #1 { \tl_to_str:n {#2} } + \__codedoc_if_almost_str:nTF {#2} + { + \tl_replace_all:Non #1 { \tl_to_str:n { __ } } + { + \verbatimchar + \token_to_str:N \_ \token_to_str:N \_ + \token_to_str:N \verb * \verbatimchar + } + \exp_args:Nx \tl_map_inline:nn + { \tl_to_str:N \verbatimchar \token_to_str:N _ } + { + \tl_replace_all:Nnn #1 {##1} + { + \verbatimchar \c__codedoc_backslash_tl ##1 + \token_to_str:N \verb * \verbatimchar + } + } + \tl_set:Nx #1 + { + \token_to_str:N \verb * \verbatimchar + #1 \verbatimchar + } + } + { + \tl_set:Nn #1 {#2} + \tl_replace_all:Non #1 + { \c__codedoc_backslash_tl } + { \token_to_str:N \bslash \c_space_tl } + } + \__codedoc_quote_special_char:N #1 + } +\cs_new_protected:Npn \__codedoc_quote_special_char:N #1 + { + \tl_map_inline:nn { \quotechar \actualchar \encapchar \levelchar } + { + \tl_replace_all:Nxn #1 + { \tl_to_str:N ##1 } { \quotechar \tl_to_str:N ##1 } + } + } +\cs_new_protected:Npn \__codedoc_key_get:n #1 + { + \__codedoc_key_get_base:nN {#1} \l__codedoc_index_macro_tl + \tl_set:Nx \l__codedoc_index_key_tl + { \tl_to_str:N \l__codedoc_index_macro_tl } + \tl_clear:N \l__codedoc_index_module_tl + \tl_if_in:NoTF \l__codedoc_index_key_tl { \tl_to_str:n { __ } } + { \bool_set_true:N \l__codedoc_index_internal_bool } + { \bool_set_false:N \l__codedoc_index_internal_bool } + \tl_if_head_eq_charcode:oNT + { \l__codedoc_index_key_tl } \c__codedoc_backslash_token + { \__codedoc_key_pop: } + \tl_if_in:NoTF \l__codedoc_index_key_tl { \token_to_str:N : } + { \__codedoc_key_func: } + { + \tl_if_in:NoTF \l__codedoc_index_key_tl { \token_to_str:N _ } + { \__codedoc_key_var: } + { + \tl_if_in:NoT \l__codedoc_index_key_tl { \token_to_str:N @ } + { \tl_set:Nn \l__codedoc_index_module_tl { TeX } } + } + } + } +\cs_new_protected:Npn \__codedoc_key_pop: + { + \tl_set:Nx \l__codedoc_index_key_tl + { \tl_tail:N \l__codedoc_index_key_tl } + } +\cs_new_protected:Npn \__codedoc_key_trim_module:n #1 + { + \cs_set:Npn \__codedoc_tmpa:w ##1 #1 ##2 \q_stop + { \exp_not:n {##1} } + \tl_set:Nx \l__codedoc_index_module_tl + { \exp_after:wN \__codedoc_tmpa:w \l__codedoc_index_module_tl #1 \q_stop } + } +\cs_new_protected:Npn \__codedoc_key_drop_underscores: + { + \tl_if_head_eq_charcode:oNT { \l__codedoc_index_key_tl } _ + { \__codedoc_key_pop: \__codedoc_key_drop_underscores: } + } +\cs_new_protected:Npn \__codedoc_key_func: + { + \tl_if_head_eq_charcode:oNT { \l__codedoc_index_key_tl } . + { \__codedoc_key_pop: } + \__codedoc_key_drop_underscores: + \tl_set_eq:NN \l__codedoc_index_module_tl \l__codedoc_index_key_tl + \exp_args:No \__codedoc_key_trim_module:n { \token_to_str:N : } + \exp_args:No \__codedoc_key_trim_module:n { \token_to_str:N _ } + } +\cs_new_protected:Npn \__codedoc_key_var: + { + \exp_args:Nx \tl_if_head_eq_charcode:nNTF + { \exp_args:No \str_tail:n \l__codedoc_index_key_tl } _ + { + \str_case:fn { \str_head:N \l__codedoc_index_key_tl } + { + { q } { \tl_set:Nn \l__codedoc_index_module_tl { quark } } + { s } { \tl_set:Nn \l__codedoc_index_module_tl { quark } } + } + \__codedoc_key_pop: + \__codedoc_key_pop: + \__codedoc_key_drop_underscores: + \tl_if_empty:NT \l__codedoc_index_module_tl + { + \seq_set_split:NoV \l__codedoc_tmpa_seq + { \token_to_str:N _ } \l__codedoc_index_key_tl + \tl_set:Nx \l__codedoc_index_module_tl + { + \int_case:nnF { \seq_count:N \l__codedoc_tmpa_seq } + { + { 0 } { } + { 1 } { int } + { 2 } { \seq_item:Nn \l__codedoc_tmpa_seq { 2 } } + } + { \seq_item:Nn \l__codedoc_tmpa_seq { 1 } } + } + } + } + { + \tl_set_eq:NN \l__codedoc_index_module_tl \l__codedoc_index_key_tl + \exp_args:No \__codedoc_key_trim_module:n { \token_to_str:N _ } + } + } +\GlossaryPrologue + { + \part*{Change~History} + {\GlossaryParms\ttfamily\hyphenchar\font=`\-} + \markboth{Change~History}{Change~History} + \addcontentsline{toc}{part}{Change~History} + } +\msg_new:nnn { l3doc-TUB } { print-changes-howto } + { + Generate~the~change~list~by~executing\\ + \iow_indent:n + { makeindex~-s~gglo.ist~-o~\c_sys_jobname_str.gls~\c_sys_jobname_str.glo } + } +\tl_gput_right:Nn \PrintChanges + { \AtEndDocument { \msg_info:nn { l3doc-TUB } { print-changes-howto } } } +\bool_if:NTF \g__codedoc_typeset_implementation_bool + { + \RecordChanges + \CodelineIndex + \EnableCrossrefs + \AlsoImplementation + } + { + \CodelineNumbered + \DisableCrossrefs + \OnlyDescription + } + +%%FMi + +\def\maketitle{\@ifstar + {\@articletitlefalse\@r@maketitle}% + {\@articletitletrue\@r@maketitle}% +} + +%% +%% +%% End of file `l3doc-TUB.cls'. diff --git a/Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.dtx b/Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.dtx new file mode 100644 index 00000000000..01903de287e --- /dev/null +++ b/Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.dtx @@ -0,0 +1,1350 @@ +% \iffalse meta-comment +% +%% File: fewerfloatpages.dtx (C) Copyright 2019-2020 Frank Mittelbach +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% https://www.latex-project.org/lppl.txt +% +% The development version of the bundle can be found below +% +% https://github.com/FrankMittelbach/fmitex/ +% +% for those people who are interested or want to report an issue. +% + +\def\fewerfloatpagesdate {2020/02/14} +\def\fewerfloatpagesversion{v1.0a} + + +%<*driver> +\documentclass + [final] + {l3doc-TUB} +\hfuzz=1.6pt % not even one tt character, don't worry. + +\makeatletter + \@mparswitchfalse +\makeatother + +\setcounter{page}{1} + +\newcommand\ctr[1]{\texttt{\upshape#1}} +\newcommand\option[1]{\texttt{\upshape#1}} +\newcommand\mnote[1]{\marginpar{\raggedleft\em #1}} + +\usepackage{csquotes} +\EnableCrossrefs +\CodelineIndex + + +\begin{document} + \DocInput{fewerfloatpages.dtx} +\addtolength\signaturewidth{42pt} +\makesignature +\end{document} +%</driver> +% +% \fi +% +% +% \title{The \texttt{fewerfloatpages} package\thanks{The current +% package version is \texttt{\fewerfloatpagesversion} dated +% \fewerfloatpagesdate.}} +% \author{Frank Mittelbach} +% \address{Mainz, Germany} +% \netaddress{https://www.latex-project.org} +% \personalURL{https://ctan.org/pkg/fewerfloatpages} +% +% \maketitle +% +% +% \begin{abstract} +% +% \LaTeX{}'s float algorithm has the tendency to produce fairly +% empty float pages, i.e., pages containing only floats but with a +% lot of free space remaining that could easily be filled with nearby +% text. There are good reasons for this behavior; nevertheless, the +% results look unappealing and in many cases documents are +% unnecessarily enlarged. +% +% The \pkg{fewerfloatpages} package provides an extended algorithm +% that improves on this behavior without the need for manual intervention by +% the user. +% +% \end{abstract} +% +% \microtypesetup{protrusion=false} +% \tableofcontents +% \microtypesetup{protrusion=true} +% +% \DoNotIndex{\@fpmin} +% \DoNotIndex{\@testwrongwidth} +% \DoNotIndex{\@cons} +% \DoNotIndex{\@currbox} +% \DoNotIndex{\@currtype} +% \DoNotIndex{\@elt} +% \DoNotIndex{\@empty} +% \DoNotIndex{\@gobble} +% \DoNotIndex{\@ne} +% \DoNotIndex{\@next} +% \DoNotIndex{\@spaces} +% \DoNotIndex{\@tempcnta} +% \DoNotIndex{\@tempcntb} +% \DoNotIndex{\@tempdima} +% \DoNotIndex{\@tempdimb} +% \DoNotIndex{\@testtrue} +% \DoNotIndex{\@undefined} +% \DoNotIndex{\@vtryfc} +% \DoNotIndex{\@xxxii} +% \DoNotIndex{\@ztryfc} +% \DoNotIndex{\fl@trace} +% \DoNotIndex{\@bitor} +% \DoNotIndex{\NeedsTeXFormat} +% \DoNotIndex{\TeX} +% \DoNotIndex{\advance} +% \DoNotIndex{\begingroup} +% \DoNotIndex{\bx@B} +% \DoNotIndex{\bx@D} +% \DoNotIndex{\bx@I} +% \DoNotIndex{\count} +% \DoNotIndex{\def} +% \DoNotIndex{\divide} +% \DoNotIndex{\else} +% \DoNotIndex{\endgroup} +% \DoNotIndex{\fi} +% \DoNotIndex{\gdef} +% \DoNotIndex{\global} +% \DoNotIndex{\ht} +% \DoNotIndex{\if@test} +% \DoNotIndex{\if@twocolumn} +% \DoNotIndex{\ifdim} +% \DoNotIndex{\ifnum} +% \DoNotIndex{\ifodd} +% \DoNotIndex{\ifx} +% \DoNotIndex{\let} +% \DoNotIndex{\maxdimen} +% \DoNotIndex{\multiply} +% \DoNotIndex{\newcommand} +% \DoNotIndex{\newcount} +% \DoNotIndex{\newcounter} +% \DoNotIndex{\providecommand} +% \DoNotIndex{\relax} +% \DoNotIndex{\renewcommand} +% \DoNotIndex{\reserved@a} +% \DoNotIndex{\sixt@@n} +% \DoNotIndex{\space} +% \DoNotIndex{\string} +% \DoNotIndex{\the} +% \DoNotIndex{\tw@} +% \DoNotIndex{\typeout} +% \DoNotIndex{\xdef} +% \DoNotIndex{\z@} +% +% +% \section{Introduction} + +% We start by giving a quick overview of \LaTeX{}'s float algorithm +% and the problems that result from the approach used. +% +% We then look in some detail into possible alterations and +% improvements to that algorithm and discuss possible issues that +% need to be resolved. In this section we also describe all +% configuration possibilities of the extended algorithm. +% +% The final section then documents the code changes that are +% necessary to \LaTeX{} kernel macros to implement the extension. +% +% \subsection{A quick overview of \LaTeX's float algorithm} +% +% \LaTeX{}'s output routine uses a greedy algorithm to place floats +% near to their call-outs in the source document. The decision of how +% to place a float is made when the float is first encountered. If +% possible it is placed onto the current page, either in mid-text, +% on top or into the bottom area, depending on what is allowed for +% the float and how many floats are already placed into those +% areas. +% +% If the float can't be placed immediately, it goes into a defer +% list, and in order to not accumulate too many unplaced floats +% \LaTeX{} tries to empty that list whenever there is a chance. This +% chance comes after the next page break: \LaTeX{} then starts a +% special ``float page'' algorithm in which it examines the defer +% list and from it forms float pages (i.e., pages that contain only +% floats). If necessary, it generates several float pages and only +% stops if there are no floats waiting to be placed, or there are +% too few floats to form a float page, or there are only floats left +% that are for one or another reason not allowed to be placed in +% this way. +% +% Finally \LaTeX{} looks at the remaining floats and tries to place +% as many of them as possible into the top and bottom area of the +% next page. Then it continues to process further text to fill the +% text part of that page. Details on the exact behavior of the +% algorithm are discussed in \cite{fmi:floatplacement}. +% +% +% \subsection{The typical float page and its problems} +% +% \LaTeX{} considers a float page to be successfully built if its +% floats take up more than \cs{floatpagefraction} of the whole +% page. By default this parameter is set to \texttt{.5} which means +% that such float pages may end up being half empty. +% +% Many users think that this is not a good value and try to improve on +% it by enforcing a higher percentage (such as 80\%) only to find +% that this prevents \LaTeX{} in many cases from successfully +% generating any float page, with the effect that all floats are +% suddenly piling up at the end of the document. +% +% Why is this the case? In a nutshell, because a higher percentage +% makes it much more likely that a float can't be +% placed, because it is not big enough to be used on its +% own and no other nearby floats can be combined with +% it, because their combination violates some other restriction, +% e.g., together they are bigger than a page, not all of them are +% allowed to go on float pages, etc. The moment that happens this +% float prevents the placement of all later floats of the same +% class too (i.e., all figures) and disaster is ensured. In most +% cases these floats will then never get placed, because they need a +% float of the right size from a different class to appear, which +% may in theory happen but is, unfortunately, unlikely. +% +% Thus,\mnote{Tinkering with the parameter settings will usually +% produce unwanted effects} while tempting, tinkering with this +% parameter by making it larger is usually not a good idea, unless +% you are prepared to place most if not all of your floats +% manually, by overwriting the placement algorithm on the level of +% individual floats (e.g., using \texttt{!}\@ syntax and/or +% shifting its position in the source document). +% +% Why does the current algorithm have these problems? To some extent, +% because it offers only global parameters that need to fit +% different scenarios and thus settings that are suitable when many +% floats need to be placed result in sub-optimal paginations in +% document parts that contain only a few floats, and vice versa. +% To overcome this problem, either one can try to develop +% algorithms with many more configurable parameters that act +% differently in different scenarios or one can let the algorithm +% follow a main strategy, configurable with only a few parameters +% (like today), but monitor the process and make more local +% adjustments and corrections depending on the actual outcome of +% that base strategy and additional knowledge of the actual +% situation in a given document part. This is the +% approach taken by the extension implemented in this package. +% +% \section{Improvements to the float page algorithm} +% +% A simple way to improve on the existing algorithm, without +% compromising its main goal of placing the floats as fast as +% possible and as close as possible to their call-outs, is the +% following: as long as there are many floats waiting to be placed, +% generate float pages as necessary to get them placed (using the +% current algorithm and its parameters). + +% Once we are unable to build further float pages, do some level +% of backtracking by checking if we have actually succeeded in +% placing all floats. If there are still floats waiting to be +% placed then assume that what has been done so far is the best +% possible way to place as many floats as possible (which it +% probably is). However, if we have been able to place all floats +% onto float pages then check if the last float page is +% sufficiently full; if not, undo that float page and instead +% redistribute its floats into the top and bottom area of the next +% upcoming page. This way the floats will be combined with further +% text and we avoid a possible half-empty float page. +% +% This approach will not resolve all the problematic scenarios +% where we find that \LaTeX{} has decided to favor fairly empty +% float pages over some tighter type of placement. It will, +% however, help to improve typical cases that do not involve too +% many floats. For\mnote{A typical case where we don't really want +% \LaTeX{} to make a float page} a example, if a single (larger) +% float appears near the end of a page, then using the standard +% algorithm it can't be immediately placed (because there isn't +% enough free space on the current page). It is therefore moved to +% the defer list and at the page break it is then placed onto a +% float page (possibly by itself, if it is large enough to allow +% for that) even though it could perfectly well go into the top or +% bottom area of the next page and thus be combined with textual +% material on that page. +% +% With the new algorithm this float page is reexamined and unless +% it is pretty much filled up already, it is unraveled and its +% floats are redistributed into the top and bottom areas of the +% next page. If, however, we have many floats waiting on the defer +% list, the normal float page algorithm will first place as many of +% them as possible into float pages and only the last of these +% pages will be subject to a closer inspection and a possible +% unraveling. +% +% An extension of this idea (and the one that we actually +% implement) is to monitor the whole float page generation process +% and instead of just considering the last float page in the sequence +% for unraveling, we look at each prospective float page in turn and +% based on the current situation (e.g., number of floats still +% being unplaced, free space on the float page, etc.)\@ decide +% whether this float page should be produced or whether we should +% stop making float pages and instead place the pending floats into +% top and bottom areas of the upcoming page. +% +% +% \subsection{Details on the extended algorithm} +% +% The main idea of the extended algorithm is to avoid unnecessary cases of +% float pages especially if those float pages are fairly +% empty.\mnote{Don't unravel a float page if there are too many +% floats on the defer list} +% Natural candidates are single float pages, but even in cases where +% the current \LaTeX{} algorithm produces several sequential float +% pages the extended algorithm may decide to replace them by normal +% pages under certain conditions. +% However, the main goal +% is and should remain to place as many floats as soon as possible +% and so generating float pages when many floats are waiting is +% usually essential. +% +% \begin{variable}{floatpagedeferlimit} +% \begin{syntax} +% \cs{setcounter}\{floatpagedeferlimit\}\Arg{number} +% \end{syntax} +% Whether or not unraveling for a float page is considered at all +% is guided by the counter \ctr{floatpagedeferlimit}. As long as +% there are more floats waiting on the defer list than this number, +% float pages are not considered for unraveling. The default is +% \texttt{3} which corresponds to the default value for +% \ctr{totalnumber}, i.e., with that setting the unraveling of a +% floating page has a fighting chance to place all floats into the +% top and bottom areas on the current page. +% It would also resolve cases for up to three floats, each larger than +% \cs{floatpagefraction}, where the standard \LaTeX{} algorithm would +% produce three individual float pages.\strut +% \end{variable} +% +% If you set the counter to \texttt{1} then only the last float +% page in a sequence is considered, and only if it contains only a +% single float and if there are no other floats that are still +% waiting to be placed. If you set it to \texttt{0}, then the +% extension is disabled, because float pages are produced only if +% there was at least one float on the defer list. +% +% Even\mnote{Don't unravel if the float page contains many floats} +% if we set \ctr{floatpagedeferlimit} to a fairly high value, we +% may not want to unravel float pages that contain many floats. To +% support this case there is a second counter that guides the +% algorithm in this respect. +% +% \begin{variable}{floatpagekeeplimit} +% \begin{syntax} +% \cs{setcounter}\{floatpagekeeplimit\}\Arg{number} +% \end{syntax} +% Whenever the float page contains at least +% \ctr{floatpagekeeplimit} floats it will not be unraveled. The +% default is also \texttt{3} so that float pages with three or more +% floats are not touched. Obviously the counter can have any effect +% only if it has a value less than or equal to +% \ctr{floatpagedeferlimit} because this is tested first.\strut +% \end{variable} +% +% +% There are, however, a number of other situations in which we +% shouldn't unravel a float page even if the above checks for the +% size of the defer list were passed successfully.\mnote{Don't +% unravel if the float page contains at least one \texttt{\upshape +% [p]} float} The most important one is the case when the float +% page contains at least one float that is allowed \emph{only} on +% float pages (i.e., has a \texttt{[p]} argument). Such a float +% would not be placeable in a top/bottom area on any page and thus +% would be repeatedly sent back to the defer list (possibly forever). +% +% The other case where unraveling would normally be +% counterproductive is when the particular float page is nearly or +% completely filled up with floats.\mnote{Don't unravel if the +% float page is nearly filled} If we unravel it, then it is +% certain that we can place only some of the floats into the top or +% bottom area of the next page, while some would end up on the defer +% list. That in turn means that these deferred floats float even +% further away from their call-out positions than need be. +% +% \begin{variable}{\floatpagekeepfraction} +% \begin{syntax} +% \cs{renewcommand}\cs{floatpagekeepfraction}\Arg{decimal} +% \end{syntax} +% So what is a good way to determine if a float page is ``full +% enough''? A possible answer is that if the remaining free space +% on that page is less than \cs{textfraction} we consider it full +% enough to stay. \cs{textfraction} defines the minimum amount of +% space that has to be occupied by text on a normal page, thus if +% all floats together need so much space that this amount of text +% could not fit, then trying to place all floats onto a +% normal page can't succeed and some of them would get deferred for +% sure. To allow for further flexibility the algorithm uses +% the variable \cs{floatpagekeepfraction} (defaulting to +% \cs{textfraction}) so if desired a lower (or even a higher) +% boundary can be set.\strut +% \end{variable} +% +% The above parameters give some reasonable configuration +% possibilities to guide the algorithm as to when and when not to unravel +% a possible float page and instead produce further normal pages. +% It should be noted, however, that except for the case of setting +% \ctr{floatpagedeferlimit} to \texttt{1}, there is always a chance +% that floats drift further away from their call-outs, because they +% may not be immediately placeable due to other parameter settings +% of the float algorithm. For example, the counter +% \texttt{topnumber} (default value 2) limits the number of floats +% that can be placed in the top area on a normal page and if more +% remain after unraveling only two can immediately go in this area. +% +% +% \subsection{Possible pitfalls and how to avoid them} +% +% The algorithm detects if a float is allowed only on float pages +% (i.e., is given in the source as \texttt{[p]}) and it will ensure +% that float pages containing such floats are not unraveled. +% +% However, if you have a float with the default specifier +% \texttt{[tbp]} whose size is larger than the allowed size of the +% top or bottom area (e.g., larger than \cs{topfraction} +% \texttimes{} \cs{textheight}), then this effectively means it can +% only be placed on a float page. +% +% However, according to the specifier the float is allowed to go +% into the top or bottom area, so the algorithm, as explained so +% far, would be allowed to unravel and when that float later is +% considered for top or bottom placement it will get again deferred +% and thus move from one page to the next, most likely messing up +% the whole float placement. +% +% There\mnote{\option{checktb} (option)} are two possible ways to +% improve the algorithm to avoid this disaster. One way +% would be to check the float size when it is initially encountered +% and remove any specifier that is technically not possible because +% of the parameter settings and the float size. A possible +% disadvantage is that this determination will be done once and any +% later (temporary) change to the float parameters will have no +% effect. This is currently the package default. It can be +% explicitly selected by specifying the option \option{checktb}. In +% this case you might see warnings like +%\begin{verbatim} +% LaTeX Warning: Float too large for top area: t changed to p on line ... +%\end{verbatim} +% +% Another\mnote{\option{addbang} (option)} possibility is that we automatically add a +% \texttt{!}\@ specifier to all floats during unraveling, i.e., when +% we send them back for reevaluation. This way such floats become +% placeable into top and bottom areas regardless of their size. This +% may result in fewer pages at the cost of violating the area size +% restrictions once in a while. It is specified with the option \option{addbang}. +% +% If\mnote{\option{nocheck} (option)} you prefer no automatic +% adjustment of the specifiers, add the option \option{nocheck}. +% In this case you might find that floats of certain sizes are +% unplaceable and thus get delayed to the end of the document. If +% that happens, the remedy is either to explicitly specify +% \texttt{[p]} or \texttt{[hp]} for such a float (to ensure that +% they aren't subject to unraveling) or to manually add an +% exclamation specifier, e.g., \texttt{[!tp]} so that \LaTeX{} +% doesn't use the size restrictions in its algorithm. +% +% +% +% \subsection{Tracing the algorithm} +% +% The\mnote{\option{trace} (option)} package offers the option +% \option{trace}, which if used, will result in messages such as +%\begin{verbatim} +% [1] +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@B \bx@D +% fewerfloatpages: starting with \bx@B +% fewerfloatpages: --> success: \bx@B \bx@D +% fewerfloatpages: ----- current float page unraveled +% (free space 192.50336pt > 109.99832pt) +% [2] +%\end{verbatim} +% which means that the algorithm is trying to make a float page +% from the defer list which at that point contained two floats (the +% float boxes \cs[no-index]{bx@B} and \cs[no-index]{bx@D}), that it +% was able to produce a float page containing just +% \cs[no-index]{bx@B} and \cs[no-index]{bx@D}, and that the extended +% algorithm then decided to unravel that float page, because it has +% an unused space of \texttt{192.5pt}, i.e., roughly 16 text lines. With the current +% \cs{floatpagekeepfraction} that is too much empty space on the +% page. +% +% Or it might say +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@D \bx@F \bx@G \bx@H \bx@I +% fewerfloatpages: starting with \bx@D +% fewerfloatpages: --> success: \bx@D \bx@F +% fewerfloatpages: ----- too many deferred floats for unraveling (5 > 3) +% [3] +%\end{verbatim} +% which means that the algorithm made a float page out of the first +% two floats from the defer list (i.e., 3 remained). +% That +% page was kept regardless of the amount of free space it contained +% because we have a total of 5 floats on the defer list and the +% counter \ctr{floatpagedeferlimit} has its default value of \texttt{3}. +% +% The above tracing messages are both from the same test +% document. What they also (implicitly) show is that the unraveling +% that happened after page~1 resulted in only one float (\cs[no-index]{bx@B}) +% being placed on page~2, because we see the second one (\cs[no-index]{bx@D}) +% reappearing in the defer list after page~2 got finished. In other +% words it was moved one page further away from its call-out: the +% price for getting a nicely filled page~2 instead of a fairly empty +% float page with roughly 200 points left empty. +% The final part of that test document then exhibits another +% type of message: +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@G \bx@H \bx@I +% fewerfloatpages: starting with \bx@G +% fewerfloatpages: --> success: \bx@G \bx@H \bx@I +% fewerfloatpages: ----- all floats placed on float page(s) +% fewerfloatpages: ----- current float page kept, full enough +% (free space 38.99496pt < 109.99832pt) +% [4] +%\end{verbatim} +% This means that the remaining floats (that were left unplaced +% after float page~3 got constructed) formed a float +% page and that float page was the last in sequence (i.e., all +% floats have been placed). However, this time the algorithm decided not +% to unravel it, because it is nicely full: there are only 39 points +% of free space left on that page. +% +% Three other possible messages are shown in this sequence of +% tracing lines from a second test document (which is using some uncommon +% settings: \ctr{floatpagedeferlimit} is \texttt{10} and +% \ctr{floatpagekeeplimit} is \texttt{5}): +%\begin{verbatim} +% [1] +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@B \bx@C \bx@D \bx@E \bx@F \bx@G \bx@H +% fewerfloatpages: starting with \bx@B +% fewerfloatpages: --> success: \bx@B \bx@C \bx@D \bx@E \bx@F \bx@G \bx@H +% fewerfloatpages: ----- current float page kept (contains at least 5 floats) +% [2] [3] +%\end{verbatim} +% In this case 7 floats have been waiting on the defer list and the +% algorithm was able to construct a float page using all of them. +% The algorithm then keeps that page because it has 5 or more floats +% in it (the value of the \ctr{floatpagekeeplimit} counter). +% +% The next message in that test document shows what happens +% when there are not enough floats waiting or they are simply too +% small (to even get past the \cs{floatpagefraction} limit): +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@I \bx@J +% fewerfloatpages: starting with \bx@I +% fewerfloatpages: --> fail +% fewerfloatpages: starting with \bx@J +% fewerfloatpages: --> fail +% fewerfloatpages: --> fail: no float page made +% [4] +%\end{verbatim} +% So no float page was made, but for some reason (that becomes clear +% later) the two floats also didn't got distributed into the top or +% bottom area of the next page. Instead they remained on the +% defer list and during processing of page~4 one more float was +% found so that after that page the defer list had grown to +% length~3: +% +%\begin{verbatim} +% fewerfloatpages: PAGE: trying to make a float page +% fewerfloatpages: ----- \@deferlist: \bx@I \bx@J \bx@K +% fewerfloatpages: starting with \bx@I +% fewerfloatpages: --> success: \bx@I \bx@J \bx@K +% fewerfloatpages: ----- current float page kept, contains a float +% fewerfloatpages: with p but no t or b specifier +% [5] +%\end{verbatim} +% This time all floats could be placed, but again the float page +% wasn't unraveled (even though in the test document it contained a +% lot of white space) because of the fact that one of its floats (in fact +% the first though that can only be deduced implicitly) was +% specified as a \enquote{float page only} float. This explains why +% on page~4 \cs[no-index]{bx@I} couldn't be placed into the top or bottom +% area and then all following floats of the same class (the test +% document contained only \env{figure} floats) couldn't be placed +% either. +% +% If\mnote{Detailed tracing of the complete algorithm} you want +% detailed tracing of the complete algorithm, also load the +% \pkg{fltrace} package and enable the tracing with +% \cs{tracefloats} anywhere in your document. Note, however, that +% the resulting output is very detailed but rather low-level and +% unpolished. +% +% +% +% +% +% \subsection{Local (manual) adjustments} +% +% If the extended algorithm is used you will get fewer float pages +% that contain a noticeable amount of white space. By adjusting +% \cs{floatpagekeepfraction} and the counters \ctr{floatpagekeeplimit} and +% \ctr{floatpagedeferlimit} you can direct the algorithm to unravel more or +% fewer of the otherwise generated float pages. However, in some cases +% it might happen that redistribution of the floats into the top and +% bottom areas of the next page(s) may result in some of them +% drifting too far away from their call-outs. If that happens, you can +% either try to change the general parameters or you could help the +% algorithm along by using the optional argument of individual float +% environments. +% The two main tools at your disposal are +% \begin{itemize} +% \item +% using the \texttt{[!..]} notation to allow the float to go into +% the top or bottom area even if it would be normally prevented by +% other restrictions; +% \item +% using \texttt{[p]} to force a float into a float page as that +% prevents the algorithm from unravelling the float page which contains +% that float. +% \end{itemize} +% As an alternative you can, of course, temporarily alter the +% definition of the command \cs{floatpagekeepfraction} or the values +% of two counters in mid-document, but remember that they are not +% looked at when a float is encountered in the source but when we +% are at a page break and \LaTeX{} attempts to empty the defer list, +% which is usually later and unfortunately somewhat asynchronous, +% i.e., not easy to predict. +% +% +% \StopEventually{ +% \begin{thebibliography}{1} +% \raggedright +% \bibitem{fmi:floatplacement} +% Frank Mittelbach. +% \newblock How to influence the position of float environments like figure and table in \LaTeX? +% \newblock \textsl{TUG}boat 35:3, 2014.\\ +% \newblock \url{https://www.latex-project.org/publications/indexbytopic/2e-floats/} +% \bibitem{source2e} +% \LaTeX{} Project Team. +% \newblock The \LaTeXe{} Sources (660+ pages), 2020.\\ +% \newblock \url{https://www.latex-project.org/help/documentation} +% \end{thebibliography} +% \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index +% \setlength\IndexMin{200pt} \PrintIndex +% \fi +%} +% +% +% +% \section{The implementation} +% +% We start off with the package announcement. Requiring a fairly new +% \LaTeX{} kernel is not absolutely necessary but it will help to +% ensure that we patch what we think we patch and in the future it +% means that will can be assured that the rollback functionality of +% the kernel is available in case will need to support several +% releases of the package. +% \begin{macrocode} +%<*package> +\NeedsTeXFormat{LaTeX2e}[2018-04-01] +% \end{macrocode} +% +% \begin{macrocode} +\ProvidesPackage{fewerfloatpages} + [\fewerfloatpagesdate\space \fewerfloatpagesversion\space + improve float page generation (FMi)] +% \end{macrocode} +% +% \subsection{Option handling} +% +% This release of the package has four options: \option{trace} +% for tracing the algorithm, \option{addbang} and +% \option{checktb} to handle cases where the float size in +% combination with the float specifiers makes it difficult if not +% impossible to place the floats, and \option{nocheck} to not make +% adjustments for that case. +% +% The option \option{trace} enables tracing of the algorithm and is +% implemented by giving the command \cs[no-index]{fl@trace} (which is also +% used by the \pkg{fltrace} package) a suitable definition. +% +% To handle the case that the \pkg{fltrace} package is loaded +% first, we use \cs[no-index]{providecommand}, so that its definition is not +% overwritten, but used if it is already available. If the package is +% loaded later everything works fine because it unconditionally +% defines \cs[no-index]{fl@trace}, i.e., overwrites whatever +% \pkg{fewerfloatpages} has defined. +% +% \begin{macrocode} +\DeclareOption{trace} + {\providecommand\fl@trace[1]% + {{\let\@elt\@empty\typeout{fewerfloatpages: #1}}}} +% \end{macrocode} +% +% The other three options are mutually exclusive so we number them 0 +% to 2 in the command \cs[no-index]{fp@strategy} to ensure that +% only one is ever active. Option \option{nocheck} does nothing, with +% the cost that some floats may float to the end of the +% document. Option \option{addbang} adds a \texttt{!}\@ to floats +% that are sent back for reevaluation when a float page gets +% unraveled. Option \option{checktb} implements a different +% approach to handling problematic floats: the vertical +% size of a float is checked, and if it is too large to be allowed +% into the top or the bottom area, any \texttt{t} or \texttt{b} +% specifier is replaced by \texttt{p} (or dropped if \texttt{p} is +% already specified). +% \begin{macrocode} +\def\fp@strategy{0}% +\DeclareOption{nocheck}{\def\fp@strategy{0}} % better name? +\DeclareOption{addbang}{\def\fp@strategy{1}} +\DeclareOption{checktb}{\def\fp@strategy{2}} +% \end{macrocode} +% The actual implementation is done later. The default is +% currently \option{checktb} but this may change to +% \option{addbang} based on user feedback. +% \begin{macrocode} +\ExecuteOptions{checktb} +\ProcessOptions +% \end{macrocode} +% +% +% \subsection{Tracing code} +% +% \begin{macro}[internal]{\fl@trace} +% The command \cs[no-index]{fl@trace} is used to output tracing information. +% By default the tracing of the algorithm is turned off, so +% \cs[no-index]{fl@trace} will simply swallow its argument. But if +% \pkg{fltrace} is loaded or the option \option{trace} is given +% then the command already has a definition so we don't change it +% here. +% \begin{macrocode} +\providecommand\fl@trace[1]{} +% \end{macrocode} +% \end{macro} +% +% +% \subsection{User-level interfaces} +% +% For the most part the packages provides internal code that +% extends the float algorithm of \LaTeX{}. There are, however, also +% three new parameters that guide this algorithm; they are defined +% in this section. +% +% \begin{macro}[var]{\floatpagekeepfraction} +% The fraction that the algorithm uses to decide whether a given float +% page is so full that it would be pointless to unravel it for the +% reasons outlined above. The default is whatever fraction has been +% chosen as the minimum amount of text that needs to be on a normal +% page (i.e., \cs{textfraction}). +% \begin{macrocode} +\newcommand\floatpagekeepfraction{\textfraction} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}[var]{floatpagedeferlimit,\c@floatpagedeferlimit} + +% The algorithm will only consider unraveling float pages if there +% are not too many floats on the defer list. The definition of +% \enquote{too many} is provided through the counter +% \ctr{floatpagedeferlimit} if there are more floats waiting to be +% placed; float pages are generated until their number falls below +% this level. Thus, a value of \texttt{0} will disable the whole +% algorithm and a value of \texttt{1} means that only float pages +% with a single float might get unraveled and only if there aren't +% others still waiting to be placed. +% \begin{macrocode} +\newcounter{floatpagedeferlimit} \setcounter{floatpagedeferlimit}{3} +% \end{macrocode} +% \end{macro} + + + +% \begin{macro}[var]{floatpagekeeplimit,\c@floatpagekeeplimit} +% +% A float page that contains at least this number of floats will +% also be kept. The default is \texttt{3} but if you have a lot of +% small floats it might be better to set this to a higher +% value. +% \begin{macrocode} +\newcounter{floatpagekeeplimit} \setcounter{floatpagekeeplimit}{3} +% \end{macrocode} +% \end{macro} + + + + + +% \subsection{Patching the \LaTeX{} kernel commands} +% + + +% +% \begin{macro}[internal]{\@tryfcolumn} +% The main macro we have to patch to extend \LaTeX's algorithm is +% \cs{@tryfcolumn}. That command is changed when \pkg{fltrace} +% gets loaded, so we make our definition as late as possible to +% ensure that it will survive. +% \begin{macrocode} +\AtBeginDocument{% +% \end{macrocode} +% +% \begin{macrocode} +\def \@tryfcolumn #1{% + \global \@fcolmadefalse + \ifx #1\@empty + \else + \fl@trace{PAGE: trying to make a float + \if@twocolumn column/page\else page\fi}% + \fl@trace{----- \string #1: #1}% + \xdef\@trylist{#1}% + \global \let \@failedlist \@empty + \begingroup + \let \@elt \@xtryfc \@trylist + \endgroup +% \end{macrocode} +% Up to this point the definition is the same as in the original +% algorithm. At this point the switch \cs[no-index]{if@fcolmade} tells us if making a +% float page was successful and the original algorithm then called +% \cs[no-index]{@vtryfc} and removed the floats used for this float page from the defer list. +% +% In the extended algorithm this is the place where things start to +% differ as we may not want that float page to actually come into +% existence. +% \begin{macrocode} + \if@fcolmade +% \end{macrocode} +% As a first step we count the number of floats in the defer list +% and save the result in \cs{fp@candidates}. +% \begin{macrocode} + \fp@candidates\z@ + \def\@elt##1{\advance\fp@candidates\@ne}% + #1% + \let\@elt\relax +% \end{macrocode} +% Now we compare this number with the values of the counter \ctr{floatpagedeferlimit} +% and if it is higher we definitely want to keep the float +% page. The rationale is that if we unravel now, then all floats from +% the defer list need to go into the top/bottom areas (or get +% deferred again but to a later page) and so a high number means the defer list will +% not get shortened very much and too many floats will get delayed further. +% \begin{macrocode} + \ifnum \fp@candidates >\c@floatpagedeferlimit + \fl@trace{----- too many deferred floats for unraveling + (\the\fp@candidates\space> \the\c@floatpagedeferlimit)}% + \else +% \end{macrocode} +% +% Otherwise we do a bit more testing. First we set \cs[no-index]{if@fcolmade} +% back to false; after all our goal is to not keep the float page. If +% during the tests we decide otherwise we set it back to true, which +% then signals that it should stay. +% +% We also count the floats on the float page, reusing \cs[no-index]{fp@candidates} +% for that, which is why we initialize it to zero. +% \begin{macrocode} + \global\@fcolmadefalse + \fp@candidates\z@ +% \end{macrocode} +% The actual checking is done with +% \cs{fp@analyse@floats@for@unraveling} and it loops over +% \cs{@flsucceed}, i.e., the floats for that float page. This +% checks if any float for that page has only a \texttt{[p]} +% specifier and if so it sets \cs[no-index]{if@fcolmade} back to +% \texttt{true} and as a side effect it also does the counting for +% us. Furthermore, it also changes the switch to true if it finds +% at least \ctr{floatpagekeeplimit} floats on that page. +% \begin{macrocode} + \let\@elt\fp@analyse@floats@for@unraveling + \@flsucceed + \let\@elt\relax +% \end{macrocode} +% Now we recheck the state of the switch and if it still says +% \texttt{false}, all tests so far indicate that we don't want the float +% page. +% \begin{macrocode} + \if@fcolmade \else +% \end{macrocode} +% But we aren't done yet: the float page might be nicely filled, +% in which case it would be a shame to unravel it. During the above +% loop we also measured the free space on the float page and stored +% it in \cs{fp@unused@space} (see \cs{@xtryfc} below). We now +% compare that to the maximum free space that we consider to be +% still okay and if there is more we finally do the unraveling. +% \begin{macrocode} + \@tempdima\floatpagekeepfraction\@colht + \ifdim \fp@unused@space >\@tempdima + \fl@trace{----- current float page unraveled^^J% + \@spaces\@spaces\@spaces\space\space\space + (free space \fp@unused@space\space > \the\@tempdima)}% +% \end{macrocode} +% For this we basically return all floats back to the +% defer list. The switch is still \texttt{false} so it doesn't need +% changing. +% \begin{macrocode} + \xdef #1{\@failedlist\@flsucceed\@flfail}% +% \end{macrocode} +% However, we may also want to add a \texttt{!}\@ specifier to each of +% the floats (if the \option{addbang} option was given) +% so we loop over all the floats once more to get this +% done.\footnote{This could have been integrated with +% \cs{fp@analyse@floats@for@unraveling} but there is not much gain if +% any and by keeping it separate the processing logic seems clearer to me.} +% \begin{macrocode} + \let\@elt\fp@maybe@add@bang + \@flsucceed + \let\@elt\relax + \else +% \end{macrocode} +% But if we want to keep the float page after all, we have to set +% the switch back to \texttt{true} so that the rest of the +% algorithm proceeds correctly. +% \begin{macrocode} + \global \@fcolmadetrue + \fl@trace{----- current float page kept, full enough^^J% + \@spaces\@spaces\@spaces\space\space\space + (free space \fp@unused@space\space < \the\@tempdima)}% + \fi + \fi + \fi +% \end{macrocode} +% The next \cs[no-index]{else} matches the first \cs[no-index]{if@fcolmade}, i.e., the +% case that the algorithm wasn't able to make any float page. If +% we are tracing the algorithm, we want to tell the user about this. +% \begin{macrocode} + \else + \fl@trace{ --> fail: no float page made}% + \fi +% \end{macrocode} +% +% Finally, at this point we are back in the original algorithm. Now the +% switch tells the truth about whether or not we want to make a float +% page, and if so, we go ahead and produce it. +% \begin{macrocode} + \if@fcolmade + \@vtryfc #1% + \fi + \fi}% +}% -- END of \AtBeginDocument +% \end{macrocode} +% \end{macro} +% +% \pagebreak +% +% +% \begin{macro}[internal]{\@makefcolumn} +% +% In contrast to \cs{@tryfcolumn} this macro will always make float +% pages out of the deferred floats. It is used by \cs{clearpage} +% when we really need the floats to get out because there is no further +% text coming up. Thus, in that case we should not unravel the +% float pages. That would happen with the kernel definition of +% \cs{@makefcolumn} as that calls \cs{@tryfcolumn} which we just +% changed above. We therefore modify its definition to include the +% original code for \cs{@tryfcolumn} instead of calling our updated +% version. +% +% Again this change is made at \verb=\begin{document}= so that it +% is not overwritten in case \pkg{fltrace} is loaded afterwards. +% \begin{macrocode} +\AtBeginDocument{% +\def\@makefcolumn #1{% + \begingroup + \@fpmin -\maxdimen + \let \@testfp \@gobble +% \end{macrocode} +% At this point the original definition called \cs[no-index]{@tryfcolumn} and +% the lines above ensured that it was always succeeding in making +% a float page. However, since we have changed that command to do unraveling +% we had better not use it any more. Instead we replace it by its original +% definition (with the addition of two tracing lines). +% \begin{macrocode} + \global \@fcolmadefalse + \ifx #1\@empty + \else + \fl@trace{PAGE: trying to make a float + \if@twocolumn column/page\else page\fi}% + \fl@trace{----- \string #1: #1}% + \xdef\@trylist{#1}% + \global \let \@failedlist \@empty + \begingroup + \let \@elt \@xtryfc \@trylist + \endgroup + \if@fcolmade + \@vtryfc #1% + \fi + \fi + \endgroup +}% +}% -- END of \AtBeginDocument +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\@xtryfc} +% The only change to \cs{@xtryfc} is the addition of the +% \cs[no-index]{fl@trace} calls. But this extra tracing info is generally +% useful and should also be done in the \pkg{fltrace} package. +% +% The macro initiates a float page trial starting with the first +% float in \cs{@trylist}. More detailed explanations can be found +% in the documented sources of the \LaTeX{} kernel~\cite{source2e}. +% \begin{macrocode} +\def\@xtryfc #1{% + \fl@trace{ starting with \string#1}% + \@next\reserved@a\@trylist{}{}% + \@currtype \count #1% + \divide\@currtype\@xxxii + \multiply\@currtype\@xxxii + \@bitor \@currtype \@failedlist + \@testfp #1% + \@testwrongwidth #1% + \ifdim \ht #1>\@colht + \@testtrue + \fi + \if@test + \@cons\@failedlist #1% + \fl@trace{ --> fail}% + \else + \@ytryfc #1% + \fi +}% +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% +% \begin{macro}[internal]{\@ytryfc} +% +% The command \cs{@ytryfc}, which is also part of the code in the +% kernel, loops through the defer list and tries to build a float +% page starting with the float passed to it in |#1|. If it succeeds, +% the floats that are part of the float page are listed in +% \cs{@flsucceed} and the switch \cs[no-index]{if@fcolmade} is set to +% \texttt{true}. Also of interest to us is that inside the code +% \cs[no-index]{@tempdima} holds the size taken up by the floats, so we can +% use this to calculate the unused space on the float page and +% store it in \cs{fp@unused@space} for use in our extended +% algorithm. +% \begin{macrocode} +\def\@ytryfc #1{% + \begingroup + \gdef\@flsucceed{\@elt #1}% + \global\let\@flfail\@empty + \@tempdima\ht #1% + \let\@elt\@ztryfc + \@trylist + \ifdim \@tempdima >\@fpmin + \global\@fcolmadetrue +% \end{macrocode} +% This branch is executed when the floats together are big enough +% to form a float page. Thus, this is the right place to calculate +% the free space by subtracting the used space from the column +% height (which may not be the full height if there are spanning +% floats in two column mode). +% \begin{macrocode} + \@tempdimb\@colht + \advance\@tempdimb-\@tempdima + \xdef\fp@unused@space{\the\@tempdimb}% +% \end{macrocode} +% The remaining code is again unchanged except that we added two +% additional tracing lines (though those should be added to +% the \pkg{fltrace} package too one of these days). +% \begin{macrocode} + \else + \@cons\@failedlist #1% + \fl@trace{ --> fail}% + \fi + \endgroup + \if@fcolmade + \let\@elt\@gobble + \fl@trace{ --> success: \@flsucceed}% + \fi} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\@largefloatcheck} +% +% The final kernel macro we need to patch is +% \cs{@largefloatcheck}. This is called when a float box is +% constructed and it checks if that box is larger than the available +% \cs{textheight}, which would mean it could never be placed +% anywhere, not even on a float page. The code therefore reduces +% the box size as necessary and issues a warning. +% +% This macro is therefore a natural candidate to also check if the +% float size is too large for the float to go into top or bottom +% areas (if the option \option{checktb} is used). +% \begin{macrocode} +\def \@largefloatcheck{% + \ifdim \ht\@currbox>\textheight + \@tempdima -\textheight + \advance \@tempdima \ht\@currbox + \@latex@warning {Float too large for page by \the\@tempdima}% + \ht\@currbox \textheight + \fi +% \end{macrocode} +% The \cs{fp@maybe@check@tb} does the checking (or nothing if the +% option is not given). +% \begin{macrocode} + \fp@maybe@check@tb +} +% \end{macrocode} +% \end{macro} +% +% +% +% +% +% \subsection{Internal helper commands and parameters} +% +% +% \begin{macro}[internal]{\fp@candidates} +% We use an internal counter to count the number of floats in the +% defer list and on a float page under construction. +% \begin{macrocode} +\newcount\fp@candidates +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}[internal]{\fp@unused@space} +% In \cs{fp@unused@space} we store the amount of free space +% on the current float page. +% \begin{macrocode} +\def\fp@unused@space{} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}[internal]{\fp@analyse@floats@for@unraveling} +% With \cs{fp@analyse@floats@for@unraveling} we loop over the +% floats on the float page, i.e., |#1| will be one such float. +% +% One of its tasks is to count the floats (in \cs{fp@candidates}) and +% check if +% there are at least \ctr{floatpagekeeplimit} of them (which means +% the float page should definitely be kept). +% +% Its most important task, however, is to check if one of the floats +% has only a \texttt{p} specifier but no other. In that case it is +% essential that we not unravel the float page because such a +% float would then only go back onto the defer list as it has no +% place to go except a float page. +% \begin{macrocode} +\def\fp@analyse@floats@for@unraveling#1{% + \advance\fp@candidates\@ne + \ifnum \fp@candidates <\c@floatpagekeeplimit +% \end{macrocode} +% So far we haven't got enough floats to know that this float page +% should be kept so we check the given float specifiers. +% +% The test may look a little weird,\footnote{\enquote{Little} might +% be an understatement. Encoding a lot of information in individual +% bits of the counter value associated with a float was a great way +% in the early days of \LaTeX{} to preserve macro space (and +% absolutely essential back then), but these days \ldots{} Anyway, +% it is the way it is and that part can't really be changed without +% breaking a lot of packages.} but what we want to know is this: +% is there a \texttt{p} (third bit) but neither a \texttt{b} +% (second bit) nor a \texttt{t} (first bit). We don't care about +% \texttt{h} or \texttt{!} which are the next two bits in the float +% counter nor any of its higher bits (which encode the type of +% float). So we divide the integer number by 8, which drops +% the two least significant bits (think of the integer +% represented in binary format), and then multiply it again by 8. As +% a result the first two bits are zeroed out. We then compare the +% result with the original value and if the two values are the same +% then the \texttt{b} and \texttt{t} bits must both have been zero +% from the start. And since the float was on a float page we also +% know that it had a \texttt{p} specifier. +% \begin{macrocode} + \@tempcntb\count#1% + \divide\@tempcntb 8\relax + \multiply\@tempcntb 8\relax + \ifnum \count#1=\@tempcntb +% \end{macrocode} +% In that case we set \cs[no-index]{if@fcolmade} to \texttt{true} +% to signal that this float page should be kept, generate a tracing +% message and change \cs[no-index]{@elt} to become +% \cs[no-index]{@gobble} to quickly jump over any remaining floats +% in the loop without doing further tests or generate further +% tracing messages. +% \begin{macrocode} + \global \@fcolmadetrue + \fl@trace{----- current float page kept, contains a float}% + \fl@trace{\@spaces\space\space with p but no t or b specifier}% + \let\@elt\@gobble + \fi +% \end{macrocode} +% On the other hand, if we have seen enough floats we also know +% that the float page should be kept, so change the switch, give +% some tracing info and stop checking: +% \begin{macrocode} + \else + \global \@fcolmadetrue + \fl@trace{----- current float page kept + (contains at least \the\fp@candidates\space floats)}% + \let\@elt\@gobble + \fi +} +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\fp@maybe@add@bang} +% +% The helper \cs{fp@maybe@add@bang} is used to loop through all of +% the floats of a float page (receiving each as |#1| in turn) and +% add a \texttt{!}\@ specifier if there wasn't one before. +% +% However, we only define it if we implement strategy 1 which is +% option \option{addbang}. +% \begin{macrocode} +\ifnum\fp@strategy=1 + \def\fp@maybe@add@bang#1{% +% \end{macrocode} +% Find out if the fourth bit is set (which means no \texttt{!}\@) +% and if so subtract 16 from the float counter which means setting +% it to zero. +% \begin{macrocode} + \@boxfpsbit #1\sixt@@n + \ifodd \@tempcnta + \global\advance\count#1-\sixt@@n + \fi + } +\else + \let\fp@maybe@add@bang\@gobble +\fi +% \end{macrocode} +% \end{macro} +% +% +% +% +% \begin{macro}[internal]{\fp@maybe@check@tb} +% The code in \cs{fp@maybe@check@tb} is used in +% \cs{@largefloatcheck} to test if the float has a \texttt{t} or +% \texttt{b} specifier but is too large to fit into the +% respective area. This test is not made by default but only if the +% option \option{checktb} is used, i.e., strategy~2. +% \begin{macrocode} +\ifnum\fp@strategy=2 + \def\fp@maybe@check@tb{% +% \end{macrocode} +% Again this is a case of +% looking at various bits in the float counter value in binary +% notation. +% If the specifier contained a \texttt{!}\@ we are ok and it would +% be wrong to change the specifier, because in +% that case size restrictions for areas do not apply. For this we +% have to test the fourth bit which means dividing by 16 and then +% checking if the result is odd or even (odd means there was no +% \texttt{!}\@).\footnote{I'm sure we had good reasons to +% implement it this way in 1992\Dash we probably saved a few bytes +% which was important back then. But it is certainly odd that for +% \texttt{!}\@ a value of zero means that it was specified on the +% float while for all other specifiers a value of \texttt{1} +% indicates that the specifier was given.} The kernel +% \cs{@getfpsbit} does this for us and stores the result in +% \cs[no-index]{@tempcnta} so we can test this with \cs[no-index]{ifodd} to see if the +% bit was set. +% \begin{macrocode} + \@getfpsbit \sixt@@n + \ifodd \@tempcnta +% \end{macrocode} +% If there was no \texttt{!}\@ we check if the height of the +% float is too large to fit into the top area. +% \begin{macrocode} + \ifdim \ht\@currbox>\topfraction\textheight +% \end{macrocode} +% +% If that is the case we also check the first bit of the float +% counter to see if a \texttt{t} was specified. For this we use +% \cs{@getfpsbit} again but this time with \texttt{2} as the argument +% since we test the first bit. +% \begin{macrocode} + \@getfpsbit \tw@ + \ifodd \@tempcnta +% \end{macrocode} +% If \texttt{t} was specified we need to remove it (next line) and +% add (if not already present) a \texttt{p} instead. This is done +% by \cs[no-index]{fp@add@p@bit}. Finally we add a warning for the user about +% the change. +% \begin{macrocode} + \global\advance\count\@currbox -\tw@ + \fp@add@p@bit + \@latex@warning {Float too large for top area: t changed to p}% + \fi + \fi +% \end{macrocode} +% A similar test and action is needed for bottom floats; here we +% need to look at and zero out the second bit (i.e., using 4 as a value). +% \begin{macrocode} + \ifdim \ht\@currbox>\bottomfraction\textheight + \@getfpsbit 4\relax + \ifodd \@tempcnta + \global\advance\count\@currbox -4\relax + \fp@add@p@bit + \@latex@warning {Float too large for bottom area: + b changed to p}% + \fi + \fi + \fi + } +% \end{macrocode} +% In all other cases \cs{fp@maybe@check@tb} does nothing. +% \begin{macrocode} +\else \let\fp@maybe@check@tb\relax \fi +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}[internal]{\fp@add@p@bit} +% The command \cs{fp@add@p@bit} adds the \texttt{p} specifier which +% means checking the third bit and if not set, adding 8 to the float counter. +% \begin{macrocode} +\def\fp@add@p@bit{% + \@getfpsbit 8\relax + \ifodd \@tempcnta \else \global\advance\count\@currbox 8\relax \fi} +% \end{macrocode} +% \end{macro} +% +% +% \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index +% \subsection{Patches that will eventually go into \pkg{fltrace}} +% +% The \pkg{fewerfloatpages} package added some additional general +% tracing info into some of the kernel functions which isn't +% currently available when using only the \pkg{fltrace} package. As +% that tracing info is generally useful for understanding what the +% base part of the float algorithm does, it should also be added to +% the latter package. +% +% \fi +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% \Finale +% + + +\endinput diff --git a/Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.ins b/Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.ins new file mode 100644 index 00000000000..d3e1ef0563c --- /dev/null +++ b/Master/texmf-dist/source/latex/fewerfloatpages/fewerfloatpages.ins @@ -0,0 +1,66 @@ +%% +%% This file will generate fast loadable files and documentation +%% driver files from the dtx file(s) in this package when run through +%% LaTeX or TeX. +%% +%% Copyright 2019-2020 Frank Mittelbach +%% +%% +%% This file is part of the fewerfloatpages Bundle for LaTeX. +%% ------------------------------------------------------- +%% +%% It may be distributed and/or modified under the +%% conditions of the LaTeX Project Public License, either version 1.3c +%% 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.3c or later is part of all distributions of LaTeX +%% version 2005/12/01 or later. +%% +%% In particular, NO PERMISSION is granted to modify the contents of this +%% file since it contains the legal notices that are placed in the files +%% it generates. +%% +%% +%% +%% --------------- start of docstrip commands ------------------ +%% +\input l3docstrip + +\keepsilent + +\usedir{tex/latex/contrib/fewerfloatpages} + +\preamble + +This is a generated file. + +Copyright 2019-2020 Frank Mittelbach + +This file was generated from file(s) of the LaTeX `fewerfloatpages Bundle'. +-------------------------------------------------------------------------- + +It may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3c +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.3c or later is part of all distributions of LaTeX +version 2008 or later. + +This file may only be distributed together with a copy of the LaTeX +`fewerfloatpages Bundle'. You may however distribute the `fewerfloatpages Bundle' +without such generated files. + +The newest sources can be found below + + https://github.com/FrankMittelbach/fmitex/ + +where one can also log issues in case there are any. + +\endpreamble + + +\generate{\file{fewerfloatpages.sty}{\from{fewerfloatpages.dtx}{package}}} + +\endbatchfile diff --git a/Master/texmf-dist/tex/latex/fewerfloatpages/fewerfloatpages.sty b/Master/texmf-dist/tex/latex/fewerfloatpages/fewerfloatpages.sty new file mode 100644 index 00000000000..6c797aa3cc1 --- /dev/null +++ b/Master/texmf-dist/tex/latex/fewerfloatpages/fewerfloatpages.sty @@ -0,0 +1,248 @@ +%% +%% This is file `fewerfloatpages.sty', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% fewerfloatpages.dtx (with options: `package') +%% +%% This is a generated file. +%% +%% Copyright 2019-2020 Frank Mittelbach +%% +%% This file was generated from file(s) of the LaTeX `fewerfloatpages Bundle'. +%% -------------------------------------------------------------------------- +%% +%% It may be distributed and/or modified under the +%% conditions of the LaTeX Project Public License, either version 1.3c +%% 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.3c or later is part of all distributions of LaTeX +%% version 2008 or later. +%% +%% This file may only be distributed together with a copy of the LaTeX +%% `fewerfloatpages Bundle'. You may however distribute the `fewerfloatpages Bundle' +%% without such generated files. +%% +%% The newest sources can be found below +%% +%% https://github.com/FrankMittelbach/fmitex/ +%% +%% where one can also log issues in case there are any. +%% +%% File: fewerfloatpages.dtx (C) Copyright 2019-2020 Frank Mittelbach + +\def\fewerfloatpagesdate {2020/02/14} +\def\fewerfloatpagesversion{v1.0a} + + + +\NeedsTeXFormat{LaTeX2e}[2018-04-01] +\ProvidesPackage{fewerfloatpages} + [\fewerfloatpagesdate\space \fewerfloatpagesversion\space + improve float page generation (FMi)] +\DeclareOption{trace} + {\providecommand\fl@trace[1]% + {{\let\@elt\@empty\typeout{fewerfloatpages: #1}}}} +\def\fp@strategy{0}% +\DeclareOption{nocheck}{\def\fp@strategy{0}} % better name? +\DeclareOption{addbang}{\def\fp@strategy{1}} +\DeclareOption{checktb}{\def\fp@strategy{2}} +\ExecuteOptions{checktb} +\ProcessOptions +\providecommand\fl@trace[1]{} +\newcommand\floatpagekeepfraction{\textfraction} + +\newcounter{floatpagedeferlimit} \setcounter{floatpagedeferlimit}{3} + +\newcounter{floatpagekeeplimit} \setcounter{floatpagekeeplimit}{3} + + +\AtBeginDocument{% +\def \@tryfcolumn #1{% + \global \@fcolmadefalse + \ifx #1\@empty + \else + \fl@trace{PAGE: trying to make a float + \if@twocolumn column/page\else page\fi}% + \fl@trace{----- \string #1: #1}% + \xdef\@trylist{#1}% + \global \let \@failedlist \@empty + \begingroup + \let \@elt \@xtryfc \@trylist + \endgroup + \if@fcolmade + \fp@candidates\z@ + \def\@elt##1{\advance\fp@candidates\@ne}% + #1% + \let\@elt\relax + \ifnum \fp@candidates >\c@floatpagedeferlimit + \fl@trace{----- too many deferred floats for unraveling + (\the\fp@candidates\space> \the\c@floatpagedeferlimit)}% + \else + \global\@fcolmadefalse + \fp@candidates\z@ + \let\@elt\fp@analyse@floats@for@unraveling + \@flsucceed + \let\@elt\relax + \if@fcolmade \else + \@tempdima\floatpagekeepfraction\@colht + \ifdim \fp@unused@space >\@tempdima + \fl@trace{----- current float page unraveled^^J% + \@spaces\@spaces\@spaces\space\space\space + (free space \fp@unused@space\space > \the\@tempdima)}% + \xdef #1{\@failedlist\@flsucceed\@flfail}% + \let\@elt\fp@maybe@add@bang + \@flsucceed + \let\@elt\relax + \else + \global \@fcolmadetrue + \fl@trace{----- current float page kept, full enough^^J% + \@spaces\@spaces\@spaces\space\space\space + (free space \fp@unused@space\space < \the\@tempdima)}% + \fi + \fi + \fi + \else + \fl@trace{ --> fail: no float page made}% + \fi + \if@fcolmade + \@vtryfc #1% + \fi + \fi}% +}% -- END of \AtBeginDocument +\AtBeginDocument{% +\def\@makefcolumn #1{% + \begingroup + \@fpmin -\maxdimen + \let \@testfp \@gobble + \global \@fcolmadefalse + \ifx #1\@empty + \else + \fl@trace{PAGE: trying to make a float + \if@twocolumn column/page\else page\fi}% + \fl@trace{----- \string #1: #1}% + \xdef\@trylist{#1}% + \global \let \@failedlist \@empty + \begingroup + \let \@elt \@xtryfc \@trylist + \endgroup + \if@fcolmade + \@vtryfc #1% + \fi + \fi + \endgroup +}% +}% -- END of \AtBeginDocument +\def\@xtryfc #1{% + \fl@trace{ starting with \string#1}% + \@next\reserved@a\@trylist{}{}% + \@currtype \count #1% + \divide\@currtype\@xxxii + \multiply\@currtype\@xxxii + \@bitor \@currtype \@failedlist + \@testfp #1% + \@testwrongwidth #1% + \ifdim \ht #1>\@colht + \@testtrue + \fi + \if@test + \@cons\@failedlist #1% + \fl@trace{ --> fail}% + \else + \@ytryfc #1% + \fi +}% +\def\@ytryfc #1{% + \begingroup + \gdef\@flsucceed{\@elt #1}% + \global\let\@flfail\@empty + \@tempdima\ht #1% + \let\@elt\@ztryfc + \@trylist + \ifdim \@tempdima >\@fpmin + \global\@fcolmadetrue + \@tempdimb\@colht + \advance\@tempdimb-\@tempdima + \xdef\fp@unused@space{\the\@tempdimb}% + \else + \@cons\@failedlist #1% + \fl@trace{ --> fail}% + \fi + \endgroup + \if@fcolmade + \let\@elt\@gobble + \fl@trace{ --> success: \@flsucceed}% + \fi} +\def \@largefloatcheck{% + \ifdim \ht\@currbox>\textheight + \@tempdima -\textheight + \advance \@tempdima \ht\@currbox + \@latex@warning {Float too large for page by \the\@tempdima}% + \ht\@currbox \textheight + \fi + \fp@maybe@check@tb +} +\newcount\fp@candidates +\def\fp@unused@space{} +\def\fp@analyse@floats@for@unraveling#1{% + \advance\fp@candidates\@ne + \ifnum \fp@candidates <\c@floatpagekeeplimit + \@tempcntb\count#1% + \divide\@tempcntb 8\relax + \multiply\@tempcntb 8\relax + \ifnum \count#1=\@tempcntb + \global \@fcolmadetrue + \fl@trace{----- current float page kept, contains a float}% + \fl@trace{\@spaces\space\space with p but no t or b specifier}% + \let\@elt\@gobble + \fi + \else + \global \@fcolmadetrue + \fl@trace{----- current float page kept + (contains at least \the\fp@candidates\space floats)}% + \let\@elt\@gobble + \fi +} +\ifnum\fp@strategy=1 + \def\fp@maybe@add@bang#1{% + \@boxfpsbit #1\sixt@@n + \ifodd \@tempcnta + \global\advance\count#1-\sixt@@n + \fi + } +\else + \let\fp@maybe@add@bang\@gobble +\fi +\ifnum\fp@strategy=2 + \def\fp@maybe@check@tb{% + \@getfpsbit \sixt@@n + \ifodd \@tempcnta + \ifdim \ht\@currbox>\topfraction\textheight + \@getfpsbit \tw@ + \ifodd \@tempcnta + \global\advance\count\@currbox -\tw@ + \fp@add@p@bit + \@latex@warning {Float too large for top area: t changed to p}% + \fi + \fi + \ifdim \ht\@currbox>\bottomfraction\textheight + \@getfpsbit 4\relax + \ifodd \@tempcnta + \global\advance\count\@currbox -4\relax + \fp@add@p@bit + \@latex@warning {Float too large for bottom area: + b changed to p}% + \fi + \fi + \fi + } +\else \let\fp@maybe@check@tb\relax \fi +\def\fp@add@p@bit{% + \@getfpsbit 8\relax + \ifodd \@tempcnta \else \global\advance\count\@currbox 8\relax \fi} + +\endinput +%% +%% End of file `fewerfloatpages.sty'. |