Appendices ========== .. label follows .. _sec:requiredmodules: Required Perl modules --------------------- If you intend to use ``latexindent.pl`` and *not* one of the supplied standalone executable files (``latexindent.exe`` is available for Windows users without Perl, see :numref:`subsubsec:latexindent:exe`), then you will need a few standard Perl modules. If you can run the minimum code in :numref:`lst:helloworld` as in .. code-block:: latex :class: .commandshell perl helloworld.pl then you will be able to run ``latexindent.pl``, otherwise you may need to install the missing modules; see :numref:`sec:module-installer` and :numref:`sec:manual-module-instal`. .. code-block:: latex :caption: ``helloworld.pl`` :name: lst:helloworld #!/usr/bin/perl use strict; # | use warnings; # | use Encode; # | use Getopt::Long; # | use Data::Dumper; # these modules are use List::Util qw(max); # generally part use PerlIO::encoding; # of a default perl distribution use open ':std', ':encoding(UTF-8)';# | use Text::Wrap; # | use Text::Tabs; # | use FindBin; # | use File::Copy; # | use File::Basename; # | use File::Path; # | use File::HomeDir; # <--- typically requires install via cpanm use YAML::Tiny; # <--- typically requires install via cpanm print "hello world"; exit; .. label follows .. _sec:module-installer: Module installer script ~~~~~~~~~~~~~~~~~~~~~~~ ``latexindent.pl`` ships with a helper script that will install any missing ``perl`` modules on your system; if you run .. code-block:: latex :class: .commandshell perl latexindent-module-installer.pl or .. code-block:: latex :class: .commandshell perl latexindent-module-installer.pl then, once you have answered ``Y``, the appropriate modules will be installed onto your distribution. .. label follows .. _sec:manual-module-instal: Manually installing modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Manually installing the modules given in :numref:`lst:helloworld` will vary depending on your operating system and ``Perl`` distribution. Linux ~~~~~ perlbrew ^^^^^^^^ Linux users may be interested in exploring Perlbrew (“Perlbrew” n.d.); an example installation would be: .. code-block:: latex :class: .commandshell sudo apt-get install perlbrew perlbrew init perlbrew install perl-5.42.0 perlbrew switch perl-5.42.0 sudo apt-get install curl curl -L http://cpanmin.us | perl - App::cpanminus cpanm YAML::Tiny cpanm File::HomeDir .. index:: cpan Ubuntu/Debian ^^^^^^^^^^^^^ For other distributions, the Ubuntu/Debian approach may work as follows .. code-block:: latex :class: .commandshell sudo apt install perl sudo cpan -i App::cpanminus sudo cpanm YAML::Tiny sudo cpanm File::HomeDir or else by running, for example, .. code-block:: latex :class: .commandshell sudo perl -MCPAN -e'install "File::HomeDir"' Ubuntu: using the texlive from apt-get ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Ubuntu users that install texlive using ``apt-get`` as in the following .. code-block:: latex :class: .commandshell sudo apt install texlive sudo apt install texlive-latex-recommended may need the following additional command to work with ``latexindent.pl`` .. code-block:: latex :class: .commandshell sudo apt install texlive-extra-utils Ubuntu: users without perl ^^^^^^^^^^^^^^^^^^^^^^^^^^ ``latexindent-linux`` is a standalone executable for Ubuntu Linux (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from (“Home of Latexindent.pl” n.d.). .. index:: latexindent-linux .. index:: linux .. index:: TeXLive Arch-based distributions ^^^^^^^^^^^^^^^^^^^^^^^^ ``latexindent`` is included in Arch-packaged TeX Live, and can be installed by: .. code-block:: latex :class: .commandshell sudo pacman -S texlive-binextra perl-yaml-tiny perl-file-homedir To enable optional ``–GCString`` switch, install ``perl-unicode-linebreak``: .. code-block:: latex :class: .commandshell sudo pacman -S perl-unicode-linebreak Alpine ^^^^^^ If you are using Alpine, some ``Perl`` modules are not build-compatible with Alpine, but replacements are available through ``apk``. For example, you might use the commands given in :numref:`lst:alpine-install`; thanks to (J. 2020) for providing these details. .. code-block:: latex :caption: ``alpine-install.sh`` :name: lst:alpine-install # Installing perl apk --no-cache add miniperl perl-utils # Installing incompatible latexindent perl dependencies via apk apk --no-cache add \ perl-log-dispatch \ perl-namespace-autoclean \ perl-specio \ perl-unicode-linebreak # Installing remaining latexindent perl dependencies via cpan apk --no-cache add curl wget make ls /usr/share/texmf-dist/scripts/latexindent cd /usr/local/bin && \ curl -L https://cpanmin.us/ -o cpanm && \ chmod +x cpanm cpanm -n App::cpanminus cpanm -n File::HomeDir cpanm -n Params::ValidationCompiler cpanm -n YAML::Tiny Users of NixOS might like to see https://github.com/cmhughes/latexindent.pl/issues/222 for tips. Mac ~~~ Users of the Macintosh operating system might like to explore the following commands, for example: .. code-block:: latex :class: .commandshell brew install perl brew install cpanm cpanm YAML::Tiny cpanm File::HomeDir Alternatively, .. code-block:: latex :class: .commandshell brew install latexindent ``latexindent-macos`` is a standalone executable for macOS (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system. It is available from (“Home of Latexindent.pl” n.d.). .. index:: latexindent-macos .. index:: macOS .. index:: TeXLive Windows ~~~~~~~ Strawberry Perl users on Windows might use ``CPAN client``. All of the modules are readily available on CPAN (“CPAN: Comprehensive Perl Archive Network” n.d.). ``indent.log`` will contain details of the location of the Perl modules on your system. ``latexindent.exe`` is a standalone executable for Windows (and therefore does not require a Perl distribution) and caches copies of the Perl modules onto your system; if you wish to see where they are cached, use the ``trace`` option, e.g .. code-block:: latex :class: .commandshell latexindent.exe -t myfile.tex .. label follows .. _subsec:the-GCString: The GCString switch ~~~~~~~~~~~~~~~~~~~ If you find that the ``lookForAlignDelims`` (as in :numref:`subsec:align-at-delimiters`) does not work correctly for your language, then you may wish to use the ``Unicode::GCString`` module . .. index:: perl;Unicode GCString module .. index:: switches;–GCString demonstration This can be loaded by calling ``latexindent.pl`` with the ``GCString`` switch as in .. code-block:: latex :class: .commandshell latexindent.pl --GCString myfile.tex In this case, you will need to have the ``Unicode::GCString`` installed in your ``perl`` distribution by using, for example, .. code-block:: latex :class: .commandshell cpanm Unicode::GCString Note: this switch does *nothing* for ``latexindent.exe`` which loads the module by default. Users of ``latexindent.exe`` should not see any difference in behaviour whether they use this switch or not, as ``latexindent.exe`` loads the ``Unicode::GCString`` module. .. label follows .. _sec:updating-path: Updating the path variable -------------------------- ``latexindent.pl`` has a few scripts (available at (“Home of Latexindent.pl” n.d.)) that can update the ``path`` variables. Thank you to (Juang 2015) for this feature. If you’re on a Linux or Mac machine, then you’ll want ``CMakeLists.txt`` from (“Home of Latexindent.pl” n.d.). Add to path for Linux ~~~~~~~~~~~~~~~~~~~~~ To add ``latexindent.pl`` to the path for Linux, follow these steps: #. download ``latexindent.pl`` and its associated modules, ``defaultSettings.yaml``, to your chosen directory from (“Home of Latexindent.pl” n.d.) ; #. within your directory, create a directory called ``path-helper-files`` and download ``CMakeLists.txt`` and ``cmake_uninstall.cmake.in`` from (“Home of Latexindent.pl” n.d.)/path-helper-files to this directory; #. run .. code-block:: latex :class: .commandshell ls /usr/local/bin to see what is *currently* in there; #. run the following commands .. code-block:: latex :class: .commandshell sudo apt-get update sudo apt-get install --no-install-recommends cmake make # or any other generator mkdir build && cd build cmake ../path-helper-files sudo make install #. run .. code-block:: latex :class: .commandshell ls /usr/local/bin again to check that ``latexindent.pl``, its modules and ``defaultSettings.yaml`` have been added. To *remove* the files, run .. code-block:: latex :class: .commandshell sudo make uninstall Add to path for Windows ~~~~~~~~~~~~~~~~~~~~~~~ To add ``latexindent.exe`` to the path for Windows, follow these steps: #. download ``latexindent.exe``, ``defaultSettings.yaml``, ``add-to-path.bat`` from (“Home of Latexindent.pl” n.d.) to your chosen directory; #. open a command prompt and run the following command to see what is *currently* in your ``%path%`` variable; .. code-block:: latex :class: .commandshell echo %path% #. right click on ``add-to-path.bat`` and *Run as administrator*; #. log out, and log back in; #. open a command prompt and run .. code-block:: latex :class: .commandshell echo %path% to check that the appropriate directory has been added to your ``%path%``. To *remove* the directory from your ``%path%``, run ``remove-from-path.bat`` as administrator. .. label follows .. _sec:batches: Batches of files ---------------- You can instruct ``latexindent.pl`` to operate on multiple files. For example, the following calls are all valid .. code-block:: latex :class: .commandshell latexindent.pl myfile1.tex latexindent.pl myfile1.tex myfile2.tex latexindent.pl myfile*.tex We note the following features of the script in relation to the switches detailed in :numref:`sec:how:to:use`. location of indent.log ~~~~~~~~~~~~~~~~~~~~~~ If the ``-c`` switch is *not* active, then ``indent.log`` goes to the directory of the final file called. If the ``-c`` switch *is* active, then ``indent.log`` goes to the specified directory. interaction with -w switch ~~~~~~~~~~~~~~~~~~~~~~~~~~ If the ``-w`` switch is active, as in .. code-block:: latex :class: .commandshell latexindent.pl -w myfile*.tex then files will be overwritten individually. Back-up files can be re-directed via the ``-c`` switch. interaction with -o switch ~~~~~~~~~~~~~~~~~~~~~~~~~~ If ``latexindent.pl`` is called using the ``-o`` switch as in .. code-block:: latex :class: .commandshell latexindent.pl myfile*.tex -o=my-output-file.tex and there are multiple files to operate upon, then the ``-o`` switch is ignored because there is only *one* output file specified. More generally, if the ``-o`` switch does *not* have a ``+`` symbol at the beginning, then the ``-o`` switch will be ignored, and is turned it off. For example .. code-block:: latex :class: .commandshell latexindent.pl myfile*.tex -o=+myfile *will* work fine because *each* ``.tex`` file will output to ``myfile.tex`` Similarly, .. code-block:: latex :class: .commandshell latexindent.pl myfile*.tex -o=++ *will* work because the ‘existence check/incrementation’ routine will be applied. interaction with lines switch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This behaves as expected by attempting to operate on the line numbers specified for each file. See the examples in :numref:`sec:line-switch`. interaction with check switches ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The exit codes for ``latexindent.pl`` are given in :numref:`tab:exit-codes`. When operating on multiple files with the check switch active, as in .. code-block:: latex :class: .commandshell latexindent.pl myfile*.tex --check then - exit code 0 means that the text from *none* of the files has been changed; - exit code 1 means that the text from *at least one* of the files been file changed. The interaction with ``checkv`` switch is as in the check switch, but with verbose output. when a file does not exist ~~~~~~~~~~~~~~~~~~~~~~~~~~ What happens if one of the files can not be operated upon? - if at least one of the files does not exist and ``latexindent.pl`` has been called to act upon multiple files, then the exit code is 3; note that ``latexindent.pl`` will try to operate on each file that it is called upon, and will not exit with a fatal message in this case; - if at least one of the files can not be read and ``latexindent.pl`` has been called to act upon multiple files, then the exit code is 4; note that ``latexindent.pl`` will try to operate on each file that it is called upon, and will not exit with a fatal message in this case; - if ``latexindent.pl`` has been told to operate on multiple files, and some do not exist and some cannot be read, then the exit code will be either 3 or 4, depending upon which it scenario it encountered most recently. latexindent-yaml-schema.json ---------------------------- ``latexindent.pl`` ships with ``latexindent-yaml-schema.json`` which might help you when constructing your YAML files. .. index:: json;schema for YAML files VSCode demonstration ~~~~~~~~~~~~~~~~~~~~ To use ``latexindent-yaml-schema.json`` with ``VSCode``, you can use the following steps: .. index:: VSCode .. index:: json;VSCode #. download ``latexindent-yaml-schema.json`` from the ``documentation`` folder of (“Home of Latexindent.pl” n.d.), save it in whichever directory you would like, noting it for reference; #. following the instructions from (“How to Create Your Own Auto-Completion for Json and Yaml Files on Vs Code with the Help of Json Schema” n.d.), for example, you should install the VSCode YAML extension (“VSCode Yaml Extension” n.d.); #. set up your ``settings.json`` file using the directory you saved the file by adapting :numref:`lst:settings.json`; on my Ubuntu laptop this file lives at ``/home/cmhughes/.config/Code/User/settings.json``. .. literalinclude:: demonstrations/settings.json :class: .baseyaml :caption: ``settings.json`` :name: lst:settings.json Alternatively, if you would prefer not to download the json file, you might be able to use an adapted version of :numref:`lst:settings-alt.json`. .. literalinclude:: demonstrations/settings-alt.json :class: .baseyaml :caption: ``settings-alt.json`` :name: lst:settings-alt.json Finally, if your TeX distribution is up to date, then ``latexindent-yaml-schema.json`` *should* be in the documentation folder of your installation, so an adapted version of :numref:`lst:settings-alt1.json` may work. .. literalinclude:: demonstrations/settings-alt1.json :class: .baseyaml :caption: ``settings-alt1.json`` :name: lst:settings-alt1.json If you have details of how to implement this schema in other editors, please feel encouraged to contribute to this documentation. .. label follows .. _sec:app:conda: Using conda ----------- If you use conda you’ll only need .. code-block:: latex :class: .commandshell conda install latexindent.pl -c conda-forge This will install the executable and all its dependencies (including perl) in the activate environment. You don’t even have to worry about ``defaultSettings.yaml`` as it included too, you can thus skip :numref:`sec:requiredmodules` and :numref:`sec:updating-path`. .. index:: conda You can get a conda installation for example from (“Conda Forge” n.d.) or from (“Anacoda” n.d.). Sample conda installation on Ubuntu ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On Ubuntu I followed the 64-bit installation instructions at (“How to Install Anaconda on Ubuntu?” n.d.) and then I ran the following commands: .. code-block:: latex :class: .commandshell conda create -n latexindent.pl conda activate latexindent.pl conda install latexindent.pl -c conda-forge conda info --envs conda list conda run latexindent.pl -vv I found the details given at (“Solving Environment: Failed with Initial Frozen Solve. Retrying with Flexible Solve.” n.d.) to be helpful. .. label follows .. _sec:app:docker: Using docker ------------ If you use docker you’ll only need .. code-block:: latex :class: .commandshell docker pull ghcr.io/cmhughes/latexindent.pl This will download the image packed ``latexindent``\ ’s executable and its all dependencies. .. index:: docker Thank you to (eggplants 2022) for contributing this feature; see also (“Latexindent.pl Ghcr (Github Container Repository) Location” n.d.). For reference, *ghcr* stands for *GitHub Container Repository*. Sample docker installation on Ubuntu ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To pull the image and show ``latexindent``\ ’s help on Ubuntu: .. code-block:: latex :caption: ``docker-install.sh`` :name: lst:docker-install # setup docker if not already installed if ! command -v docker &> /dev/null; then sudo apt install docker.io -y sudo groupadd docker sudo gpasswd -a "$USER" docker sudo systemctl restart docker newgrp docker fi # download image and execute docker pull ghcr.io/cmhughes/latexindent.pl docker run ghcr.io/cmhughes/latexindent.pl -h Once I have run the above, on subsequent logins I run .. code-block:: latex :caption: ``docker-install.sh`` :name: lst:docker-install-subsequent newgrp docker docker run ghcr.io/cmhughes/latexindent.pl -h How to format on Docker ~~~~~~~~~~~~~~~~~~~~~~~ When you use ``latexindent`` with the docker image, you have to mount target ``tex`` file like this: .. code-block:: latex :class: .commandshell docker run -v /path/to/local/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s -w myfile.tex pre-commit ---------- Users of ``.git`` may be interested in exploring the ``pre-commit`` tool (“Pre-Commit: A Framework for Managing and Maintaining Multi-Language Pre-Commit Hooks.” n.d.), which is supported by ``latexindent.pl``. Thank you to (Geus 2022) for contributing this feature, and to (Holthuis 2022) for their contribution to it. To use the ``pre-commit`` tool, you will need to install ``pre-commit``; sample instructions for Ubuntu are given in :numref:`sec:pre-commit-ubuntu`. Once installed, there are two ways to use ``pre-commit``: using ``CPAN`` or using ``conda``, detailed in :numref:`sec:pre-commit-cpan` and :numref:`sec:pre-commit-conda` respectively. .. label follows .. _sec:pre-commit-ubuntu: Sample pre-commit installation on Ubuntu ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On Ubuntu I ran the following command: .. code-block:: latex :class: .commandshell python3 -m pip install pre-commit I then updated my path via .bashrc so that it includes the line in :numref:`lst:bashrc-update`. .. code-block:: latex :caption: ``.bashrc`` update :name: lst:bashrc-update ... export PATH=$PATH:/home/cmhughes/.local/bin pre-commit defaults ~~~~~~~~~~~~~~~~~~~ The default values that are employed by ``pre-commit`` are shown in :numref:`lst:.pre-commit-yaml-default`. .. index:: pre-commit;default .. literalinclude:: ../.pre-commit-hooks.yaml :class: .baseyaml :caption: ``.pre-commit-hooks.yaml`` (default) :name: lst:.pre-commit-yaml-default In particular, the decision has deliberately been made (in collaboration with (Holthuis 2022)) to have the default to employ the following switches: ``overwriteIfDifferent``, ``silent``, ``local``; this is detailed in the lines that specify ``args`` in :numref:`lst:.pre-commit-yaml-default`. .. index:: pre-commit;warning .. index:: warning;pre-commit .. warning:: Users of ``pre-commit`` will, by default, have the ``overwriteIfDifferent`` switch employed. It is assumed that such users have version control in place, and are intending to overwrite their files. .. label follows .. _sec:pre-commit-cpan: pre-commit using CPAN ~~~~~~~~~~~~~~~~~~~~~ To use ``latexindent.pl`` with ``pre-commit``, create the file ``.pre-commit-config.yaml`` given in :numref:`lst:.pre-commit-config.yaml-cpan` in your git-repository. .. index:: cpan .. index:: git .. index:: pre-commit;cpan .. literalinclude:: demonstrations/pre-commit-config-cpan.yaml :class: .baseyaml :caption: ``.pre-commit-config.yaml`` (cpan) :name: lst:.pre-commit-config.yaml-cpan Once created, you should then be able to run the following command: .. code-block:: latex :class: .commandshell pre-commit run --all-files A few notes about :numref:`lst:.pre-commit-config.yaml-cpan`: - the settings given in :numref:`lst:.pre-commit-config.yaml-cpan` instruct ``pre-commit`` to use ``CPAN`` to get dependencies; - this requires ``pre-commit`` and ``perl`` to be installed on your system; - the ``args`` lists selected command-line options; the settings in :numref:`lst:.pre-commit-config.yaml-cpan` are equivalent to calling .. code-block:: latex :class: .commandshell latexindent.pl -s myfile.tex for each ``.tex`` file in your repository; - to instruct ``latexindent.pl`` to overwrite the files in your repository, then you can update :numref:`lst:.pre-commit-config.yaml-cpan` so that ``args: [-s, -w]``. Naturally you can add options, or omit ``-s`` and ``-w``, according to your preference. .. label follows .. _sec:pre-commit-conda: pre-commit using conda ~~~~~~~~~~~~~~~~~~~~~~ You can also rely on ``conda`` (detailed in :numref:`sec:app:conda`) instead of ``CPAN`` for all dependencies, including ``latexindent.pl`` itself. .. index:: conda .. index:: git .. index:: pre-commit;conda .. literalinclude:: demonstrations/pre-commit-config-conda.yaml :class: .baseyaml :caption: ``.pre-commit-config.yaml`` (conda) :name: lst:.pre-commit-config.yaml-conda Once created, you should then be able to run the following command: .. code-block:: latex :class: .commandshell pre-commit run --all-files A few notes about :numref:`lst:.pre-commit-config.yaml-cpan`: - the settings given in :numref:`lst:.pre-commit-config.yaml-conda` instruct ``pre-commit`` to use ``conda`` to get dependencies; - this requires ``pre-commit`` and ``conda`` to be installed on your system; - the ``args`` lists selected command-line options; the settings in :numref:`lst:.pre-commit-config.yaml-cpan` are equivalent to calling .. code-block:: latex :class: .commandshell conda run latexindent.pl -s myfile.tex for each ``.tex`` file in your repository; - to instruct ``latexindent.pl`` to overwrite the files in your repository, then you can update :numref:`lst:.pre-commit-config.yaml-cpan` so that ``args: [-s, -w]``. .. label follows .. _sec:pre-commit-docker: pre-commit using docker ~~~~~~~~~~~~~~~~~~~~~~~ You can also rely on ``docker`` (detailed in :numref:`sec:app:docker`) instead of ``CPAN`` for all dependencies, including ``latexindent.pl`` itself. .. index:: docker .. index:: git .. index:: pre-commit;docker .. literalinclude:: demonstrations/pre-commit-config-docker.yaml :class: .baseyaml :caption: ``.pre-commit-config.yaml`` (docker) :name: lst:.pre-commit-config.yaml-docker Once created, you should then be able to run the following command: .. code-block:: latex :class: .commandshell pre-commit run --all-files A few notes about :numref:`lst:.pre-commit-config.yaml-cpan`: - the settings given in :numref:`lst:.pre-commit-config.yaml-docker` instruct ``pre-commit`` to use ``docker`` to get dependencies; - this requires ``pre-commit`` and ``docker`` to be installed on your system; - the ``args`` lists selected command-line options; the settings in :numref:`lst:.pre-commit-config.yaml-cpan` are equivalent to calling .. code-block:: latex :class: .commandshell docker run -v /path/to/myfile.tex:/myfile.tex ghcr.io/cmhughes/latexindent.pl -s myfile.tex for each ``.tex`` file in your repository; - to instruct ``latexindent.pl`` to overwrite the files in your repository, then you can update :numref:`lst:.pre-commit-config.yaml-cpan` so that ``args: [-s, -w]``. pre-commit example using -l, -m switches ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Let’s consider a small example, with local ``latexindent.pl`` settings in ``.latexindent.yaml``. .. proof:example:: We use the local settings given in :numref:`lst:.latexindent.yaml`. .. code-block:: latex :caption: ``.latexindent.yaml`` :name: lst:.latexindent.yaml onlyOneBackUp: 1 modifyLineBreaks: oneSentencePerLine: manipulateSentences: 1 and ``.pre-commit-config.yaml`` as in :numref:`lst:.latexindent.yaml-switches`: .. literalinclude:: demonstrations/pre-commit-config-demo.yaml :class: .baseyaml :caption: ``.pre-commit-config.yaml`` (demo) :name: lst:.latexindent.yaml-switches Now running .. code-block:: latex :class: .commandshell pre-commit run --all-files is equivalent to running .. code-block:: latex :class: .commandshell latexindent.pl -l -m -s -w myfile.tex for each ``.tex`` file in your repository. A few notes about :numref:`lst:.latexindent.yaml-switches`: - the ``-l`` option was added to use the local ``.latexindent.yaml`` (where it was specified to only create one back-up file, as ``git`` typically takes care of this when you use ``pre-commit``); - ``-m`` to modify line breaks; in addition to ``-s`` to suppress command-line output, and ``-w`` to format files in place. .. label follows .. _app:indentconfig:options: indentconfig options -------------------- The behaviour of ``latexindent.pl`` is controlled from the settings specified in any of the YAML files that you tell it to load. By default, ``latexindent.pl`` will only load ``defaultSettings.yaml``, but there are a few ways that you can tell it to load your own settings files. We focus our discussion on ``indentconfig.yaml``, but there are other options which we also detail here. .. label follows .. _sec:indentconfig: indentconfig.yaml and .indentconfig.yaml ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``latexindent.pl`` will always check your home directory for ``indentconfig.yaml`` and ``.indentconfig.yaml`` (unless it is called with the ``-d`` switch), which is a plain text file you can create that contains the *absolute* paths for any settings files that you wish ``latexindent.pl`` to load. There is no difference between ``indentconfig.yaml`` and ``.indentconfig.yaml``, other than the fact that ``.indentconfig.yaml`` is a ‘hidden’ file; thank you to (Diaz 2014) for providing this feature. In what follows, we will use ``indentconfig.yaml``, but it is understood that this could equally represent ``.indentconfig.yaml``. If you have both files in existence then ``indentconfig.yaml`` takes priority. For Mac and Linux users, their home directory is `` /username`` while Windows (Vista onwards) is ``C:\Users\username``\ [1]_ :numref:`lst:indentconfig` shows a sample ``indentconfig.yaml`` file. .. literalinclude:: demonstrations/indent-config.yaml :class: .baseyaml :caption: ``indentconfig.yaml`` (sample) :name: lst:indentconfig Note that the ``.yaml`` files you specify in ``indentconfig.yaml`` will be loaded in the order in which you write them. Each file doesn’t have to have every switch from ``defaultSettings.yaml``; in fact, I recommend that you only keep the switches that you want to *change* in these settings files. To get started with your own settings file, you might like to save a copy of ``defaultSettings.yaml`` in another directory and call it, for example, ``mysettings.yaml``. Once you have added the path to ``indentconfig.yaml`` you can change the switches and add more code-block names to it as you see fit – have a look at :numref:`lst:mysettings` for an example that uses four tabs for the default indent, adds the ``tabbing`` environment/command to the list of environments that contains alignment delimiters; you might also like to refer to the many YAML files detailed throughout the rest of this documentation. .. index:: indentation;defaultIndent using YAML file .. literalinclude:: demonstrations/tabbing.yaml :class: .baseyaml :caption: ``mysettings.yaml`` (example) :name: lst:mysettings You can make sure that your settings are loaded by checking ``indent.log`` for details – if you have specified a path that ``latexindent.pl`` doesn’t recognise then you’ll get a warning, otherwise you’ll get confirmation that ``latexindent.pl`` has read your settings file. [2]_ .. index:: warning;editing YAML files .. warning:: When editing ``.yaml`` files it is *extremely* important to remember how sensitive they are to spaces. I highly recommend copying and pasting from ``defaultSettings.yaml`` when you create your first ``whatevernameyoulike.yaml`` file. If ``latexindent.pl`` can not read your ``.yaml`` file it will tell you so in ``indent.log``. As of you can specify the ``paths`` field from :numref:`lst:indentconfig` within any of your ``latexindent.yaml`` and friends settings files. This can lead to creative nesting of configuration files; a demonstration is given in :numref:`sec:appendix:paths`. .. label follows .. _sec:localsettings: localSettings.yaml and friends ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``-l`` switch tells ``latexindent.pl`` to look for ``localSettings.yaml`` and/or friends in the *same directory* as ``myfile.tex``. For example, if you use the following command .. index:: switches;-l demonstration .. code-block:: latex :class: .commandshell latexindent.pl -l myfile.tex then ``latexindent.pl`` will search for and then, assuming they exist, load each of the following files in the following order: #. localSettings.yaml #. latexindent.yaml #. .localSettings.yaml #. .latexindent.yaml These files will be assumed to be in the same directory as ``myfile.tex``, or otherwise in the current working directory. You do not need to have all of the above files, usually just one will be sufficient. In what follows, whenever we refer to ``localSettings.yaml`` it is assumed that it can mean any of the four named options listed above. If you’d prefer to name your ``localSettings.yaml`` file something different, (say, ``mysettings.yaml`` as in :numref:`lst:mysettings`) then you can call ``latexindent.pl`` using, for example, .. code-block:: latex :class: .commandshell latexindent.pl -l=mysettings.yaml myfile.tex Any settings file(s) specified using the ``-l`` switch will be read *after* ``defaultSettings.yaml`` and, assuming they exist, any user setting files specified in ``indentconfig.yaml``. Your settings file can contain any switches that you’d like to change; a sample is shown in :numref:`lst:localSettings`, and you’ll find plenty of further examples throughout this manual. .. index:: verbatim;verbatimEnvironments demonstration (-l switch) .. code-block:: latex :caption: ``localSettings.yaml`` (example) :name: lst:localSettings # verbatim environments - environments specified # here will not be changed at all! verbatimEnvironments: cmhenvironment: 0 myenv: 1 You can make sure that your settings file has been loaded by checking ``indent.log`` for details; if it can not be read then you receive a warning, otherwise you’ll get confirmation that ``latexindent.pl`` has read your settings file. .. label follows .. _sec:yamlswitch: The -y|yaml switch ~~~~~~~~~~~~~~~~~~ You may use the ``-y`` switch to load your settings; for example, if you wished to specify the settings from :numref:`lst:localSettings` using the ``-y`` switch, then you could use the following command: .. index:: verbatim;verbatimEnvironments demonstration (-y switch) .. code-block:: latex :class: .commandshell latexindent.pl -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex Note the use of ``;`` to specify another field within ``verbatimEnvironments``. This is shorthand, and equivalent, to using the following command: .. index:: switches;-y demonstration .. code-block:: latex :class: .commandshell latexindent.pl -y="verbatimEnvironments:cmhenvironment:0,verbatimEnvironments:myenv:1" myfile.tex You may, of course, specify settings using the ``-y`` switch as well as, for example, settings loaded using the ``-l`` switch; for example, .. index:: switches;-l demonstration .. index:: switches;-y demonstration .. code-block:: latex :class: .commandshell latexindent.pl -l=mysettings.yaml -y="verbatimEnvironments:cmhenvironment:0;myenv:1" myfile.tex Any settings specified using the ``-y`` switch will be loaded *after* any specified using ``indentconfig.yaml`` and the ``-l`` switch. If you wish to specify any regex-based settings using the ``-y`` switch, .. index:: regular expressions;using -y switch it is important not to use quotes surrounding the regex; for example, with reference to the ‘one sentence per line’ feature (:numref:`sec:onesentenceperline`) and the listings within :numref:`lst:sentencesEndWith`, the following settings give the option to have sentences end with a semicolon .. index:: switches;-y demonstration .. code-block:: latex :class: .commandshell latexindent.pl -m --yaml='modifyLineBreaks:oneSentencePerLine:sentencesEndWith:other:\;' Note that the ``paths`` settings (see :numref:`sec:appendix:paths`) can *not* be specified using the ``-y`` switch. .. label follows .. _sec:loadorder: Settings load order ~~~~~~~~~~~~~~~~~~~ ``latexindent.pl`` loads the settings files in the following order: .. index:: switches;-l in relation to other settings #. ``defaultSettings.yaml`` is always loaded, and can not be renamed; #. ``anyUserSettings.yaml`` and any other arbitrarily-named files specified in ``indentconfig.yaml``; #. ``localSettings.yaml`` but only if found in the same directory as ``myfile.tex`` and called with ``-l`` switch; this file can be renamed, provided that the call to ``latexindent.pl`` is adjusted accordingly (see :numref:`sec:localsettings`). You may specify both relative and absolute paths to other YAML files using the ``-l`` switch, separating multiple files using commas; #. any settings specified in the ``-y`` switch. A visual representation of this is given in :numref:`fig:loadorder`. .. label follows .. _fig:loadorder: .. figure:: figure-schematic.png Schematic of the load order described in :numref:`sec:loadorder`; solid lines represent mandatory files, dotted lines represent optional files. ``indentconfig.yaml`` can contain as many files as you like. The files will be loaded in order; if you specify settings for the same field in more than one file, the most recent takes priority. .. label follows .. _indentconfig-options-1: indentconfig options ~~~~~~~~~~~~~~~~~~~~ This section describes the possible locations for the main configuration file, discussed in :numref:`sec:indentconfig`. Thank you to (Nehctargl 2022) for this contribution. The possible locations of ``indentconfig.yaml`` are read one after the other, and reading stops when a valid file is found in one of the paths. Before stating the list, we give summarise in :numref:`tab:environment:summary`. .. label follows .. _tab:environment:summary: .. table:: indentconfig environment variable summaries ==================== ================= ===== ===== ======= environment variable type Linux macOS Windows ==================== ================= ===== ===== ======= LATEXINDENT_CONFIG full path to file yes yes yes XDG_CONFIG_HOME directory path yes no no LOCALAPPDATA directory path no no yes ==================== ================= ===== ===== ======= The following list shows the checked options and is sorted by their respective priority. It uses capitalized and with a dollar symbol prefixed names (e.g. ``$LATEXINDENT_CONFIG``) to symbolize environment variables. In addition to that the variable name ``$homeDir`` is used to symbolize your home directory. #. The value of the environment variable ``$LATEXINDENT_CONFIG`` is treated as highest priority source for the path to the configuration file. #. The next options are dependent on your operating system: - Linux: #. The file at ``$XDG_CONFIG_HOME/latexindent/indentconfig.yaml`` #. The file at ``$homeDir/.config/latexindent/indentconfig.yaml`` - Windows: #. The file at ``$LOCALAPPDATA\latexindent\indentconfig.yaml`` #. The file at ``$homeDir\AppData\Local\latexindent\indentconfig.yaml`` - Mac: #. The file at ``$homeDir/Library/Preferences/latexindent/indentconfig.yaml`` #. The file at ``$homeDir/indentconfig.yaml`` #. The file at ``$homeDir/.indentconfig.yaml`` Why to change the configuration location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is mostly a question about what you prefer, some like to put all their configuration files in their home directory (see ``$homeDir`` above), whilst some like to sort their configuration. And if you don’t care about it, you can just continue using the same defaults. How to change the configuration location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This depends on your preferred location, if, for example, you would like to set a custom location, you would have to change the ``$LATEXINDENT_CONFIG`` environment variable. Although the following example only covers ``$LATEXINDENT_CONFIG``, the same process can be applied to ``$XDG_CONFIG_HOME`` or ``$LOCALAPPDATA`` because both are environment variables. You just have to change the path to your chosen configuration directory (e.g. ``$homeDir/.config`` or ``$homeDir\AppData\Local`` on Linux or Windows respectively) .. label follows .. _linux-1: Linux ~~~~~ To change ``$LATEXINDENT_CONFIG`` on Linux you can run the following command in a terminal after changing the path: .. code-block:: latex :class: .commandshell echo 'export LATEXINDENT_CONFIG="/home/cmh/latexindent-config.yaml"' >> ~/.profile Context: This command adds the given line to your ``.profile`` file (which is commonly stored in ``$HOME/.profile``). All commands in this file a run after login, so the environment variable will be set after your next login. You can check the value of ``$LATEXINDENT_CONFIG`` by typing .. code-block:: latex :class: .commandshell echo $LATEXINDENT_CONFIG /home/cmh/latexindent-config.yaml Linux users interested in ``$XDG_CONFIG_HOME`` can explore variations of the following commands .. code-block:: latex :class: .commandshell echo $XDG_CONFIG_HOME echo ${XDG_CONFIG_HOME:=$HOME/.config} echo $XDG_CONFIG_HOME mkdir /home/cmh/.config/latexindent touch /home/cmh/.config/latexindent/indentconfig.yaml .. label follows .. _windows-1: Windows ~~~~~~~ To change ``$LATEXINDENT_CONFIG`` on Windows you can run the following command in ``powershell.exe`` after changing the path: .. code-block:: latex :class: .commandshell [Environment]::SetEnvironmentVariable ("LATEXINDENT_CONFIG", "\your\config\path", "User") This sets the environment variable for every user session. .. label follows .. _mac-1: Mac ~~~ To change ``$LATEXINDENT_CONFIG`` on macOS you can run the following command in a terminal after changing the path: .. code-block:: latex :class: .commandshell echo 'export LATEXINDENT_CONFIG="/your/config/path"' >> ~/.profile Context: This command adds the line to your ``.profile`` file (which is commonly stored in ``$HOME/.profile``). All commands in this file a run after login, so the environment variable will be set after your next login. .. label follows .. _sec:appendix:paths: paths demonstration ------------------- As detailed in :numref:`app:indentconfig:options` , the ``paths`` field can be specified in any of your ``YAML`` files. We will use the file in :numref:`lst:paths-demo` for demonstration in what follows. .. literalinclude:: demonstrations/paths-demo.tex :class: .tex :caption: ``paths-demo.tex`` :name: lst:paths-demo .. proof:example:: Consider the settings given in :numref:`lst:path1-yaml` and :numref:`lst:path2-yaml`. .. literalinclude:: demonstrations/path1.yaml :class: .baseyaml :caption: ``path1.yaml`` :name: lst:path1-yaml .. literalinclude:: demonstrations/path2.yaml :class: .baseyaml :caption: ``path2.yaml`` :name: lst:path2-yaml Upon calling .. code-block:: latex :class: .commandshell latexindent.pl -l=path1.yaml paths-demo.tex then we will receive the output given in :numref:`lst:paths-demo-mod1`. .. literalinclude:: demonstrations/paths-demo-mod1.tex :class: .tex :caption: ``paths-demo-mod1.tex`` :name: lst:paths-demo-mod1 We note that the settings from :numref:`lst:path2-yaml` have been called from :numref:`lst:path1-yaml`. On inspection of ``indent.log`` from the above call, we see the details of this part of the process given in :numref:`lst:path-test1:txt`. .. literalinclude:: demonstrations/path-test1.txt :class: .tex :caption: ``path-test1.txt`` :name: lst:path-test1:txt .. proof:example:: Consider the settings given in :numref:`lst:path3-yaml` to :numref:`lst:path5-yaml`. .. literalinclude:: demonstrations/path3.yaml :class: .baseyaml :caption: ``path3.yaml`` :name: lst:path3-yaml .. literalinclude:: demonstrations/path4.yaml :class: .baseyaml :caption: ``path4.yaml`` :name: lst:path4-yaml .. literalinclude:: demonstrations/path5.yaml :class: .baseyaml :caption: ``path5.yaml`` :name: lst:path5-yaml Upon calling .. code-block:: latex :class: .commandshell latexindent.pl -l=path3.yaml paths-demo.tex then we will receive the output given in :numref:`lst:paths-demo-mod3`. .. literalinclude:: demonstrations/paths-demo-mod3.tex :class: .tex :caption: ``paths-demo-mod3.tex`` :name: lst:paths-demo-mod3 We see that ``path3.yaml`` calls ``path4.yaml`` which in turn calls ``path5.yaml``. On inspection of ``indent.log`` from the above call, we see the details of this part of the process given in :numref:`lst:path-test3:txt`. .. literalinclude:: demonstrations/path-test3.txt :class: .tex :caption: ``path-test3.txt`` :name: lst:path-test3:txt .. label follows .. _app:logfile-demo: logFilePreferences ------------------ ``latexindent.pl`` writes information to ``indent.log``, some of which can be customized by changing ``logFilePreferences``; see :numref:`lst:logFilePreferences`. If you load your own user settings (see :numref:`sec:indentconfig`) then ``latexindent.pl`` will detail them in ``indent.log``; you can choose not to have the details logged by switching ``showEveryYamlRead`` to ``0``. Once all of your settings have been loaded, you can see the amalgamated settings in the log file by switching ``showAmalgamatedSettings`` to ``1``, if you wish. .. literalinclude:: ../defaultSettings.yaml :class: .baseyaml :caption: ``logFilePreferences`` :name: lst:logFilePreferences :lines: 520-532 :linenos: :lineno-start: 520 The log file will end with the characters given in ``endLogFileWith``, and will report the ``GitHub`` address of ``latexindent.pl`` to the log file if ``showGitHubInfoFooter`` is set to ``1``. Note: ``latexindent.pl`` no longer uses the ``log4perl`` module to handle the creation of the logfile. Some of the options for Perl’s ``Dumper`` module can be specified in :numref:`lst:logFilePreferences`; see (“Data::Dumper Module” n.d.) and (“Data Dumper Demonstration” n.d.) for more information. These options will mostly be helpful for those calling ``latexindent.pl`` with the ``-tt`` option described in :numref:`sec:commandline`. :numref:`lst:logFilePreferences` describes the options for customising the information given to the log file, and we provide a few demonstrations here. .. label follows .. _app:encoding: Encoding -------- When using latexindent in different ways on different systems, the range of characters supported by its switches/flags/options (see :numref:`sec:commandline`) may vary. For the Windows executable file ``latexindent.exe``, its options support UTF-8 characters. For the Windows Perl script ``latexindent.pl``, its option switch supports the characters supported by the encoding corresponding to the system code page. You can check the system code page by running the following command in either ``cmd.exe`` or ``powershell.exe``: .. code-block:: latex :class: .commandshell chcp which may receive the following result .. code-block:: latex :class: .commandshell Active code page: 936 and then the characters supported by the code page can be found in `https://learn.microsoft.com/en-us/windows/win32/intl/code-page-identifiers `__. For example, the characters supported by the encoding corresponding to code page 936 are: ANSI/OEM Simplified Chinese (PRC, Singapore); Chinese Simplified (GB2312). For Ubuntu Linux and macOS users, whether using the Perl script or the executable file, the options support UTF-8 characters. dos2unix linebreak adjustment ----------------------------- .. describe:: dos2unixlinebreaks:integer If you use ``latexindent.pl`` on a dos-based Windows file on Linux then you may find that trailing horizontal space is not removed as you hope. In such a case, you may wish to try setting ``dos2unixlinebreaks`` to 1 and employing, for example, the following command. .. code-block:: latex :class: .commandshell latexindent.pl -y="dos2unixlinebreaks:1" myfile.tex See (“Windows Line Breaks on Linux Prevent Removal of White Space from End of Line” n.d.) for further dertails. Thanks ------ I first created ``latexindent.pl`` to help me format chapter files in a big project. After I blogged about it on the TeX stack exchange (“A Perl Script for Indenting Tex Files” n.d.) I received some positive feedback and follow-up feature requests. A big thank you to Harish Kumar (Kumar 2013) who helped to develop and test the initial versions of the script. The ``YAML``-based interface of ``latexindent.pl`` was inspired by the wonderful ``arara`` tool; any similarities are deliberate, and I hope that it is perceived as the compliment that it is. Thank you to Paulo Cereda and the team for releasing this awesome tool; I initially worried that I was going to have to make a GUI for ``latexindent.pl``, but the release of ``arara`` has meant there is no need. There have been several contributors to the project so far (and hopefully more in the future!); thank you very much to the people detailed in :numref:`sec:contributors` for their valued contributions, and thank you to those who report bugs and request features at (“Home of Latexindent.pl” n.d.). -------------- .. container:: references hanging-indent :name: refs .. container:: :name: ref-anacoda “Anacoda.” n.d. Accessed December 22, 2021. https://www.anaconda.com/products/individual. .. container:: :name: ref-cmhblog “A Perl Script for Indenting Tex Files.” n.d. Accessed January 23, 2017. http://tex.blogoverflow.com/2012/08/a-perl-script-for-indenting-tex-files/. .. container:: :name: ref-conda “Conda Forge.” n.d. Accessed December 22, 2021. https://github.com/conda-forge/miniforge. .. container:: :name: ref-cpan “CPAN: Comprehensive Perl Archive Network.” n.d. Accessed January 23, 2017. http://www.cpan.org/. .. container:: :name: ref-dumperdemo “Data Dumper Demonstration.” n.d. Accessed June 18, 2021. https://stackoverflow.com/questions/7466825/how-do-you-sort-the-output-of-datadumper. .. container:: :name: ref-dumper “Data::Dumper Module.” n.d. Accessed June 18, 2021. https://perldoc.perl.org/Data::Dumper. .. container:: :name: ref-jacobo-diaz-hidden-config Diaz, Jacobo. 2014. “Hiddenconfig.” July 21, 2014. https://github.com/cmhughes/latexindent.pl/pull/18. .. container:: :name: ref-eggplants eggplants. 2022. “Add Dockerfile and Its Updater/Releaser.” June 12, 2022. https://github.com/cmhughes/latexindent.pl/pull/370. .. container:: :name: ref-tdegeusprecommit Geus, Tom de. 2022. “Adding Perl Installation + Pre-Commit Hook.” January 21, 2022. https://github.com/cmhughes/latexindent.pl/pull/322. .. container:: :name: ref-holzhausprecommit Holthuis, Jan. 2022. “Fix Pre-Commit Usage.” March 31, 2022. https://github.com/cmhughes/latexindent.pl/pull/354. .. container:: :name: ref-latexindent-home “Home of Latexindent.pl.” n.d. Accessed January 23, 2017. https://github.com/cmhughes/latexindent.pl. .. container:: :name: ref-vscode-yaml-demo “How to Create Your Own Auto-Completion for Json and Yaml Files on Vs Code with the Help of Json Schema.” n.d. Accessed January 1, 2022. https://dev.to/brpaz/how-to-create-your-own-auto-completion-for-json-and-yaml-files-on-vs-code-with-the-help-of-json-schema-k1i. .. container:: :name: ref-condainstallubuntu “How to Install Anaconda on Ubuntu?” n.d. Accessed January 21, 2022. https://askubuntu.com/questions/505919/how-to-install-anaconda-on-ubuntu. .. container:: :name: ref-jun-sheaf J., Randolf. 2020. “Alpine-Linux Instructions.” August 10, 2020. https://github.com/cmhughes/latexindent.pl/pull/214. .. container:: :name: ref-jasjuang Juang, Jason. 2015. “Add in Path Installation.” November 24, 2015. https://github.com/cmhughes/latexindent.pl/pull/38. .. container:: :name: ref-harish Kumar, Harish. 2013. “Early Version Testing.” November 10, 2013. https://github.com/harishkumarholla. .. container:: :name: ref-cmhughesio “Latexindent.pl Ghcr (Github Container Repository) Location.” n.d. Accessed June 12, 2022. https://github.com/cmhughes?tab=packages. .. container:: :name: ref-nehctargl Nehctargl. 2022. “Added Support for the Xdg Specification.” December 23, 2022. https://github.com/cmhughes/latexindent.pl/pull/397. .. container:: :name: ref-perlbrew “Perlbrew.” n.d. Accessed January 23, 2017. http://perlbrew.pl/. .. container:: :name: ref-pre-commithome “Pre-Commit: A Framework for Managing and Maintaining Multi-Language Pre-Commit Hooks.” n.d. Accessed January 8, 2022. https://pre-commit.com/. .. container:: :name: ref-condainstallhelp “Solving Environment: Failed with Initial Frozen Solve. Retrying with Flexible Solve.” n.d. Accessed January 21, 2022. https://github.com/conda/conda/issues/9367#issuecomment-558863143. .. container:: :name: ref-vscode-yaml-extentions “VSCode Yaml Extension.” n.d. Accessed January 1, 2022. https://marketplace.visualstudio.com/items?itemName%20=%20redhat.vscode-yaml. .. container:: :name: ref-bersbersbers “Windows Line Breaks on Linux Prevent Removal of White Space from End of Line.” n.d. Accessed June 18, 2021. https://github.com/cmhughes/latexindent.pl/issues/256. .. [1] If you’re not sure where to put ``indentconfig.yaml``, don’t worry ``latexindent.pl`` will tell you in the log file exactly where to put it assuming it doesn’t exist already. .. [2] Windows users may find that they have to end ``.yaml`` files with a blank line