Add documentation page for templates

Author: tstenner

README.md

@@ -11,14 +11,14 @@ The file format used by the LabRecorder is XDF. This is a new open general-purpo
 # Usage
 
 The LabRecorder displays a list of currently present device streams under "Record from Streams". If you have turned on a device after you have already started the recorder, click the "Refresh" button to update the list (this takes ca. 2 seconds). For testing there are several simple dummy devices in the [examples folder](https://github.com/labstreaminglayer/App-Examples) (for example SendData<!--, SendStringMarkers, and SendDataSimple-->); you can start any of these programs (and follow the on-screen instructions, if any) to bring a stream online. After you have done so, clicking refresh in the recorder should display the streams in green. If you cannot see streams that are provided on another computer, read the section Network Troubleshooting on the NetworkConnectivity page. You can select which streams you want to record from and which not by checking the check boxes next to them. By default any present stream will be initially checked, as in the follwing picture.
-> ![labrecorder-default.png](screenshots/labrecorder-default.png)
+> ![labrecorder-default.png](doc/labrecorder-default.png)
 
 The entry in "Storage Location" shows you the file name (or file name template) where your recording will be stored. You can change this by clicking the browse button. If this string contains any occurrence of the placeholder `%n`, it will be replaced by the value in the "Experiment Number" field. The value in that field is "smart": when you start the recorder or load a configuration file, this field will be set automatically to the lowest number for which no directory exists yet on disk. If the string contains any occurrence of `%b`, it will be substituted by the the selected string under "Current experiment block". This list of pre-defined block names is feature for advanced uses that can be customized by editing the `default_config.cfg` configuration file (or creating a new one). If the respective directory does not yet exist, it will be created automatically (except if you do not have the permissions to create it). If the file that you are trying to record to already exists, the existing file will be renamed (the string `_oldX` will be appended where X is the lowest number that is not yet occupied by another existing file). This way, it is impossible to accidentally overwrite data.
 
 <!--If the checkbox "Enable scripted actions" is checked, then scripted actions that are defined in your current config file will be automatically invoked when you click Start, Stop, or select a block. This check box is by normally unchecked unless you have custom-tailored a configuration to your experiment or experimentation environment.-->
 
 Click "Start" to start a recording. If everything goes well, the status bar will now display the time since you started the recording, and more importantly, the current file size (the number before the kb) will grow slowly. This is a way to check whether you are still in fact recording data. The recording program cannot be closed while you are recording (as a safety measure). This looks like in the following picture.
-> ![labrecorder-running.png](screenshots/labrecorder-running.png)
+> ![labrecorder-running.png](doc/labrecorder-running.png)
 
 When you are done recording, click the "Stop" button. You can now close the program. You can now import and inspect your recording, see for example ImportingRecordingsInMatlab.
 

doc/controls.png

@@ -0,0 +1,34 @@
+# Working with file name templates
+
+Most sites have specific formats for paths and file names or even switched to
+the [BIDS](#BIDS) standard. LabRecorder makes it easier to file and name your
+correctly by providing path and file name templates.
+
+All variables (starting with `%`) are replaced with the corresponding field's
+contents upon starting the recording.
+
+Lets assume your institution requires your file to be saved in
+`/mnt/server/studies/your_name/<participant_id>/<session>/<task>.xdf`.
+
+You can let LabRecorder create the files and folders with the following
+settings (configuration file keys are `highlighted`):
+
+- `StudyRoot`=`/mnt/server/studies/your_name`
+- File Name / Template: `%p/%s/%b.xdf`
+- `SessionBlocks`=`"Task 1", "Resting State", "Task 2"`
+
+Before recording, you only need to fill in the fields you're using.
+The paths in the File Name Template are created automatically.
+
+The final folder and file path are previewed in the `Saving to...` box (above
+`16` in the screenshot).
+
+## BIDS
+
+[BIDS](https://bids.neuroimaging.io/) is a set of conventions for organizing
+your research data.
+Checking the `BIDS` checkbox (`10` in the screenshot) automatically generates
+the correct File Name
+Template depending on which variables you set in the fields below.
+
+![LabRecorder Inputs](controls.png)