Website: split up variables section & adjust for argument split

Split up the "Variables" section, and adjust the wording for the splitting
of `{blender}` into `{blender}` and `{blenderArgs}` (rFe5a20425c474).

web/project-website/content/usage/variables/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Variables & Multi-Platform Support
+title: Variables
 weight: 2
 ---
 
@@ -8,7 +8,7 @@ mixed-platform render farms, Flamenco uses *variables*.
 
 Each variable consists of:
 
-- Its **name**: just a sequence of letters, like `ffmpeg` or `whateveryouwant`.
+- Its **name**: just a sequence of letters, like `blender` or `whateveryouwant`.
 - Its **values**: per *platform* and *audience*, described below.
 
 The variables are configured in `flamenco-manager.yaml`.
@@ -20,15 +20,25 @@ variables:
   blender:
     values:
     - platform: linux
-      value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender -b -y
+      value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
     - platform: windows
-      value: B:\Downloads\blenders\blender-3.2.2-release\blender.exe -b -y
+      value: B:\Downloads\blenders\blender-3.2.2-release\blender.exe
     - platform: darwin
-      value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender -b -y
+      value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
 ```
 
-Whenever a Worker gets a task that contains the string `{blender}`, that'll be
+Whenever a Worker gets a task that contains `{blender}`, that'll be replaced by
-replaced by the appropriate value for that worker.
+the appropriate value for that worker.
+
+{{< hint type=note title="Custom Job Types" >}}
+This documentation section focuses on pre-existing variables, `blender` and
+`blenderArgs`. There is nothing special about these. Apart from being part of
+Flamenco's default configuration, that is. When you go the more advanced route
+of creating your own [custom job types][jobtypes] you're free to create your own
+set of variables to suit your needs.
+
+[jobtypes]: {{< ref "usage/job-types" >}}
+{{< /hint >}}
 
 ## Platform
 
@@ -40,16 +50,6 @@ on the platform. The variables system allows you to configure this.
 The platform can be `windows`, `linux`, or `darwin` for macOS. Other platforms
 are also allowed, if you happen to use them in your farm.
 
-{{< hint type=note title="Custom Job Types" >}}
-This documentation section focuses on pre-existing variables, `blender` and
-`ffmpeg`. There is nothing special about these. Apart from being part of
-Flamenco's default configuration, that is. When you go the more advanced route
-of creating your own [custom job types][jobtypes] you're free to create your own
-set of variables to suit your needs.
-
-[jobtypes]: {{< ref "usage/job-types" >}}
-{{< /hint >}}
-
 ## Audience
 
 The audience of a value is who that value is for: `workers`, `users`, or `all`
@@ -64,126 +64,3 @@ might be different from where users go to pick them up.
 - `users`: values are used when submitting jobs from Blender and showing them in
   the web interface.
 - `workers`: values that are used when sending tasks to workers.
-
-## Blender and FFmpeg
-
-The location of Blender and FFmpeg on the Worker, as well as their default
-arguments, can be configured via the `blender` and `ffmpeg` variables.
-
-- If the Blender or FFmpeg location is just plain `blender` resp. `ffmpeg`, the
-  worker will try and find those by itself. How this is done is different for
-  the two programs, and explained below.
-- In other cases, it is assumed to be a path and the worker will just use it as
-  configured.
-
-### Blender
-
-The built-in [job types][jobtypes] use `{blender}` instead of hard-coding a
-particular command. This makes it possible to configure your own Blender
-command. The Worker has a few strategies for finding Blender, described below.
-
-[jobtypes]: {{< ref "usage/job-types" >}}
-
-#### Just `blender`
-
-If the command is configured to be just `blender` with some arguments, for
-example `blender -b -y`, some "smartness" will kick in. It will pick the first
-Blender it finds in this order:
-
-1. On Windows, the worker will figure out which Blender is associated with blend
-   files. In other words, it will run whatever Blender runs when you
-   double-click a `.blend` file. On other platforms this step is skipped.
-2. The locations listed in the `PATH` environment variable are searched to find
-   Blender. This should run whatever Blender starts when you enter the `blender`
-   command in a shell.
-3. If none of the above result in a usable Blender, the worker will fail its task.
-
-#### An explicit path
-
-If the command is configured to anything other than `blender` (arguments
-excluded), it is assumed to be a path to the Blender executable. For an example,
-see the top of this page.
-
-### FFmpeg
-
-Similar to `{blender}`, described above, the `{ffmpeg}` variable can be used to
-configure both which FFmpeg executable to use, and which additional parameters
-to pass.
-
-#### Just `ffmpeg`
-
-If the command is configured to be just `ffmpeg` with some arguments, for
-example `ffmpeg -hide_banner`, the worker will try to use the bundled FFmpeg.
-This is the default behavior, so if you do not have any `ffmpeg` variable
-defined, this is what will happen.
-
-The worker looks next to the `flamenco-worker` executable for a `tools`
-directory. Given the current OS (`windows`, `linux`, `darwin`, etc.) and
-architecture (`amd64`, `x86`, etc.) it will try to find the most-specific one
-for your system in that `tools` directory.
-
-The worker tries the following ones; the first one found is used:
-
-1. `ffmpeg-OS-ARCHITECTURE`, for example `ffmpeg-windows-amd64.exe` or `ffmpeg-linux-x86`
-2. `ffmpeg-OS`, for example `ffmpeg-windows.exe` or `ffmpeg-linux`
-3. `ffmpeg`, so `ffmpeg.exe` on Windows and `ffmpeg` on any other platform.
-
-#### An explicit path
-
-If the command is configured to anything other than `ffmpeg` (arguments
-excluded), it is assumed to be a path to the FFmpeg executable.
-
-Example configuration from `flamenco-manager.yaml`:
-
-```yaml
-variables:
-  ffmpeg:
-    values:
-    - platform: linux
-      value: /media/shared/tools/ffmpeg-5.0/ffmpeg-linux
-    - platform: windows
-      value: S:\tools\ffmpeg-5.0\ffmpeg.exe
-    - platform: darwin
-      value: /Volumes/shared/tools/ffmpeg-5.0/ffmpeg-macos
-```
-
-## Two-way Variables
-
-Two-way variables are there to support mixed-platform Flamenco farms. Basically
-they perform *path prefix replacement*.
-
-Let's look at an example configuration:
-
-```yaml
-variables:
-  shared_storage:
-    is_twoway: true
-    values:
-    - platform: linux
-      value: /media/shared/flamenco
-    - platform: windows
-      value: F:\flamenco
-    - platform: darwin
-      value: /Volumes/shared/flamenco
-```
-
-The difference with regular variables is that regular variables are one-way, so
-only `{variablename}` is replaced with the value. Two-way variables go both ways, as follows:
-
-- When submitting a job from a Linux workstation, `/media/shared/flamenco` (the
-  variable's value for Linux) will be replaced with `{shared_storage}`.
-- When sending a task for this job to a Windows worker, `{shared_storage}` will
-  be replaced with `F:\flamenco`.
-
-Let's look at a more concrete example, with the same configuration as above.
-
-- Alice runs Blender on **macOS**. She submits a job that has its render output set
-  to `/Volumes/shared/flamenco/renders/shot_010_a_anim`.
-- Flamenco recognises the path, and stores the job as rendering to
-  `{shared_storage}/renders/shot_010_a_anim`.
-- Bob's computer is running the Worker on **Windows**, so when it receives a render
-  task Flamenco will tell it to render to
-  `F:\flamenco\renders\shot_010_a_anim`.
-- Carol's computer is also running a worker, but on **Linux**. When it receives a
-  render task, Flamenco will tell it to render to
-  `/media/shared/flamenco/renders/shot_010_a_anim`.

web/project-website/content/usage/variables/blender.md

@@ -0,0 +1,61 @@
+---
+title: Blender
+---
+
+The location of Blender *on the Worker*, as well as its default arguments, can be
+configured via the `blender` and `blenderArgs` variables.
+
+- If the Blender location is just plain `blender`, the worker will try and find
+  those by itself. How this is done is different for the two programs, and
+  explained below.
+- In other cases, it is assumed to be a path and the worker will just use it as
+  configured.
+
+Here is an example configuration, which is part of `flamenco-manager.yaml`:
+
+```yaml
+variables:
+  blender:
+    values:
+    - platform: linux
+      value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
+    - platform: windows
+      value: B:\Downloads\blenders\blender-3.2.2-release\blender.exe
+    - platform: darwin
+      value: /home/sybren/Downloads/blenders/blender-3.2.2-release/blender
+  blenderArgs:
+    values:
+    - platform: all
+      value: -b -y
+```
+
+## Just `blender`
+
+If the `{blender}` variable is configured to be just `blender` some "smartness"
+will kick in. It will pick the first Blender it finds in this order:
+
+1. On Windows, the worker will figure out which Blender is associated with blend
+   files. In other words, it will run whatever Blender runs when you
+   double-click a `.blend` file. On other platforms this step is skipped.
+2. The locations listed in the `PATH` environment variable are searched to find
+   Blender. This should run whatever Blender starts when you enter the `blender`
+   command in a shell.
+3. If none of the above result in a usable Blender, the worker will fail its task.
+
+## An explicit path
+
+If the command is configured to anything other than `blender`, it is assumed to
+be a path to the Blender executable.
+
+## Setting Arguments
+
+The `{blenderArgs}` variable can be used to provide arguments to Blender that
+are used on every invocation. Flamenco uses these by default:
+
+- `-b`: run Blender in the background, so that it doesn't pop up a window.
+- `-y`: allow executing Python code without any confirmation, which is often
+  necessary for production rigs to work.
+
+More can be found in Blender's [Command Line Arguments documentation][blendcli].
+
+[blendcli]: https://docs.blender.org/manual/en/latest/advanced/command_line/arguments.html

web/project-website/content/usage/variables/ffmpeg.md

@@ -0,0 +1,18 @@
+---
+title: FFmpeg
+---
+
+FFmpeg is bundled with Flamenco, and at the moment it cannot be configured to
+use any other install of FFmpeg. This is intended to be added in some future,
+but there is no timeline when this will happen (patches welcome!).
+
+The worker looks next to the `flamenco-worker` executable for a `tools`
+directory. Given the current OS (`windows`, `linux`, `darwin`, etc.) and
+architecture (`amd64`, `x86`, etc.) it will try to find the most-specific one
+for your system in that `tools` directory.
+
+The worker tries the following ones; the first one found is used:
+
+1. `ffmpeg-OS-ARCHITECTURE`, for example `ffmpeg-windows-amd64.exe` or `ffmpeg-linux-x86`
+2. `ffmpeg-OS`, for example `ffmpeg-windows.exe` or `ffmpeg-linux`
+3. `ffmpeg`, so `ffmpeg.exe` on Windows and `ffmpeg` on any other platform.

web/project-website/content/usage/variables/multi-platform.md

@@ -0,0 +1,48 @@
+---
+title: Two-way Variables for Multi-Platform Support
+---
+
+Two-way variables are there to support mixed-platform Flamenco farms. Basically
+they perform *path prefix replacement*.
+
+Let's look at an example configuration:
+
+```yaml
+variables:
+  my_storage:
+    is_twoway: true
+    values:
+    - platform: linux
+      value: /media/shared/flamenco
+    - platform: windows
+      value: F:\flamenco
+    - platform: darwin
+      value: /Volumes/shared/flamenco
+```
+
+The difference with regular variables is that regular variables are one-way:
+`{variablename}` is replaced with the value, and that's it.
+
+Two-way variables go both ways, as follows:
+
+- When submitting a job, values are replaced with variables.
+- When sending a task to a worker, variables are replaced with values again.
+
+This may seem like a lot of unnecessary work. After all, why go through the
+trouble of replacing in one direction, when later the opposite is done? The
+power lies in the fact that each replacement step can target a different
+platform. In the first step the value for Linux can be recognised, and in the
+second step the value for Windows can be put in its place.
+
+Let's look at a more concrete example, based on the configuration shown above.
+
+- Alice runs Blender on **macOS**. She submits a job that has its render output set
+  to `/Volumes/shared/flamenco/renders/shot_010_a_anim`.
+- Flamenco recognises the path, and stores the job as rendering to
+  `{my_storage}/renders/shot_010_a_anim`.
+- Bob's computer is running the Worker on **Windows**, so when it receives a render
+  task Flamenco will tell it to render to
+  `F:\flamenco\renders\shot_010_a_anim`.
+- Carol's computer is also running a worker, but on **Linux**. When it receives a
+  render task, Flamenco will tell it to render to
+  `/media/shared/flamenco/renders/shot_010_a_anim`.