[lua scripts] created manual from script comments

[lua scripts api] created manual from embedded library documentation

[lua api] created stub to contain lua api manual

content/_index.html

@@ -1,6 +1,17 @@
 ---
 title: Home
-id: lua-documentation
+id: darktable Lua documentation
 draft: false
 author: "people"
 ---
+
+<p><img src="./images/darktable-logo.png" width="50%"></p>
+
+<p>
+darktable is an open source photography workflow application and raw developer &mdash; a virtual lighttable and darkroom for photographers. It manages your digital negatives in a database, lets you view them through a zoomable lighttable and enables you to develop and enhance your raw images.
+</p>
+<p>
+darktable contains an embedded interpreter for the <a href="https://www.lua.org">Lua</a> programming language which provides the ability to modify and extend darktable's functionality.  This documentation set contains descriptions of the extensions and Application Program Interface (API).
+<p>
+The source repository for this documentation may be found at <a href="https://github.com/darktable-org/luadocs.git">https://github.com/darktable-org/luadocs.git</a>. Any feedback relating to this documentation can be provided by creating a <a href="https://github.com/darktable-org/luadocs/issues/new">ticket</a> or a pull request against this repository.
+</p>

content/lua.api/_index.html

@@ -0,0 +1,11 @@
+---
+title: Lua API Manual
+id: Lua Scripts Manual
+weight: 30
+draft: false
+author: "people"
+---
+
+<p>
+The Lua API manual is currently being converted.
+</p>

content/lua.scripts.api.manual/_index.html

@@ -0,0 +1,10 @@
+---
+title: Lua Script Libraries API Manual
+id: Lua Scripts API Manual
+weight: 20
+draft: false
+author: "people"
+---
+
+<p><img src="./images/darktable-logo.png" width="50%"></p>
+

content/lua.scripts.api.manual/dtutils.debug/_index.md

@@ -0,0 +1,7 @@
+---
+title: dtutils.debug
+id: dtutils-debug
+weight: 20
+draft: false
+author: "people"
+---

content/lua.scripts.api.manual/dtutils.debug/details.md

@@ -0,0 +1,59 @@
+---
+title: details
+id: details
+weight: 10
+draft: false
+author: "people"
+---
+
+## NAME
+
+dtutils.debug
+
+## SYNOPSIS
+
+debugging helpers used in developing darktable lua scripts
+
+## USAGE
+```
+require "lib/dtutils.debug"
+```
+## DESCRIPTION
+
+dtutils.debug provides an interface to the darktable debugging routines.
+
+## RETURN VALUE
+
+**dd** - _library_ - the darktable lua debugging helpers
+
+## FUNCTIONS
+
+### [dprint](dprint.md)
+
+pass a variable to darktable.debug.dump and print the results to stdout
+
+### [new_tracepoint](new_tracepoint.md)
+
+create a function returning a tracepoint
+
+### [terse_dump](terse_dump.md)
+
+set darktable.debug.known to shorten all image dumps to a single line
+
+### [tracepoint](tracepoint.md)
+
+print out a tracepoint and dump the arguments
+
+## LICENSE
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+

content/lua.scripts.api.manual/dtutils.debug/dprint.md

@@ -0,0 +1,27 @@
+---
+title: dprint
+id: dprint
+weight: 20
+draft: false
+author: "people"
+---
+
+## NAME
+
+dprint
+
+## SYNOPSIS
+
+pass a variable to darktable.debug.dump and print the results to stdout
+
+## USAGE
+```
+local dd = require "lib/dtutils.debug"
+dd.dprint(var)
+```
+**var** - _variable_ - any variable that you want to see the contents of
+
+## DESCRIPTION
+
+**dprint** is a wrapper around **darktable.debug.dump**, will directly print to stdout,
+same calling convention

content/lua.scripts.api.manual/dtutils.debug/new_tracepoint.md

@@ -0,0 +1,42 @@
+---
+title: new_tracepoint
+id: new-tracepoint
+weight: 30
+draft: false
+author: "people"
+---
+
+## NAME
+
+new_tracepoint
+
+## SYNOPSIS
+
+create a function returning a tracepoint
+
+## USAGE
+```
+local dd = require "lib/dtutils.debug"
+local result = dd.new_tracepoint(name, ...)
+```
+**name** - _string_ - the name of the tracepoint to print out  
+**...** - _arguments_ - variables to dump the contents of
+
+## DESCRIPTION
+
+**new_tracepoint** returns a tracepoint function with the given name.
+This is mainly used to debug callbacks.
+
+## RETURN VALUE
+
+**result** - _function_ - a function that returns the result of a tracepoint
+
+## EXAMPLE
+```
+register_event(event, dd.new_tracepoint("hit callback"))
+```
+will print the following each time the callback is called
+```
+**** hit callback ****
+<all the callback's parameters dumped>
+```

content/lua.scripts.api.manual/dtutils.debug/terse_dump.md

@@ -0,0 +1,25 @@
+---
+title: terse_dump
+id: terse-dump
+weight: 40
+draft: false
+author: "people"
+---
+
+## NAME
+
+terse_dump
+
+## SYNOPSIS
+
+set darktable.debug.known to shorten all image dumps to a single line
+
+## USAGE
+```
+local dd = require "lib/dtutils.debug"
+dd.terse_dump()
+```
+## DESCRIPTION
+
+**terse_dump** sets **darktable.debug.known** to shorten all images to a single line.
+If you don't need to debug the content of images, this will avoid them flooding your logs.

content/lua.scripts.api.manual/dtutils.debug/tracepoint.md

@@ -0,0 +1,32 @@
+---
+title: tracepoint
+id: tracepoint
+weight: 50
+draft: false
+author: "people"
+---
+
+## NAME
+
+tracepoint
+
+## SYNOPSIS
+
+print out a tracepoint and dump the arguments
+
+## USAGE
+```
+local dd = require "lib/dtutils.debug"
+local result = dd.tracepoint(name, ...)
+```
+**name** - _string_ - the name of the tracepoint to print out  
+**...** - _arguments_ - variables to dump the contents of
+
+## DESCRIPTION
+
+**tracepoint** prints its name and dumps its parameters using
+**darktable.debug**.
+
+## RETURN VALUE
+
+**result** - _..._ - the supplied argument list

content/lua.scripts.api.manual/dtutils.file/_index.md

@@ -0,0 +1,7 @@
+---
+title: dtutils.file
+id: dtutils-file
+weight: 30
+draft: false
+author: "people"
+---

content/lua.scripts.api.manual/dtutils.file/check_if_bin_exists.md

@@ -0,0 +1,35 @@
+---
+title: check_if_bin_exists
+id: check_if_bin_exists
+weight: 20
+draft: false
+author: "people"
+---
+
+## NAME
+
+check_if_bin_exists
+
+## SYNOPSIS
+
+check if an executable exists
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.check_if_bin_exists(bin)
+```
+**bin** - _string_ - the binary to check for
+
+## DESCRIPTION
+
+**check_if_bin_exists** checks to see if the specified binary exists.
+**check_if_bin_exists** first checks to see if a preference for the binary has been
+registered and uses that if found.  The presence of the file is verified, then 
+quoted and returned.  If no preference is specified and the operating system is
+linux then the which command is used to check for a binary in the path.  If found
+that path is returned.  If no binary is found, false is returned.
+
+## RETURN VALUE
+
+**result** - _string_ - the sanitized path of the binary, false if not found

content/lua.scripts.api.manual/dtutils.file/check_if_file_exists.md

@@ -0,0 +1,30 @@
+---
+title: check_if_file_exists
+id: check_if_file_exists
+weight: 30
+draft: false
+author: "people"
+---
+
+## NAME
+
+check_if_file_exists
+
+## SYNOPSIS
+
+check if a file or path exist
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.check_if_file_exists(filepath)
+```
+**filepath** - _string_ - a file or path to check
+
+## DESCRIPTION
+
+**check_if_file_exists** checks to see if a file or path exists.
+
+## RETURN VALUE
+
+**result** - _boolean_ - true if the file or path exists, false if it doesn't.

content/lua.scripts.api.manual/dtutils.file/chop_filetype.md

@@ -0,0 +1,30 @@
+---
+title: chop_filetype
+id: chop_filetype
+weight: 40
+draft: false
+author: "people"
+---
+
+## NAME
+
+chop_filetype
+
+## SYNOPSIS
+
+remove a filetype from a filename
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.chop_filetype(path)
+```
+**path** - _string_ - a filename with or without a path
+
+## DESCRIPTION
+
+**chop_filetype** removes the filetype from the filename.
+
+## RETURN VALUE
+
+**result** - _string_ - the path and filename without the filetype

content/lua.scripts.api.manual/dtutils.file/create_unique_filename.md

@@ -0,0 +1,37 @@
+---
+title: create_unique_filename
+id: create_unique_filename
+weight: 50
+draft: false
+author: "people"
+---
+
+## NAME
+
+create_unique_filename
+
+## SYNOPSIS
+
+create a unique filename from the supplied argument
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.create_unique_filename(filepath)
+```
+**filepath** - _string_ - the path and filename requested
+
+## DESCRIPTION
+
+**create_unique_filename** takes a requested filepath and checks to see if
+it exists.  If if doesn't then it's returned intact.  If it already exists, then a two
+digit increment is added to the filename and it is tested again.  The increment keeps 
+increasing until either a unique filename is found or there have been 100 attempts.
+
+## RETURN VALUE
+
+**result** - _string_ - the incremented filename
+
+## LIMITATIONS
+
+**create_unique_filename** will only attempt 100 increments.

content/lua.scripts.api.manual/dtutils.file/details.md

@@ -0,0 +1,116 @@
+---
+title: details
+id: details
+weight: 10
+draft: false
+author: "people"
+---
+
+## NAME
+
+details
+
+## SYNOPSIS
+
+common darktable lua file functions
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+```
+## DESCRIPTION
+
+The **dtutils.file** library provides common file manipulation functions used in
+constructing darktable lua scripts
+
+## RETURN VALUE
+
+**df** - _library_ - the file functions
+
+## FUNCTIONS
+
+### [check_if_bin_exists](check_if_bin_exists.md)
+
+check if an executable exists
+
+### [check_if_file_exists](check_if_file_exists.md)
+
+check if a file or path exist
+
+### [chop_filetype](chop_filetype.md)
+
+remove a filetype from a filename
+
+### [create_unique_filename](create_unique_filename.md)
+
+create a unique filename from the supplied argment
+
+### [executable_path_widget](executable_path_widget.md)
+
+create a widget to get executable path preferences
+
+### [file_copy](file_copy.md)
+
+copy a file to another name/location
+
+### [file_move](file_move.md)
+
+move a file from one directory to another
+
+### [filename_increment](filename_increment.md)
+
+add a two digit increment to a filename
+
+### [get_basename](get_basename.md)
+
+get the filename without the path or extension
+
+### [get_executable_path_preference](get_executable_path_preference.md)
+
+return the path to an executable from a preference
+
+### [get_filename](get_filename.md)
+
+get the filename and extension from a file path
+
+### [get_filetype](get_filetype.md)
+
+get the filetype from a filename
+
+### [get_path](get_path.md)
+
+get the path from a file path
+
+### [mkdir](mkdir.md)
+
+create the directory(ies) if they do not already exists
+
+### [rmdir](rmdir.md)
+
+recursively remove a directory
+
+### [sanitize_filename](sanitize_filename.md)
+
+make a filename safe to pass as an argument
+
+### [set_executable_path_preference](set_executable_path_preference.md)
+
+set a preference for the path to an executable
+
+### [split_filepath](split_filepath.md)
+
+split a filepath into parts
+
+## LICENSE
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+

content/lua.scripts.api.manual/dtutils.file/executable_path_widget.md

@@ -0,0 +1,33 @@
+---
+title: executable_path_widget
+id: executable_path_widget
+weight: 60
+draft: false
+author: "people"
+---
+
+## NAME
+
+executable_path_widget
+
+## SYNOPSIS
+
+create a widget to get executable path preferences
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local widget = df.executable_path_widget(executables)
+```
+**executables** - _table_ - a table of strings that are executable names
+
+## DESCRIPTION
+
+**executable_path_widget** takes a table of executable names
+and builds a set of file selector widgets to get the path to the executable. 
+The resulting widgets are wrapped in a box widget and returned.
+
+## RETURN VALUE
+
+**widget** - _widget_ - a widget containing a file selector widget for
+each executable.

content/lua.scripts.api.manual/dtutils.file/file_copy.md

@@ -0,0 +1,32 @@
+---
+title: file_copy
+id: file_copy
+weight: 70
+draft: false
+author: "people"
+---
+
+## NAME
+
+file_copy
+
+## SYNOPSIS
+
+copy a file to another name/location
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.file_copy(fromFile, toFile)
+```
+**fromFile** - _string_ - name of file to copy from  
+**toFile** - _string_ - name of file to copy to
+
+## DESCRIPTION
+
+copy a file using a succession of methods from operating system
+to a pure lua solution
+
+## RETURN VALUE
+
+**result** - _boolean_ - nil on error, true on success

content/lua.scripts.api.manual/dtutils.file/file_move.md

@@ -0,0 +1,32 @@
+---
+title: file_move
+id: file_move
+weight: 80
+draft: false
+author: "people"
+---
+
+## NAME
+
+file_move
+
+## SYNOPSIS
+
+move a file from one directory to another
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.file_move(fromFile, toFile)
+```
+**fromFile** - _string_ - name of the original file  
+**toFile** - _string_ - the new file location and name
+
+## DESCRIPTION
+
+Move a file from one place to another.  Try a succession of methods from
+builtin to operating system to a pure lua solution.
+
+## RETURN VALUE
+
+**result** - _boolean_ - nil on error, some value on success

content/lua.scripts.api.manual/dtutils.file/filename_increment.md

@@ -0,0 +1,37 @@
+---
+title: filename_increment
+id: filename_increment
+weight: 90
+draft: false
+author: "people"
+---
+
+## NAME
+
+filename_increment
+
+## SYNOPSIS
+
+add a two digit increment to a filename
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.filename_increment(filepath)
+```
+**filepath** - _string_ - filename to increment
+
+## DESCRIPTION
+
+**filename_increment** solves the problem of filename conflict by adding an 
+increment to the filename.  If the supplied filename has no increment then 
+"01" is added to the basename.  If the filename already has an increment, then
+1 is added to it and the filename returned.
+
+## RETURN VALUE
+
+**result** - _string_ - the incremented filename
+
+## LIMITATIONS
+
+The filename will be incremented to a maximum of 99.

content/lua.scripts.api.manual/dtutils.file/get_basename.md

@@ -0,0 +1,30 @@
+---
+title: get_basename
+id: get_basename
+weight: 100
+draft: false
+author: "people"
+---
+
+## NAME
+
+get_basename
+
+## SYNOPSIS
+
+get the filename without the path or extension
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.get_basename(filepath)
+```
+**filepath** - _string_ - path and filename
+
+## DESCRIPTION
+
+**get_basename** returns the name of the file without the path or filetype.
+
+## RETURN VALUE
+
+**result** - _string_ - the basename of the file

content/lua.scripts.api.manual/dtutils.file/get_executable_path_preference.md

@@ -0,0 +1,35 @@
+---
+title: get_executable_path_preference
+id: get_executable_path_preference
+weight: 110
+draft: false
+author: "people"
+---
+
+## NAME
+
+get_executable_path_preference
+
+## SYNOPSIS
+
+return the path to an executable from a preference
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.get_executable_path_preference(executable)
+```
+**executable** - _string_ - the name of the executable to get the path for
+
+## DESCRIPTION
+
+**get_executable_path_preference** returns the path preference to
+the requested executable.
+
+## RETURN VALUE
+
+**result** - _string_ - path to the executable
+
+## LIMITATIONS
+
+executable should be the basename of the executable without extensions

content/lua.scripts.api.manual/dtutils.file/get_filename.md

@@ -0,0 +1,30 @@
+---
+title: get_filename
+id: get_filename
+weight: 120
+draft: false
+author: "people"
+---
+
+## NAME
+
+get_filename
+
+## SYNOPSIS
+
+get the filename and extension from a file path
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.get_filename(filepath)
+```
+**filepath** - _string_ - path and filename
+
+## DESCRIPTION
+
+**get_filename** strips the path from a filepath and returns the filename
+
+## RETURN VALUE
+
+**result** - _string_ - the file name and type

content/lua.scripts.api.manual/dtutils.file/get_filetype.md

@@ -0,0 +1,30 @@
+---
+title: get_filetype
+id: get_filetype
+weight: 130
+draft: false
+author: "people"
+---
+
+## NAME
+
+get_filetype
+
+## SYNOPSIS
+
+get the filetype from a filename
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.get_filetype(filepath)
+```
+**filepath** - _string_ - path and filename
+
+## DESCRIPTION
+
+**get_filetype** returns the filetype from the supplied filepath
+
+## RETURN VALUE
+
+**result** - _string_ - the filetype

content/lua.scripts.api.manual/dtutils.file/get_path.md

@@ -0,0 +1,30 @@
+---
+title: get_path
+id: get_path
+weight: 140
+draft: false
+author: "people"
+---
+
+## NAME
+
+get_path
+
+## SYNOPSIS
+
+get the path from a file path
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.get_path(filepath)
+```
+**filepath** - _string_ - path and filename
+
+## DESCRIPTION
+
+**get_path** strips the filename and filetype from a path and returns the path
+
+## RETURN VALUE
+
+**result** - _string_ - the path

content/lua.scripts.api.manual/dtutils.file/mkdir.md

@@ -0,0 +1,31 @@
+---
+title: mkdir
+id: mkdir
+weight: 150
+draft: false
+author: "people"
+---
+
+## NAME
+
+mkdir
+
+## SYNOPSIS
+
+create the directory(ies) if they do not already exist
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+df.mkdir(path)
+```
+**path** - _string_ - a directory path
+
+## DESCRIPTION
+
+**mkdir** creates directories if they do not already exist. It 
+creates parent directories if needed.
+
+## RETURN VALUE
+
+_**path** - string_ - a directory path

content/lua.scripts.api.manual/dtutils.file/rmdir.md

@@ -0,0 +1,30 @@
+---
+title: rmdir
+id: rmdir
+weight: 160
+draft: false
+author: "people"
+---
+
+## NAME
+
+rmdir
+
+## SYNOPSIS
+
+recursively remove a directory
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+df.rmdir(path)
+```
+**path** - _string_ - a directory path
+
+## DESCRIPTION
+
+**rmdir** allows directories to be removed recursively.
+
+## RETURN VALUE
+
+**path** - _string_ - a directory path

content/lua.scripts.api.manual/dtutils.file/sanitize_filename.md

@@ -0,0 +1,32 @@
+---
+title: sanitize_filename
+id: sanitize_filename
+weight: 170
+draft: false
+author: "people"
+---
+
+## NAME
+
+sanitize_filename
+
+## SYNOPSIS
+
+make a filename safe to pass as an argument
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local sanitized_filename = df.sanitize_filename(filename)
+```
+**filename** - _string_ - a filepath and filename
+
+## DESCRIPTION
+
+**sanitize_filename** places quotes around the filename in an
+operating system specific manner.  The result is safe to pass as 
+an argument to the operating system.
+
+## RETURN VALUE
+
+**sanitized_filename** - _string_ - quoted filename

content/lua.scripts.api.manual/dtutils.file/set_executable_path_preference.md

@@ -0,0 +1,28 @@
+---
+title: set_executable_path_preference
+id: set_executable_path_preference
+weight: 180
+draft: false
+author: "people"
+---
+
+## NAME
+
+set_executable_path_preference
+
+## SYNOPSIS
+
+set a preference for the path to an executable
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+df.set_executable_path_preference(executable, path)
+```
+**executable** - _string_ - the name of the executable to set the path for  
+**path** - _string_ - the path to the binary
+
+## DESCRIPTION
+
+**set_executable_path_preference** takes an executable name and path to the
+executable and registers the preference for later use.

content/lua.scripts.api.manual/dtutils.file/split_filepath.md

@@ -0,0 +1,31 @@
+---
+title: split_filepath
+id: split_filepath
+weight: 190
+draft: false
+author: "people"
+---
+
+## NAME
+
+split_filepath
+
+## SYNOPSIS
+
+split a filepath into parts
+
+## USAGE
+```
+local df = require "lib/dtutils.file"
+local result = df.split_filepath(filepath)
+```
+**filepath** - _string_ - path and filename
+
+## DESCRIPTION
+
+**split_filepath** splits a filepath into the path, filename, basename and filetype and puts
+that in a table
+
+## RETURN VALUE
+
+**result** - _table_ - a table containing the path, filename, basename, and filetype

content/lua.scripts.api.manual/dtutils.log/_index.md

@@ -0,0 +1,7 @@
+---
+title: dtutils.log
+id: dtutils-log
+weight: 40
+draft: false
+author: "people"
+---

content/lua.scripts.api.manual/dtutils.log/caller.md

@@ -0,0 +1,30 @@
+---
+title: caller
+id: caller
+weight: 20
+draft: false
+author: "people"
+---
+
+## NAME
+
+caller
+
+## SYNOPSIS
+
+get the name and line number of the calling routine
+
+## USAGE
+```
+local log = require "lib/dtutils.log"
+result = log.caller(level)
+```
+**level** - _number_ - the  number of stack levels to go down to retrieve the caller routine information
+
+## DESCRIPTION
+
+**caller** gets the name and line number of the calling routine and returns it
+
+## RETURN VALUE
+
+**result** - _string_ - the name and line number of the calling function or 'callback: ' if the attempt to get the caller returns nil

content/lua.scripts.api.manual/dtutils.log/details.md

@@ -0,0 +1,80 @@
+---
+title: details
+id: details
+weight: 10
+draft: false
+author: "people"
+---
+
+## NAME
+
+dtutils.log
+
+## SYNOPSIS
+
+darktable lua logging library
+
+## USAGE
+```
+local log = require "lib/dtutils.log"
+```
+## DESCRIPTION
+
+**log** provides a multi-level logging solution for use with
+the darktable lua scripts.  With this library you can leave log messages 
+scattered through out your code and only turn them on as necessary.
+
+## RETURN VALUE
+
+**log** - _library_ - the darktable lua logging functions
+
+## FUNCTIONS
+
+### [caller](caller.md)
+
+get the name and line number of the calling routine
+
+### [engine](engine.md)
+
+get and set the output engine
+
+### [log_level](log_level.md)
+
+get or set the log level
+
+### [msg](msg.md)
+
+print a log message
+
+## EXAMPLE
+```
+local log = require "lib/dtutils.log"
+local cur_level = log.log_level()
+log.log_level(log.warn)
+```
+print out warning, error and success messages as code is running
+```
+log.log_level(debug)
+```
+print out debugging messages too because this isnt working
+```
+log.log_level(info)
+```
+I want to make sure this is working ok
+```
+log.log_level(cur_level)
+```
+reset the logging level back to normal
+
+## LICENSE
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

content/lua.scripts.api.manual/dtutils.log/engine.md

@@ -0,0 +1,35 @@
+---
+title: engine
+id: engine
+weight: 30
+draft: false
+author: "people"
+---
+
+## NAME
+
+engine
+
+## SYNOPSIS
+
+get and set the output engine
+
+## USAGE
+```
+local log = require "lib/dtutils.log"
+result = log.engine(level, ...)
+```
+**level** - _table_ - the log level to get or set the engine for, one of log.debug, log.info, log.warn, log.error
+log.success, log.always, log.screen, log.critical  
+**...** - _function_ - the output function, one of dt.print, dt.print_error, dt.print_log, print
+if not function is included, the current engine is returned for the specified log level
+
+## DESCRIPTION
+
+**engine** returns the output engine for the specified log level if a second argument is not
+supplied.  If a function is supplied as the second argment, then the output engine for the specified log level
+is set to that.
+
+## RETURN VALUE
+
+**result** - _function_ - the current output engine

content/lua.scripts.api.manual/dtutils.log/log_level.md

@@ -0,0 +1,50 @@
+---
+title: log_level
+id: log_level
+weight: 40
+draft: false
+author: "people"
+---
+
+## NAME
+
+log_level
+
+## SYNOPSIS
+
+get or set the log level
+
+## USAGE
+```
+local log = require "lib/log"
+local result = log.log_level(...)
+```
+**...** - _arguments_ - if none is supplied, then the current log level is returned as one of:
+log.debug, log.info, log.warn, log.error, log.success.  If one of log.debug, log.info, log.warn,
+log.error, or log.success is supplied as the argument then the log level is set to that value.  All
+log levels greater than or equal in value will be enabled.  Any levels of lesser value will be disabled.
+
+## DESCRIPTION
+
+**log_level** gets and sets the logging level.  When called with no arguments the current log level
+is returned as one of log.debug, log.info, log.warn, log.error, or log.success.  When called with one of log.debug, 
+log.info, log.warn, log.error or log.success then the log level is set.  When setting the log level all levels 
+equal or greater are enabled and any of lesser value are disabled.  See the example.
+
+## RETURN VALUE
+
+**result** - _log level_ - one of log.debug, log.info, log.warn, log.error or log.success
+
+## EXAMPLE
+
+Assume that the current log level is log.error.  Calling 
+```
+log.log_level()
+```
+ will return log.error.
+Calling 
+```
+log.log_level(log.info) 
+```
+will leave log.debug disabled, and enable log.info, log.warn, log.error and 
+log.success.  log.info will be returned as the log_level.

content/lua.scripts.api.manual/dtutils.log/msg.md

@@ -0,0 +1,49 @@
+---
+title: msg
+id: msg
+weight: 50
+draft: false
+author: "people"
+---
+
+## NAME
+
+msg
+
+## SYNOPSIS
+
+print a log message
+
+## USAGE
+```
+local log = require "lib/log"
+log.msg(level, ...)
+```
+**level** - _table_ - the type of message, one of: 
+- log.debug    - debugging messages
+- log.info     - informational messages
+- log.warn     - warning messages 
+- log.error    - error messages 
+- log.success  - success messages
+- log.always   - an internal message for debugging
+- log.screen   - output 1 line of text to the screen
+- log.critical - print a critical message to the console  
+
+**...** - _string(s)_ - the message to print, which could be a comma separated set of strings
+
+## DESCRIPTION
+
+**msg** checks the level to see if it is enabled, then prints the level type and message if it is.
+Messages are output using the engine configured in each log level.
+
+## LIMITATIONS
+
+If you use log.msg in a callback, the name of the calling routine can't be determined.  A solution
+is to include some means of reference such as the name of the callback as an argument, i.e. 
+```
+log.msg(log.debug, "libPlugin.format_combobox:", "value is " .. self.value)
+```
+which would result in
+```
+DEBUG: callback: libPlugin.format_combobox: value is JPEG
+```

content/lua.scripts.api.manual/dtutils.string/_index.md

@@ -0,0 +1,7 @@
+---
+title: dtutils.string
+id: dtutils-string
+weight: 50
+draft: false
+author: "people"
+---

content/lua.scripts.api.manual/dtutils.string/details.md

@@ -0,0 +1,70 @@
+---
+title: details
+id: details
+weight: 10
+draft: false
+author: "people"
+---
+
+# DTUTILS.STRING
+
+## NAME
+
+dtutils.string
+
+## SYNOPSIS
+
+a library of string utilities for use in darktable lua scripts
+
+## USAGE
+```
+local ds = require "lib/dtutils.string"
+```
+## DESCRIPTION
+
+This library contains string manipulation routines to aid in building
+darktable lua scripts.
+
+## RETURN VALUE
+
+_**ds** - library_ - the darktable lua string library
+
+## FUNCTIONS
+
+### [escape_xml_characters](escape_xml_characters.md)
+
+escape characters for xml documents
+
+### [is_not_sanitized](is_not_sanitized.md)
+
+check if a string has been sanitized
+
+### [sanitize](sanitize.md)
+
+surround a string in quotes making it safe to pass as an argument
+
+### [sanitize_lua](sanitize_lua.md)
+
+escape lua 'magic' characters from a pattern string
+
+### [strip_accents](strip_accents.md)
+
+strip accents from characters
+
+### [urlencode](urlencode.md)
+
+encode a string in a websafe manner
+
+## LICENSE
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+

content/lua.scripts.api.manual/dtutils.string/escape_xml_characters.md

@@ -0,0 +1,42 @@
+---
+title: escape_xml_characters
+id: escape_xml_characters
+weight: 20
+draft: false
+author: "people"
+---
+
+## NAME
+
+escape_xml_characters
+
+## SYNOPSIS
+
+escape characters for xml documents
+
+## USAGE
+```
+local ds = require "lib/dtutils.string"
+local result = ds.escape_xml_characters(str)
+```
+**str** - _string_ - the string that needs escaped
+
+## DESCRIPTION
+
+**escape_xml_characters** provides the escape sequences for
+```
+"&", '"', "'", "<", and ">" 
+```
+with the corresponding 
+```
+"&amp;","&quot;", "&apos;", "&lt;", and "&gt;"
+```
+.
+
+## RETURN VALUE
+
+**result** - _string_ - the string containing escapes for the xml characters
+
+## REFERENCE
+
+https://stackoverflow.com/questions/1091945/what-characters-do-i-need-to-escape-in-xml-documents

content/lua.scripts.api.manual/dtutils.string/is_not_sanitized.md

@@ -0,0 +1,31 @@
+---
+title: is_not_sanitized
+id: is_not_sanitized
+weight: 30
+draft: false
+author: "people"
+---
+
+## NAME
+
+is_not_sanitized
+
+## SYNOPSIS
+
+Check if a string has been sanitized
+
+## USAGE
+```
+local ds = require "lib/dtutils.string"
+local result = ds.is_not_sanitized(str)
+```
+**str** - _string_ - the string that needs to be made safe
+
+## DESCRIPTION
+
+**is_not_sanitized** checks a string to see if it
+has been made safe use passing as an argument in a system command.
+
+## RETURN VALUE
+
+**result** - _boolean_ - true if the string is not sanitized otherwise false

content/lua.scripts.api.manual/dtutils.string/sanitize.md

@@ -0,0 +1,31 @@
+---
+title: sanitize
+id: sanitize
+weight: 40
+draft: false
+author: "people"
+---
+
+## NAME
+
+sanitize
+
+## SYNOPSIS
+
+surround a string in quotes making it safe to pass as an argument
+
+## USAGE
+```
+local ds = require "lib/dtutils.string"
+local result = ds.sanitize(str)
+```
+**str** - _string_ - the string that needs to be made safe
+
+## DESCRIPTION
+
+**sanitize** converts a string into a version suitable for
+use passing as an argument in a system command.
+
+## RETURN VALUE
+
+**result** - _string_ - a websafe string

content/lua.scripts.api.manual/dtutils.string/sanitize_lua.md

@@ -0,0 +1,31 @@
+---
+title: sanitize_lua
+id: sanitize_lua
+weight: 50
+draft: false
+author: "people"
+---
+
+## NAME
+
+sanitize_lua
+
+## SYNOPSIS
+
+escape lua 'magic' characters from a pattern string
+
+## USAGE
+```
+local ds = require "lib/dtutils.string"
+local result = ds.sanitize_lua(str)
+```
+**str** - _string_ - the string that needs to be made safe
+
+## DESCRIPTION
+
+**sanitize_lua** escapes lua 'magic' characters so that
+a string may  be used in lua string/patten matching.
+
+## RETURN VALUE
+
+**result** - _string_ - a lua pattern safe string

content/lua.scripts.api.manual/dtutils.string/strip_accents.md

@@ -0,0 +1,35 @@
+---
+title: strip_accents
+id: strip_accents
+weight: 60
+draft: false
+author: "people"
+---
+
+## NAME
+
+strip_accents
+
+## SYNOPSIS
+
+strip accents from characters
+
+## USAGE
+```
+local ds = require "lib/dtutils.string"
+local result = ds.strip_accents(str)
+```
+**str** - _string_ - the string with characters that need accents removed
+
+## DESCRIPTION
+
+**strip_accents** removes accents from accented characters returning the 
+unaccented character.
+
+## RETURN VALUE
+
+**result** - _string_ - the string containing unaccented characters
+
+## REFERENCE
+
+Copied from https://forums.coronalabs.com/topic/43048-remove-special-characters-from-string/

content/lua.scripts.api.manual/dtutils.string/urlencode.md

@@ -0,0 +1,35 @@
+---
+title: urlencode
+id: urlencode
+weight: 70
+draft: false
+author: "people"
+---
+
+## NAME
+
+urlencode
+
+## SYNOPSIS
+
+encode a string in a websage manner
+
+## USAGE
+```
+local ds = require "lib/dtutils.string"
+local result = ds.urlencode(str)
+```
+**str** - _string_ - the string that needs to be made websafe
+
+## DESCRIPTION
+
+**urlencode** converts a string into a websafe version suitable for
+use in a web browser.
+
+## RETURN VALUE
+
+**result** - _string_ - a websafe string
+
+## REFERENCE
+
+https://forums.coronalabs.com/topic/43048-remove-special-characters-from-string

content/lua.scripts.api.manual/dtutils.system/_index.md

@@ -0,0 +1,7 @@
+---
+title: dtutils.system
+id: dtutils-system
+weight: 60
+draft: false
+author: "people"
+---

content/lua.scripts.api.manual/dtutils.system/details.md

@@ -0,0 +1,57 @@
+---
+title: details
+id: details
+weight: 10
+draft: false
+author: "people"
+---
+
+# DTUTILS.SYSTEM
+
+## NAME
+
+dtutils.system
+
+## SYNOPSIS
+
+a library of system utilities for use in darktable lua scripts
+
+## USAGE
+```
+local dtsys = require "lib/dtutils.system"
+```
+## DESCRIPTION
+
+This library contains routines for interfacing to the operating system from
+darktable lua scripts.
+
+## RETURN VALUE
+
+**dtsys** - _library_ - the darktable lua system library
+
+## FUNCTIONS
+
+### [external_command](external_command.md)
+
+pass a command to the operating system for execution and return the result
+
+### [launch_default_app](launch_default_app.md)
+
+open file in default application
+
+### [windows_command](windows_command.md)
+
+pass a command to the windows operating system for execution and return the result
+
+## LICENSE
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

content/lua.scripts.api.manual/dtutils.system/external_command.md

@@ -0,0 +1,30 @@
+---
+title: external_command
+id: external_command
+weight: 20
+draft: false
+author: "people"
+---
+
+## NAME
+
+external_command
+
+## SYNOPSIS
+
+pass a command to the operating system for execution and return the result
+
+## USAGE
+```
+local dsys = require "lib/dtutils.system"
+local result = dsys.external_command(command)
+```
+**command** - _string_ - a string containing the command and arguments to be passed to the operating system for execution.
+
+## DESCRIPTION
+
+**external_command** passes a command to the operating system for execution and returns the results.
+
+## RETURN VALUE
+
+**result** - _number_ = the return value signalling success or failure.

content/lua.scripts.api.manual/dtutils.system/launch_default_app.md

@@ -0,0 +1,31 @@
+---
+title: launch_default_app
+id: launch_default_app
+weight: 30
+draft: false
+author: "people"
+---
+
+## NAME
+
+launch_default_app
+
+## SYNOPSIS
+
+open file in default application
+
+## USAGE
+```
+local dsys = require "lib/dtutils.file"
+result = dsys.launch_default_app(path)
+```
+**path** - _string_ - a file path
+
+## DESCRIPTION
+
+**launch_default_app** allows opening a file in the application that is assigned as default 
+for that filetype in the users's system
+
+## RETURN VALUE
+
+**result** - _number_ - the return value signalling success or failure.

content/lua.scripts.api.manual/dtutils.system/windows_command.md

@@ -0,0 +1,32 @@
+---
+title: windows_command
+id: windows_command
+weight: 40
+draft: false
+author: "people"
+---
+
+## NAME
+
+windows_command
+
+## SYNOPSIS
+
+pass a command to the windows operating system for execution and return the result
+
+## USAGE
+```
+local dsys = require "lib/dtutils.system"
+local result = dsys.windows_command(command)
+```
+**command** - _string_ - a string containing the command and arguments to be passed to the operating system for execution.
+
+## DESCRIPTION
+
+The normal method of executing an operating system command is using dt.control.execute(), but that doesn't 
+work with Windows when more than one item in the command is quoted.  In order to ensure command execution on Windows we 
+create a batch file in the temporary directory, put the command in it, execute the batch file, then return the result.
+
+## RETURN VALUE
+
+**result** - _number_ - the return value signalling success or failure.

content/lua.scripts.api.manual/dtutils/_index.md

@@ -0,0 +1,7 @@
+---
+title: dtutils
+id: dtutils
+weight: 10
+draft: false
+author: "people"
+---

content/lua.scripts.api.manual/dtutils/check_min_api_version.md

@@ -0,0 +1,50 @@
+---
+title: check_min_api_version
+id: check_min_api_version
+weight: 20
+draft: false
+author: "people"
+---
+
+## NAME
+
+check_min_api_version
+
+## SYNOPSIS
+
+check the minimum required application programming interface (API) version against the current API version
+
+## USAGE
+```
+local du = require "lib/dtutils"
+local result = du.check_min_api_version(min_api, script_name)
+```
+**min_api** - _string_ - the API version that the application was written for (example: "5.0.0")  
+**script_name** - _string_ - the name of the script
+
+## DESCRIPTION
+
+**check_min_api_version** compares the minimum API required for the application to
+run against the current API version. The minimum API version is typically the API version that 
+was current when the application was created. If the minimum API version is not met, then an 
+error message is printed saying the script_name failed to load, then an error is thrown causing the
+program to stop executing. 
+
+This function is intended to replace **darktable.configuration.check_version()**. The application code
+won't have to be updated each time the API changes because this only checks the minimum version required.
+
+## RETURN VALUE
+
+**result** - _boolean_ - true if the minimum API version is available, false if not.
+
+## LIMITATIONS
+
+When using the default handler on a script being executed from the luarc file, the error thrown
+will stop the luarc file from executing any remaining statements. This limitation does not apply to script_manger.
+
+## EXAMPLE
+```
+check_min_api_version("5.0.0") 
+```
+does nothing if the API is greater than or equal to 5.0.0 otherwise an
+error message is printed and an error is thrown stopping execution of the script.

content/lua.scripts.api.manual/dtutils/check_os.md

@@ -0,0 +1,42 @@
+---
+title: check_os
+id: check_os
+weight: 30
+draft: false
+author: "people"
+---
+
+## NAME
+
+check_os
+
+## SYNOPSIS
+
+check that the operating system is supported
+
+## USAGE
+```
+local du = require "lib/dtutils"
+local result = du.check_os(operating_systems)
+```
+**operating_systems** - _table_ - a table of operating system names such as {"windows","linux","macos","unix"}
+
+## DESCRIPTION
+
+**check_os** checks a supplied table of operating systems against the operating system the
+script is running on and returns true if the OS is in the list, otherwise false
+
+## RETURN VALUE
+
+**result** - _boolean_ - true if the operating system is supported, false if not.
+
+## EXAMPLE
+```
+local du = require "lib/dtutils"
+if du.check_os({"windows"}) then
+  -- run the script
+else
+  dt.print("Script <script name> only runs on windows")
+  return
+end
+```

content/lua.scripts.api.manual/dtutils/details.md

@@ -0,0 +1,77 @@
+---
+title: details
+id: details
+weight: 10
+draft: false
+author: "people"
+---
+
+
+## NAME
+
+dtutils
+
+## SYNOPSIS
+
+A Darktable lua utilities library
+
+## USAGE
+```
+local du = require "lib/dtutils"
+```
+## DESCRIPTION
+
+**dtutils** provides a common library of functions used to build
+lua scripts.
+
+## RETURN VALUE
+
+**du**- _library_ - the library of functions
+
+## FUNCTIONS
+
+### [check_min_api_version](check_min_api_version.md)
+
+check the minimum required api version against the current api version
+
+### [check_os](check_os.md)
+
+check that the operating system is supported
+
+### [join](http://github.com/darktable-org/lua-scripts/wiki/join.md)
+
+join a table of strings with a specified separator
+
+### [prequire](http://github.com/darktable-org/lua-scripts/wiki/prequire.md)
+
+a protected lua require
+
+### [spairs](http://github.com/darktable-org/lua-scripts/wiki/spairs.md)
+
+an iterator that provides sorted pairs from a table
+
+### [split](http://github.com/darktable-org/lua-scripts/wiki/split.md)
+
+split a string on a specified separator
+
+## SEE ALSO
+
+[dtutils.debug](../dtutils.debug/details.md), [dtutils.file](../dtutils.file/details.md), [dtutils.log](../dtutils.log/details.md), [dtutils.string](../dtutils.string/details.md), [dtutils.system](../dtutils.system/details.md)
+
+## LICENSE
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+## COPYRIGHT
+
+Copyright (C) 2016 Bill Ferguson <wpferguson@gmail.com>.  
+Copyright (C) 2016 Tobias Jakobs

content/lua.scripts.api.manual/dtutils/join.md

@@ -0,0 +1,43 @@
+---
+title: join
+id: join
+weight: 40
+draft: false
+author: "people"
+---
+
+## NAME
+
+join
+
+## SYNOPSIS
+
+join a table of strings with a specified separator
+
+## USAGE
+```
+local du = require "lib/dtutils"
+local result = du.join(tabl, pat)
+```
+**tabl** - _table_ - a table of strings  
+**pat** - _string_ - a separator
+
+## DESCRIPTION
+
+**join** assembles a table of strings into a string with the specified pattern 
+in between each string
+
+## RETURN VALUE
+
+**result** - _string_ - the joined string on success, or an empty string on failure
+
+## EXAMPLE
+```
+join({a, "long", "path", "name", "to", a, "file.txt"}, " ")
+```
+ would return the string
+"a long path name to a file.txt"
+
+## REFERENCE
+
+http://lua-users.org/wiki/SplitJoin

content/lua.scripts.api.manual/dtutils/prequire.md

@@ -0,0 +1,38 @@
+---
+title: prequire
+id: prequire
+weight: 50
+draft: false
+author: "people"
+---
+## NAME
+
+prequire
+
+## SYNOPSIS
+
+a protected lua require
+
+## USAGE
+```
+local du = require "lib/dtutils"
+local status, lib = du.prequire(req_name)
+```
+**req_name** - _string_ - the filename of the lua code to load without the ".lua" filetype
+
+## DESCRIPTION
+
+**prequire** is a protected require that can survive an error in the code being loaded without
+bringing down the calling routine.
+
+## RETURN VALUE
+
+**status** - _boolean_ - true on success
+**lib** - if status is true, then the code, otherwise an error message
+
+## EXAMPLE
+```
+local status, lib = prequire("lib/dtutils.file") 
+```
+which would load lib/dtutils/file.lua which 
+would return a status of true and the reference to the library.

content/lua.scripts.api.manual/dtutils/spairs.md

@@ -0,0 +1,52 @@
+---
+title: spairs
+id: spairs
+weight: 60
+draft: false
+author: "people"
+---
+## NAME
+
+spairs
+
+## SYNOPSIS
+
+an iterator that provides sorted pairs from a table
+
+## USAGE
+```
+local du = require "lib/dtutils"
+for key, value in du.spairs(t, order) do
+  -- do something
+end
+```
+**t** - _table_ - table of key, value pairs
+**order** - _function_ - an optional function to sort the pairs, if none is supplied, table.sort() is used
+
+## DESCRIPTION
+
+**spairs** is an iterator that returns key, value pairs from a table in sorted
+order.  The sorting order is the result of **table.sort()** if no function is 
+supplied, otherwise sorting is done as specified in the function.
+
+## EXAMPLE
+```
+HighScore = { Robin = 8, Jon = 10, Max = 11 }
+-- basic usage, just sort by the keys
+for k,v in spairs(HighScore) do
+  print(k,v)
+end
+--> Jon     10  
+--> Max     11  
+--> Robin   8  
+-- this uses an custom sorting function ordering by score descending
+for k,v in spairs(HighScore, function(t,a,b) return t[b] < t[a] end) do
+  print(k,v)
+end
+--> Max     11
+--> Jon     10
+--> Robin   8
+```
+## REFERENCE
+
+Code copied from http://stackoverflow.com/questions/15706270/sort-a-table-in-lua

content/lua.scripts.api.manual/dtutils/split.md

@@ -0,0 +1,45 @@
+---
+title: split
+id: split
+weight: 70
+draft: false
+author: "people"
+---
+
+## NAME
+
+split
+
+## SYNOPSIS
+
+split a string on a specified separator
+
+## USAGE
+```
+local du = require "lib/dtutils"
+local result = du.split(str, pat)
+```
+**str** - _string_ - the string to split  
+**pat** - _string_ - the pattern to split on
+
+## DESCRIPTION
+
+**split** separates a string into a table of strings.  The strings are separated at each
+occurrence of the supplied pattern. The pattern may be any pattern as described in the lua docs.
+Each match of the pattern is consumed and not returned.
+
+## RETURN VALUE
+
+**result** - _table_ - a table of strings on success, or an empty table on error
+
+## EXAMPLE
+```
+split("/a/long/path/name/to/a/file.txt", "/") 
+```
+would return a table like
+```
+{"a", "long", "path", "name", "to", "a", "file.txt"}
+```
+## REFERENCE
+
+http://lua-users.org/wiki/SplitJoin

content/lua.scripts.manual/_index.html

@@ -0,0 +1,7 @@
+---
+title: Lua Scripts Manual
+id: Lua Scripts Manual
+weight: 10
+draft: false
+author: "people"
+---

content/lua.scripts.manual/installation.md

@@ -0,0 +1,112 @@
+---
+title: installation
+id: installation
+weight: 20
+draft: false
+author: "people"
+---
+
+## Download and Install
+
+The recommended method of installation is using git to clone the repository. This ensures that all dependencies on other scripts
+are met as well as providing an easy update path.
+
+### snap packages
+
+The snap version of darktable comes with lua included starting with version 2.4.3snap2.
+
+Ensure git is installed on your system. If it isn't, use the package manager to install it. Then open a terminal and:
+
+    cd ~/snap/darktable/current
+    git clone https://github.com/darktable-org/lua-scripts.git lua
+
+### flatpak packages
+
+Flatpak packages now use the internal lua interpreter.
+
+
+Ensure git is installed on your system. If it isn't, use the package manager to install it. Then open a terminal and:
+
+    cd ~/.var/app/org.darktable.Darktable/config/darktable
+    git clone https://github.com/darktable-org/lua-scripts.git lua
+
+### appimage packages
+
+These packages run in their own environment and don't have access to a lua interpreter, therefore the scripts can't run. The packagers could enable the internal interpreter, or allow the package to link the interpreter from the operating system, or bundle a copy of lua with the package. If you use one of these packages and wish to use the lua scripts, please contact the package maintainer and suggest the above fixes.
+
+### Linux and MacOS
+
+Ensure git is installed on your system. If it isn't, use the package manager to install it. Then open a terminal and:
+
+    cd ~/.config/darktable/
+    git clone https://github.com/darktable-org/lua-scripts.git lua
+
+### Windows
+
+Ensure git is installed on your system. Git can be obtained from https://gitforwindows.org/, as well as other places. If you use the gitforwindows.org distribution, install the Git Bash Shell also as it will aid in debugging the scripts if necessary. Then open a command prompt and run:
+
+    cd %LOCALAPPDATA%\darktable
+    git clone https://github.com/darktable-org/lua-scripts.git lua
+
+If you don't have %LOCALAPPDATA%\darktable you have to start dartable at least once, because the directory is created at the first start of darktable.
+
+## Enabling
+
+When darktable starts it looks for a file name `~/.config/darktable/luarc` (`%LOCALAPPDATA%\darktable\luarc` for windows) and reads it to see which scripts to include. The file is a plain text file with entries of the form `require "<directory>/<name>"` where directory is the directory containing the scripts, from the above list, and name is the name from the above list. To include GIMP the line would be `require "contrib/gimp"`.
+
+The recommended way to enable and disable specific scripts is using the script manager module.  To use script manager do the following:
+
+### Linux or MacOS
+
+    echo 'require "tools/script_manager"' > ~/.config/darktable/luarc
+
+### Windows
+
+    echo "require 'tools/script_manager'" > %LOCALAPPDATA%\darktable\luarc
+
+### Snap
+
+    echo 'require "tools/script_manager"' > ~/snap/darktable/current/luarc
+
+### Flatpak
+
+    echo require "tools/script_manager"' > ~/.var/app/org.darktable.Darktable/config/darktable/luarc
+
+You can also create or add lines to the luarc file from the command line:
+
+`echo 'require "contrib/gimp"' > ~/.config/darktable/luarc` to create the file with a gimp entry\
+or `echo 'require "contrib/hugin"' >> ~/.config/darktable/luarc` to add an entry for hugin.
+
+On windows from a command prompt:
+
+`echo require "contrib/gimp" > %LOCALAPPDATA%\darktable\luarc` to create the file with a gimp entry\
+or `echo require "contrib/hugin" >> %LOCALAPPDATA%\darktable\luarc` to add an entry for hugin.
+
+## Disabling
+
+To disable a script open the luarc file in your text editor and insert `--` at the start of the line containing the script you wish to disable, then save the file.
+
+## Updating
+
+To update the script repository, open a terminal or command prompt and do the following:
+
+### Snap
+
+    cd ~/snap/darktable/current/lua
+    git pull
+
+
+### Flatpak
+
+    cd ~/.var/app/org.darktable.Darktable/config/darktable/lua
+    git pull
+
+### Linux and MacOS
+
+    cd ~/.config/darktable/lua/
+    git pull
+
+### Windows
+
+    cd %LOCALAPPDATA%\darktable\lua
+    git pull

content/lua.scripts.manual/overview.md

@@ -0,0 +1,10 @@
+---
+title: overview
+id: overview
+weight: 10
+draft: false
+author: "people"
+---
+
+darktable can be customized and extended using the Lua programming language. The [lua-scripts repository](https://github.com/darktable-org/lua-scripts)
+contains the collected efforts of the darktable developers, maintainers, contributors and community.

content/lua.scripts.manual/scripts/_index.md

@@ -0,0 +1,7 @@
+---
+title: scripts
+id: scripts
+weight: 40
+draft: false
+author: "people"
+---

content/lua.scripts.manual/scripts/contrib/AutoGrouper.md

@@ -0,0 +1,41 @@
+---
+title: AugoGrouper
+id: AugoGrouper
+weight: 10
+draft: false
+author: "people"
+---
+
+## Name
+
+AugoGrouper.lua - add the module "Auto Group" to darktable's lighttable view
+
+## Description
+
+This plugin adds the module "Auto Group" to darktable's lighttable view
+
+## Usage
+
+Install: (see here for more detail: https://github.com/darktable-org/lua-scripts )
+ 1) Copy this file in to your "lua/contrib" folder where all other scripts reside. 
+ 2) Require this file in your luarc file, as with any other dt plug-in
+
+Set a gap amount in second which will be used to determine when images should no 
+longer be added to a group. If an image is more then the specified amount of time
+from the last image in the group it will not be added. Images without timestamps 
+in exif data will be ignored.
+
+There are two buttons. One allows the grouping to be performed only on the currently
+selected images, the other button performs grouping on the entire active collection
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Kevin Ertel
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/CollectHelper.md

@@ -0,0 +1,48 @@
+---
+title: CollectHelper
+id: CollectHelper
+weight: 40
+draft: false
+author: "people"
+---
+
+## Name
+
+CollectHelper.lua - add buttons to help with collections
+
+## Description
+
+This plugin adds the button(s) to the "Selected Images" module:
+1) Return to Previous Collection
+2) Collect on image's Folder
+3) Collect on image's Color Label(s)
+4) Collect on All (AND)
+
+It also adds 3 preferences to the lua options dialog box which allow the user to activate/deactivate the 3 "Collect on" buttons.
+
+Button Behavior:
+1) Return to Previous Collection - Will reset the collect parameters to the previously active settings
+2) Collect on image's Folder - Will change the collect parameters to be "Folder" with a value of the selected image's folder location
+3) Collect on image's Color Label(s) - Will change the collect parameter to be "Color" with a value of the selected images color labels, will apply multiple parameters with AND logic if multiple exist
+4) Collect on All (AND) - Will collect on all parameters activated by the preferences dialog, as such this button is redundant if you only have one of the two other options enabled
+
+## Usage
+
+Install: (see here for more detail: https://github.com/darktable-org/lua-scripts )
+ 1) Copy this file in to your "lua/contrib" folder where all other scripts reside. 
+ 2) Require this file in your luarc file, as with any other dt plug-in
+
+Select the photo you wish to change you collection based on.
+In the "Selected Images" module click on "Collect on this Image"
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Kevin Ertel
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/HDRMerge.md

@@ -0,0 +1,47 @@
+---
+title: HDRMerge
+id: name
+weight: 160
+draft: false
+author: "people"
+---
+
+## Name
+
+HDRMerge.lua - create an HDR image using HDRMerge
+## Description
+
+This plugin adds the module 'HDRMerge' to darktable's lighttable view
+
+## Usage
+
+Install: (see here for more detail: https://github.com/darktable-org/lua-scripts )
+ 1) Copy this file in to your 'lua/contrib' folder where all other scripts reside. 
+ 2) Require this file in your luarc file, as with any other dt plug-in
+On the initial startup go to darktable settings > lua options and set your executable paths and other preferences, then restart darktable
+
+Select bracketed images and press the Run HDRMerge button. The resulting DNG will be auto-imported into darktable.
+Additional tags or style can be applied on auto import as well, if you desire.
+
+Base Options:
+Select your desired BPS (bits per sample and Embedded Preview Size. 
+
+Batch Options:
+Select if you want to run in batch mode or not
+Select the gap, in seconds, between images for auto grouping in batch mode
+
+See HDRMerge manual for further detail: http://jcelaya.github.io/hdrmerge/documentation/2014/07/11/user-manual.html
+
+Auto-import Options:
+Select a style, whether you want tags to be copied from the original, and any additional tags you desire added when the new image is auto-imported
+
+## Additional Software Required
+
+HDRMerge ver. 4.5 or greater
+
+## Limitations
+
+
+## Author
+
+Kevin Ertel

content/lua.scripts.manual/scripts/contrib/LabelsToTags.md

@@ -0,0 +1,53 @@
+---
+title: LabelsToTags
+id: LabelsToTags
+weight: 210
+draft: false
+author: "people"
+---
+
+## Name
+
+LabelsToTags.lua - mass apply tags to images
+## Description
+
+Allows the mass-application of tags using color labels and ratings
+as a guide.
+
+## Usage
+
+In your 'luarc' file or elsewhere, use the function
+'register_tag_mapping', defined in this module, to specify
+one or more tag mappings for use by the module.
+Any mappings so registered will be selectable, according
+to their given names, in the module's "mapping" combo box.
+
+A mapping takes the form of a table mapping patterns to
+lists of tags. A pattern consists of 6 characters, of which
+the first five represent color labels and the last the rating.
+Each color label character may be '+', '-', or '*',
+indicating that for this pattern to match, the corresponding
+color label, respectively, must be on, must be off, or can be
+either. Similarly, the rating character may be a numeral
+between 0 and 5, "R" for rejected, or "*" for "any value."
+
+An example call to 'register_tag_mapping' is provided in a
+comment at the end of this file.
+
+When the "Start" button is pressed, the module will
+iterate over each selected image and check the state of
+that image's color labels and rating against each pattern
+defined in the selected mapping. For each pattern that
+matches, the corresponding tags will be added to the
+image. Any such tag not already existing in the database
+will be created.
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+August Schwerdfeger - august@schwerdfeger.name

content/lua.scripts.manual/scripts/contrib/OpenInExplorer.md

@@ -0,0 +1,47 @@
+---
+title: OpenInExplorer
+id: OpenInExplorer
+weight: 220
+draft: false
+author: "people"
+---
+
+## Name
+
+OpenInExplorer.lua - open an images containing folder
+
+## Description
+
+This plugin adds the module "OpenInExplorer" to darktable's lighttable view.
+
+## Usage
+
+Require this file in your luarc file, as with any other dt plug-in
+
+Select the photo(s) you wish to find in your operating system's file manager and press "show in file explorer" in the "selected images" section.
+
+- Nautilus (Linux), Explorer (Windows), and Finder (macOS prior to Mojave) will open one window for each selected image at the file's location. The file name will be highlighted.
+
+- On macOS Mojave and Catalina the Finder will open one window for each different directory. In these windows only the last one of the corresponding files will be highlighted (bug or feature?).
+
+- Dolphin (Linux) will open one window with tabs for the different directories. All the selected images' file names are highlighted in their respective directories.
+
+As an alternative option you can choose to show the image file names as symbolic links in an arbitrary directory. Go to preferences|Lua options. This option is not available for Windows users as on Windows solely admins are allowed to create links.
+
+- Pros: You do not clutter up your display with multiple windows. So there is no need to limit the number of selections.
+
+- Cons: If you want to work with the files you are one step behind the original data.
+
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Kevin Ertel  
+Volker Lenhardt  
+Bill Ferguson
+

content/lua.scripts.manual/scripts/contrib/RL_out_sharp.md

@@ -0,0 +1,48 @@
+---
+title: RL_out_sharp
+id: RL_out_sharp
+weight: 290
+draft: false
+author: "people"
+---
+
+## Name
+
+RL_out_sharp.lua - Richardson-Lucy output sharpening using GMic
+
+## Description
+
+This script provides a new target storage "RL output sharpen". 
+Images exported will be sharpened using GMic (RL deblur algorithm)
+
+  EXAMPLE
+    set sigma = 0.7, iterations = 10, jpeg output quality = 95,
+    to correct blur due to image resize for web usage
+
+## Usage
+
+* require this script from main lua file
+* in lua preferences, select the GMic cli executable
+* from "export selected", choose "RL output sharpen"
+* configure output folder 
+* configure RL parameters with sliders
+* configure temp files format and quality, jpg 8bpp (good quality) 
+  and tif 16bpp (best quality) are supported
+* configure other export options (size, etc.)
+* export, images will be first exported in the temp format, then sharpened
+* sharpened images will be stored in jpg format in the output folder
+
+## Additional Software Required
+
+GMic command line interface (CLI) https://gmic.eu/download.shtml
+
+## Limitations
+
+MAC compatibility not tested
+Although Darktable can handle file names containing spaces, GMic cli cannot, 
+  so if you want to use this script please make sure that your images do not
+  have spaces in the file name and path
+
+## Author
+
+Marco Carrarini - marco.carrarini@gmail.com

content/lua.scripts.manual/scripts/contrib/_index.md

@@ -0,0 +1,7 @@
+---
+title: contrib
+id: contrib
+weight: 30
+draft: false
+author: "people"
+---

content/lua.scripts.manual/scripts/contrib/autostyle.md

@@ -0,0 +1,46 @@
+---
+title: autostyle
+id: autostyle
+weight: 20
+draft: false
+author: "people"
+---
+
+## Name
+
+autostyle.lua - automatically apply a given style when an exif tag is present in the image file
+
+## Description
+
+Automatically apply a given style when an exif tag is present in the file. This tagged is checked with exiftool, in order to be able to match very exotic tags.
+I wrote this initially to be able to apply a style to compensate for Auto-DR from my Fujifilm camera
+
+## Usage
+
+* set the exif configuration string in your lua configuration
+  mine, for instance, is AutoDynamicRange=200%=>DR200"
+  meaning that I automatically want to apply my DR200 style on all
+  images where exiftool returns '200%' for the AutoDynamicRange tag
+* if you want to be able to apply it manually to already imported
+  images, define a shortcut (lua shortcuts). As I couldn't find an event for
+  when a development is removed, so the autostyle won't be applied again, 
+  this shortcut is also helpful then
+* import your images, or use the shortcut on your already imported images
+* To determine which tag you want, list all tags with exiftool:
+  exiftool -j XE021351.RAF, and find the one you want to use
+  you can check it with 
+  > exiftool -AutoDynamicRange XE021351.RAF
+  Auto Dynamic Range              : 200%
+
+## Additional Software Required
+
+* exiftool
+
+## Limitations
+
+
+## Author
+
+Marc Cousin - cousinmarc@gmail.com
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/clear_GPS.md

@@ -0,0 +1,33 @@
+---
+title: clear_GPS
+id: clear_GPS
+weight: 30
+draft: false
+author: "people"
+---
+
+## Name
+
+clear_GPS.lua - clear_GPS - clear GPS data from selected image(s)
+
+## Description
+
+This shortcut removes the GPS coordinate data from the selected images.
+
+## Usage
+
+* require this script from your main lua file
+* select an image or images
+* click the shortcut, clear GPS data
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Bill Ferguson - wpferguson@gmail.com
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/copy_attach_detach_tags.md

@@ -0,0 +1,39 @@
+---
+title: copy_attach_detach_tags
+id: copy_attach_detach_tags
+weight: 50
+draft: false
+author: "people"
+---
+
+## Name
+
+copy_attach_detach_tags.lua - tools to manipulate image tags
+
+## Description
+
+This script that will create four shortcuts and add a module in lighttable mode to copy,
+paste, replace and remove tags from images.
+
+## Usage
+
+ * set the shortcuts for copy, attach and detach in the preferences dialog
+ * \<your shortcut1\> copy will create a list of tags from all selected images
+ * \<your shortcut2\> paste copied tags to selected images, whereby
+   darktable internal tags starting with 'darktable|' will not be touched
+ * \<your shortcut3\> removes all expect darktable internal tags from selected images
+ * \<your shortcut4\> replaces all tags expect darktable internals
+ * A module reset will empty the clipboard
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Christian Kanzian  
+Holger Klemm
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/cr2hdr.md

@@ -0,0 +1,41 @@
+---
+title: cr2hdr
+id: cr2hdr
+weight: 60
+draft: false
+author: "people"
+---
+
+## Name
+
+cr2hdr.lua - Magic Lantern Dual ISO processing
+
+## Description
+
+cr2hdr Magic Lantern Dual ISO processing.
+
+This script automates the steps involved to process an image created
+with the Magic Lantern Dual ISO module. Upon invoking the script with a
+shortcut "cr2hdr" provided by Magic Lantern is run on the selected
+images. The processed files are imported. They are also made group
+leaders to hide the original files.
+
+
+## Usage
+
+* require this script from your main lua file
+* trigger conversion on selected/hovered images by shortcut (set shortcut in settings dialog)
+* it is also possible to have the script run after importing a collection (optin, since it is not that fast)
+
+## Additional Software Required
+
+* cr2hdr (sources can be obtained through the Magic Lantern repository)
+
+## Limitations
+
+
+## Author
+
+Till Theato  - theato@ttill.de
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/enfuseAdvanced.md

@@ -0,0 +1,61 @@
+---
+title: enfuseAdvanced
+id: enfuseAdvanced
+weight: 70
+draft: false
+author: "people"
+---
+
+## Name
+
+enfuseAdvanced.lua - process HDR or focus stacked images
+
+## Description
+
+This plugin will add the new export module 'fusion to DRI or DFF image'.
+
+## Usage
+
+Install:
+ 1) Get the Lua scripts: https://github.com/darktable-org/lua-scripts#download-and-install
+ 2) Require this file in your luarc file, as with any other dt plug-in: require "contrib/enfuseAdvanced"
+ 3) Then select "DRI or DFF image" as storage option
+ 4) On the initial startup set your executable paths 
+
+DRI = Dynamic Range Increase (Blend multiple bracket images into a single LDR file)
+DFF = Depth From Focus ('Focus Stacking' - Blend multiple images with different focus into a single image)
+Select multiple images that are either bracketed, or focus-shifted, set your desired operating parameters, and press the export button. A new image will be created. The image will
+be auto imported into darktable if you have that option enabled. Additional tags or style can be applied on auto import as well, if you desire.
+
+image align options:
+See align_image_stack documentation for further explanation of how it specifically works and the options provided (http://hugin.sourceforge.net/docs/manual/Align_image_stack.html)
+
+image fustion options:
+See enfuse documentation for further explanation of how it specifically works and the options provided (https://wiki.panotools.org/Enfuse)
+If you have a specific set of parameters you frequently like to use, you can save them to a preset. There are 3 presets available for DRI, and 3 for DFF.
+
+target file:
+Select your file destination path, or check the 'save to source image location' option.
+'Create Unique Filename' is enabled by default at startup, the user can choose to overwrite existing
+Set any tags or style you desire to be added to the new image (only available if the auto-import option is enabled). You can also change the defaults for this under settings > lua options
+
+format options:
+Same as other export modules
+
+global options:
+Same as other export modules
+
+## Additional Software Required
+
+align_image_stack
+enfuse ver. 4.2 or greater
+exiftool
+
+## Limitations
+
+
+## Author
+
+Kevin Ertel
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/exportLUT.md

@@ -0,0 +1,34 @@
+---
+title: exportLUT
+id: exportLUT
+weight: 80
+draft: false
+author: "people"
+---
+
+## Name
+
+
+## Description
+
+Given a haldCLUT identity file this script generates haldCLUTS from all the user's
+styles and exports them to a location of their choosing.
+
+## Usage
+
+Add the following line to .config/darktable/luarc to enable this lightable module: 
+  require "contrib/exportLut"
+
+## Additional Software Required
+
+
+## Limitations
+
+Warning: during export if a naming collision occurs the older file is automatically
+overwritten silently.
+
+## Author
+
+Noah Clarke
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/ext_editor.md

@@ -0,0 +1,69 @@
+---
+title: ext_editor
+id: ext_editor
+weight: 90
+draft: false
+author: "people"
+---
+
+## Name
+
+ext_editor.lua - edit images with external editors
+
+## Description
+
+This script provides helpers to edit image files with programs external to darktable. It adds:
+- a new target storage "collection". Image exported will be reimported to collection for further edit with external programs
+- a new lighttable module "external editors", to select a program from a list of up to
+- 9 external editors and run it on a selected image (adjust this limit by changing MAX_EDITORS)
+- a set of lua preferences in order to configure name and path of up to 9 external editors
+- a set of lua shortcuts in order to quick launch the external editors
+
+## Usage
+
+* require this script from main lua file
+  
+-- setup --
+* in "preferences/lua options" configure name and path/command of external programs
+* note that if a program name is left empty, that and all following entries will be ignored
+* in "preferences/shortcuts/lua" configure shortcuts for external programs (optional)
+* whenever programs preferences are changed, in lighttable/external editors, press "update list"
+
+-- use --
+* in the export dialog choose "collection" and select the format and bit depth for the
+   exported image
+* press "export"
+* the exported image will be imported into collection and grouped with the original image
+      
+* select an image for editing with en external program, and:
+* in lighttable/external editors, select program and press "edit"
+* edit the image with the external editor, overwite the file, quit the external program
+* the selected image will be updated
+  or
+* in lighttable/external editors, select program and press "edit a copy"
+* edit the image with the external editor, overwite the file, quit the external program
+* a copy of the selected image will be created and updated
+  or
+* in lighttable select target storage "collection"
+* enter in darkroom
+* to create an export or a copy press CRTL+E
+* use the shortcut to edit the current image with the corresponding external editor
+* overwite the file, quit the external program
+* the darkroom view will be updated
+    
+* warning: mouseover on lighttable/filmstrip will prevail on current image
+* this is the default DT behavior, not a bug of this script
+
+
+## Additional Software Required
+
+
+## Limitations
+
+* MAC compatibility not tested
+
+## Author
+
+Marco Carrarini - marco.carrarini@gmail.com
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/face_recognition.md

@@ -0,0 +1,42 @@
+---
+title: face_recognition
+id: face_recognition
+weight: 100
+draft: false
+author: "people"
+---
+
+## Name
+
+face_recognition.lua - add a new storage option and calls face_recognition after export
+
+## Description
+
+Add a new storage option to send images to face_recognition.
+Images are exported to darktable tmp dir first.
+A directory with known faces must exist, the image name are the
+tag names which will be used.
+Multiple images for one face can exist, add a number to it, the
+number will be removed from the tag, for example:
+People|IknowYou1.jpg
+People|IknowYou2.jpg
+People|Another.jpg
+People|Youtoo.jpg
+
+## Usage
+
+* require this file from your main luarc config file.
+
+## Additional Software Required
+
+* https://github.com/ageitgey/face_recognition
+* https://github.com/darktable-org/lua-scripts/tree/master/lib
+
+## Limitations
+
+
+## Author
+
+Sebastian Witt
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/fujifilm_ratings.md

@@ -0,0 +1,31 @@
+---
+title: fujifilm_ratings
+id: fujifilm_ratings
+weight: 110
+draft: false
+author: "people"
+---
+
+## Name
+
+fujifilm_ratings.lua - support for importing Fujifilm in-camera ratings in darktable
+
+## Description
+
+Support for importing Fujifilm in-camera ratings in darktable.
+
+## Usage
+
+
+## Additional Software Required
+
+- exiftool (https://www.sno.phy.queensu.ca/~phil/exiftool/)
+
+## Limitations
+
+
+## Author
+
+Ben Mendis - ben.mendis@gmail.com
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/geoJSON_export.md

@@ -0,0 +1,36 @@
+---
+title: geoJSON_export
+id: geoJSON_export
+weight: 120
+draft: false
+author: "people"
+---
+
+## Name
+
+geoJSON_export.lua - export a geoJSON file from selected images
+
+## Description
+
+darktable geoJSON export script
+
+## Usage
+
+* require this script from your main Lua file
+
+## Additional Software Required
+
+* mkdir
+* convert (ImageMagick)
+* xdg-open
+* xdg-user-dir
+
+## Limitations
+
+This script is only tested with Linux
+
+## Author
+
+Tobias Jakobs
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/geoToolbox.md

@@ -0,0 +1,33 @@
+---
+title: geoToolbox
+id: geoToolbox
+weight: 130
+draft: false
+author: "people"
+---
+
+## Name
+
+geoToolbox.lua - a module of geo tools
+
+## Description
+
+* it creates a new geoToolbox lighttable module
+
+## Usage
+
+* require this script from your main lua file
+  To do this add this line to the file .config/darktable/luarc:
+require "geoToolbox"
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Tobias Jakobs
+
+## Change Log

content/lua.scripts.manual/scripts/contrib/gimp.md

@@ -0,0 +1,47 @@
+---
+title: gimp
+id: gimp
+weight: 140
+draft: false
+author: "people"
+---
+
+## Name
+
+gimp.lua - export and edit with GIMP
+
+## Description
+
+This script provides another storage (export target) for darktable.  Selected
+images are exported in the specified format to temporary storage.  GIMP is launched
+and opens the files.  After editing, the exported images are overwritten to save the
+changes.  When GIMP exits, the exported files are moved into the current collection
+and imported into the database.  The imported files then show up grouped with the
+originally selected images.
+
+## Usage
+
+* require this script from your main lua file
+* select an image or images for editing with GIMP
+* in the export dialog select "Edit with GIMP" and select the format and bit depth for the
+  exported image
+* Press "export"
+* Edit the image with GIMP then save the changes with File->Overwrite....
+* Exit GIMP
+* The edited image will be imported and grouped with the original image
+
+## Additional Software Required
+
+* GIMP - http://www.gimp.org
+
+## Limitations
+
+* Developed and tested on Ubuntu 14.04 LTS with darktable 2.0.3 and GIMP 2.9.3 (development version with
+  > 8 bit color)
+* There is no provision for dealing with the xcf files generated by GIMP, since darktable doesn't deal with
+  them.  You may want to save the xcf file if you intend on doing further edits to the image or need to save
+  the layers used.  Where you save them is up to you.
+
+## Author
+
+Bill Ferguson - wpferguson@gmail.com

content/lua.scripts.manual/scripts/contrib/gpx_export.md

@@ -0,0 +1,33 @@
+---
+title: gpx_export
+id: gpx_export
+weight: 150
+draft: false
+author: "people"
+---
+
+## Name
+
+gpx_export.lua - gpx exporter
+
+## Description
+
+Simple darktable GPX generator script
+
+This script generates a GPX track from all images having GPS latitude
+and longitude information.
+For each source folder, a separate \<trk\> is generated in the gpx file.
+
+## Usage
+
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Jannis_V
+

content/lua.scripts.manual/scripts/contrib/hugin.md

@@ -0,0 +1,35 @@
+---
+title: hugin
+id: hugin
+weight: 170
+draft: false
+author: "people"
+---
+
+## Name
+
+hugin.lua - stitch multiple images into a panorama
+
+## Description
+
+Add a new storage option to send images to hugin.
+Images are exported to darktable tmp dir first.
+
+## Usage
+
+* require this file from your main luarc config file
+* set the hugin tool paths (on some platforms)
+* if hugin gui mode is used, save the final result in the tmp directory with the first file name and \_pano as suffix for the image to be automatically imported to DT afterwards
+
+## Additional Software Required
+
+* hugin
+
+## Limitations
+
+
+## Author
+
+Wolfgang Goetz  
+Christian Kanzian  
+Tobias Jakobs  

content/lua.scripts.manual/scripts/contrib/image_stack.md

@@ -0,0 +1,54 @@
+---
+title: image_stack
+id: image_stack
+weight: 180
+draft: false
+author: "people"
+---
+
+## Name
+
+image_stack.lua - process a stack of images
+
+## Description
+
+This script provides another storage (export target) for darktable.  Selected
+images are exported in the specified format to temporary storage.  The images are aligned
+if the user requests it. When the images are ready, imagemagick is launched and uses
+the selected evaluate-sequence operator to process the images.  The output file is written
+to a filename representing the imput files in the format specified by the user.  The resulting 
+image is imported into the film roll.  The source images can be tagged as part of the file 
+creation so that  a user can later find the contributing images.
+
+## Usage
+
+* require this script from your main lua file
+* select the images to process with image_stack
+* in the export dialog select "image stack" and select the format and bit depth for the
+  exported image
+* Select whether the images need to be aligned.
+* Select the stack operator
+* Select the output format
+* Select whether to tag the source images used to create the resulting file
+* Specify executable locations if necessary
+* Press "export"
+* The resulting image will be imported
+
+## Additional Software Required
+
+* align_image_stack - http://www.hugin.org
+* imagemagick - http://www.imagemagick.org
+
+## Limitations
+
+Mean is a fairly quick operation.  On my machine (i7-6800K, 16G) it takes a few seconds.  Median, on the other hand
+takes approximately 10x longer to complete.  Processing 10 and 12 image stacks took over a minute.  I didn't test all
+the other functions, but the ones I did fell between Mean and Median performance wise.
+
+## Author
+
+Bill Ferguson - wpferguson@gmail.com
+
+## See Also 
+
+* Thanks to Pat David and his blog entry on blending images, https://patdavid.net/2013/05/noise-removal-in-photos-with-median_6.html

content/lua.scripts.manual/scripts/contrib/image_time.md

@@ -0,0 +1,97 @@
+---
+title: image_time
+id: image_time
+weight: 190
+draft: false
+author: "people"
+---
+
+## Name
+
+image_time.lua - synchronize image time for images shot with different cameras
+
+## Description
+
+image_time non destructively adjusts image times by modifying the 
+database image exif_datetime_taken field.  There are 4 modes: adjust time,
+set time, synchronize time, and reset time.
+
+  ADJUST TIME
+
+    adjust time mode lets you chose an offset in terms of years, months,
+    days, hours, minutes, and seconds.  The adjustment can be added or
+    subtracted.  
+
+    WARNING:  When adding and subtracting months the result will usually
+    be what is expected unless the time being adjusted is at the end of 
+    the month.  This is because a month is a variable amount of time that
+    can be 28, 29, 30 or 31 days depending on the month.  Example: It's 
+    March 31st and I subtract a month which not sets the time to February
+    31st.  When that gets set to a valid time, then the date changes to
+    March 3rd.
+
+  SET TIME
+
+    set time mode allows you to pick a date and time and set the image
+    time accordingly.  Fields may be left out.  This is useful when 
+    importing scanned images that don't have an embedded date.  
+
+  SYNCHRONIZE TIME
+
+    I recently purchased a 7DmkII to replace my aging 7D.  My 7D was still
+    serviceable, so I bought a remote control and figured I'd try shooting
+    events from 2 different perspectives.  I didn't think to synchonize the 
+    time between the 2 cameras, so when I loaded the images and sorted by
+    time it was a disaster.  I hacked a script together with hard coded values
+    to adjust the exif_datetime_taken value in the database for the 7D images 
+    so that everything sorted properly.  I've tried shooting with 2 cameras 
+    several times since that first attempt.  I've gotten better at getting the
+    camera times close, but still haven't managed to get them to sync.  So I
+    decided to think the problem through and write a proper script to take 
+    care of the problem.
+
+  RESET TIME
+
+    Select the images and click reset.  
+
+## Usage
+
+  ADJUST TIME
+
+    Change the year, month, day, hour, minute, second dropdowns to the amount
+    of change desired.  Select add or subtract.  Select the images.  Click 
+    adjust.
+
+  SET TIME
+
+    Set the time fields to the desired time.  Select the images to change.  Click
+    set.
+
+  SYNCHRONIZE TIME
+
+    Select 2 images, one from each camera, of the same moment in time.  Click
+    the Calculate button to calculate the time difference.  The difference is
+    displayed in the difference entry.  You can manually adjust it by changing
+    the value if necessary.
+
+    Select the images that need their time adjusted.  Determine which way to adjust
+    adjust the time (add or subtract) and select the appropriate choice.
+
+    If the image times get messed up and you just want to start over, select reset time
+    from the mode and reset the image times.
+
+  RESET TIME
+
+    Select the images and click reset.
+
+## Additional Software Required
+
+* exiv2
+
+## Limitations
+
+
+## Author
+
+Bill Ferguson - wpferguson@gmail.com
+

content/lua.scripts.manual/scripts/contrib/kml_export.md

@@ -0,0 +1,35 @@
+---
+title: kml_export
+id: kml_export
+weight: 200
+draft: false
+author: "people"
+---
+
+## Name
+
+kml_export.lua - export a kml file from selected images
+
+## Description
+
+darktable KML export script
+
+## Usage
+
+* require this script from your main Lua file
+* when choosing file format, pick JPEG or PNG as Google Earth doesn't support other formats
+
+## Additional Software Required
+
+* zip (at the moment Linux only and only if you create KMZ files)
+* magick (ImageMagick)
+* xdg-user-dir (Linux)
+
+## Limitations
+
+This script is only tested with Linux
+
+## Author
+
+Tobias Jakobs  
+Erik Augustin

content/lua.scripts.manual/scripts/contrib/passport_guide.md

@@ -0,0 +1,35 @@
+---
+title: passport_guide
+id: passport_guide
+weight: 230
+draft: false
+author: "people"
+---
+
+## Name
+
+
+## Description
+
+guides for cropping passport photos based on documents from the Finnish police
+(https://www.poliisi.fi/instancedata/prime_product_julkaisu/intermin/embeds/poliisiwwwstructure/38462_Passikuvaohje_EN.pdf) describing passport photo dimensions of 47x36 mm and 500x653 px for digital biometric data stored in passports. They use ISO 19794-5 standard based on ICAO 9303 regulations which should also be compliant for all of Europe.
+
+## Usage
+
+* add the following line in the file $CONFIGDIR/luarc
+  require "passport_guide"
+* (optional) add the line:
+  "plugins/darkroom/clipping/extra_aspect_ratios/passport 36x47mm=47:36"
+  to $CONFIGDIR/darktablerc
+* when using the cropping tool, select "passport" as guide and if you added the line in yout rc
+  select "passport 36x47mm" as aspect
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Kåre Hampf

content/lua.scripts.manual/scripts/contrib/pdf_slideshow.md

@@ -0,0 +1,42 @@
+---
+title: pdf_slideshow
+id: pdf_slideshow
+weight: 240
+draft: false
+author: "people"
+---
+
+## Name
+
+pdf_slideshow.lua - generate a pdf slideshow
+
+## Description
+
+Generates a PDF slideshow (via Latex) containing all selected images
+one per slide.
+
+## Usage
+
+* require this file from your main lua config file:
+
+This plugin will add a new exporter that will allow you to generate a pdf slideshow.
+The interface will let you add:
+   - a global title for the slideshow (prefix in all slide label)
+   - a delay for the transition between each slide
+
+Each slide will contain a single picture with a label at the bottom with the
+format (all fields can be the empty string):
+
+   <global title> / <image creator> / <image title>
+
+## Additional Software Required
+
+* a PDF-Viewer
+* pdflatex (Latex)
+
+## Limitations
+
+
+## Author
+
+Pascal Obry

content/lua.scripts.manual/scripts/contrib/photils.md

@@ -0,0 +1,41 @@
+---
+title: photils
+id: photils
+weight: 250
+draft: false
+author: "people"
+---
+
+## Name
+
+photils.lua - auto tag images based on feature recognition
+
+## Description
+
+ A darktable plugin that tries to predict keywords based on the selected image.
+ This plugin uses photils-cli to handle this task. Photils-cli is an application
+ that passes the image through a neural network, classifies it, and extracts the
+ suggested tags. Everything happens offline without the need that your data are
+ sent over the internet.
+
+## Usage
+
+* require this script from your main lua file
+  To do this add this line to the file .config/darktable/luarc:
+  require "contrib/photils"
+* Select an image
+* Press "get tags"
+* Select the tags you want from a list of suggestions
+* Press "Attach .. Tags" to add the selected tags to your image
+
+## Additional Software Required
+
+* photils-cli - https://github.com/scheckmedia/photils-cli at the moment only
+  available for Linux and MacOS
+
+## Limitations
+
+
+## Author
+
+Tobias Scheck

content/lua.scripts.manual/scripts/contrib/quicktag.md

@@ -0,0 +1,38 @@
+---
+title: quicktag
+id: quicktag
+weight: 260
+draft: false
+author: "people"
+---
+
+## Name
+
+quicktag.lua - add shortcuts to speed up tagging
+## Description
+
+For faster attaching your favorite tags, the script adds shortcuts and
+ the module "quicktag" in lighttable mode with a changeable number of buttons.
+ To each button a tag can be assigned. If the tags do not exist in your database,
+ they are added to the database once they get the first time attached to an image.
+
+ The number of buttons/shortcuts can be changed in the lua preferences.
+ Changes in the number require a restart of darktable.
+
+## Usage
+
+ * set the number of quicktags between 2 and 10 in the preferences dialog and restart darktable
+ * if wanted set the shortcuts in the preferences dialog
+ * to add or change a quicktag, first select the old tag with the combobox "old quicktag",
+   enter a new tag in the "new quicktag" filed and press "set quicktag"
+ * use a shortcut or button to attach the tag to selected images
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Christian Kanzian

content/lua.scripts.manual/scripts/contrib/rate_group.md

@@ -0,0 +1,43 @@
+---
+title: rate_group
+id: rate_group
+weight: 270
+draft: false
+author: "people"
+---
+
+## Name
+
+rate_group.lua - rate groups of images
+
+## Description
+
+Script to provide shortcuts for rating or rejecting all images within a group;
+particularly useful for RAW+JPEG shooters employing a star rating workflow
+like the below:
+
+  http://blog.chasejarvis.com/blog/2011/03/photo-editing-101/
+
+## Usage
+
+Assign a keyboard shortcut to each action via settings > shortcuts > lua
+
+ I use the following shortcuts:
+
+ * Reject group: Ctrl+R
+ * Rate group 1: Ctrl+1
+ * Rate group 2: Ctrl+2
+ * Rate group 3: Ctrl+3
+ * Rate group 4: Ctrl+4
+ * Rate group 5: Ctrl+5
+ * Rate group 0: Ctrl+0
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Dom H - dom@hxy.io

content/lua.scripts.manual/scripts/contrib/rename-tags.md

@@ -0,0 +1,32 @@
+---
+title: rename_tags
+id: rename_tags
+weight: 280
+draft: false
+author: "people"
+---
+
+## Name
+
+rename-tags.lua - rename tags
+
+## Description
+
+
+## Usage
+
+* In lighttable there is a new entry: 'rename tag'
+* Enter old tag (this one gets deleted!)
+* Enter new tag name
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+  Sebastian Witt - se.witt@gmx.net  
+  Bill Ferguson - wpferguson@gmail.com
+

content/lua.scripts.manual/scripts/contrib/select_untagged.md

@@ -0,0 +1,28 @@
+---
+title: select_untagged
+id: select_untagged
+weight: 390
+draft: false
+author: "people"
+---
+
+## Name
+
+select_untagged.lua - select all images that aren't tagged
+
+## Description
+
+Enable selection of untagged images (darktable|* tags are ignored)
+
+## Usage
+
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Jannis_V

content/lua.scripts.manual/scripts/contrib/slideshowMusic.md

@@ -0,0 +1,30 @@
+---
+title: slideshowMusic
+id: slideshowMusic
+weight: 310
+draft: false
+author: "people"
+---
+
+## Name
+
+slideshowMusic.lua - play music during a slideshow 
+
+## Description
+
+darktable Script to play music during a Slideshow
+
+## Usage
+
+* require this script from your main lua file
+
+## Additional Software Required
+
+You need rhythmbox-client installed to use this script
+
+## Limitations
+
+
+## Author
+
+Tobias Jakobs

content/lua.scripts.manual/scripts/contrib/transfer_hierarchy.md

@@ -0,0 +1,83 @@
+---
+title: transfer_hierarchy
+id: transfer_hierarchy
+weight: 320
+draft: false
+author: "people"
+---
+
+## Name
+
+transfer_hierarchy.lua - move or copy image hierarchies from one location to another
+
+## Description
+
+Allows the moving or copying of images from one directory
+tree to another, while preserving the existing hierarchy.
+
+## Usage
+
+darktable's native operations for moving and copying images in
+batches allow only one directory to be specified as the destination
+for each batch. Those wanting to move or copy images from a _hierarchy_
+of directories within darktable while preserving the directory structure,
+must take the laborious step of performing the operation one individual
+directory at a time.
+
+This module allows the intact moving and copying of whole directory trees.
+It was designed for the specific use case of rapidly transferring images
+from a customary source (e.g., a staging directory on the local disk)
+to a customary destination (e.g., a directory on a NAS device).
+
+Instructions for operation:
+
+1. Select the set of images you want to copy.
+
+2. Click the "calculate" button. This will calculate the
+   lowest directory in the hierarchy that contains every selected
+   file (i.e., the common prefix of all the images' pathnames), and
+   write its path into the "existing root" text box.
+
+3. If (a) you have specified the "customary source root" and "customary
+   destination root" preferences, and (b) the selected images are all
+   contained under the directory specified as the customary source
+   root, then the "root of destination" text box will also be
+   automatically filled out.
+
+   For example, suppose that you have specified '/home/user/Staging'
+   as your customary source root and '/mnt/storage' as your customary
+   destination root. If all selected images fell under the directory
+   '/home/user/Staging/2020/Roll0001', the "root of destination" would
+   be automatically filled out with '/mnt/storage/2020/Roll0001'.
+
+   But if all selected images fall under a directory outside the
+   specified customary source root (e.g., '/opt/other'), the "root
+   of destination" text box must be filled out manually.
+
+   It is also possible to edit the "root of destination" further once
+   it has been automatically filled out.
+
+4. Click the "move" or "copy" button.
+
+   Before moving or copying any images, the module will first
+   replicate the necessary directory hierarchy by creating all
+   destination directories that do not already exist; should a
+   directory creation attempt fail, the operation will be
+   aborted, but any directories already created will not be
+   removed.
+
+   During the actual move/copy operation, the module transfers an
+   image by taking its path and replacing the string in the "existing
+   root" text box with that in the "root of destination" text box
+   (e.g., '/home/user/Staging/2020/Roll0001/DSC_0001.jpg' would be
+   transferred to '/mnt/storage/2020/Roll0001/DSC_0001.jpg').
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+August Schwerdfeger - august@schwerdfeger.name

content/lua.scripts.manual/scripts/contrib/video_ffmpeg.md

@@ -0,0 +1,35 @@
+---
+title: video_ffmpeg
+id: video_ffmpeg
+weight: 330
+draft: false
+author: "people"
+---
+
+## Name
+
+video_ffmpeg.lua - create a timelapse video from selected images
+
+## Description
+
+This plugin will add the new export module "video ffmpeg".
+
+## Usage
+
+1. Go to Lighttable 
+2. Select images you want to use as a video ffmpeg frames
+3. In image export module select "video ffmpeg"
+4. Configure you video settings
+5. Export
+
+## Additional Software Required
+
+ffmpeg
+
+## Limitations
+
+This script has been tested under Linux only
+
+## Author
+
+Dominik Markiewicz

content/lua.scripts.manual/scripts/examples/_index.md

@@ -0,0 +1,7 @@
+---
+title: examples
+id: examples
+weight: 40
+draft: false
+author: "people"
+---

content/lua.scripts.manual/scripts/examples/api_version.md

@@ -0,0 +1,31 @@
+---
+title: api_version
+id: api_version
+weight: 10
+draft: false
+author: "people"
+---
+
+## Name
+
+api_version.lua - show the Lua API version
+
+## Description
+
+darktable script to show the Lua API version in the preferences
+
+## Usage
+
+* require this script from your main lua file
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Tobias Jakobs
+
+## Change Log

content/lua.scripts.manual/scripts/examples/darkroom_demo.md

@@ -0,0 +1,33 @@
+---
+title: darkroom_demo
+id: darkroom_demo
+weight: 20
+draft: false
+author: "people"
+---
+
+## Name
+
+darkroom_demo - an example script demonstrating how to control image display in darkroom mode
+
+## Description
+
+darkroom_demo is an example script showing how to control the currently displayed image in 
+darkroom mode using lua.
+
+## Usage
+
+* require this script from your main lua file
+
+## Additional Software Required
+
+None
+
+## Limitations
+
+
+## Author
+
+Bill Ferguson - wpferguson@gmail.com
+
+## Change Log

content/lua.scripts.manual/scripts/examples/gettextExample.md

@@ -0,0 +1,59 @@
+---
+title: gettextExample
+id: gettextExample
+weight: 30
+draft: false
+author: "people"
+---
+
+## Name
+
+gettextExample.lua - darktable script to show how translations works
+
+## Description
+
+To create the .po file run:
+xgettext -l lua gettextExample.lua
+
+xgettext is not a lua tool, it knows (almost) nothing about Lua, and not 
+enough to do a proper parsing. It takes a text file (In our case a Lua 
+file) and recognises a few (language dependant) keyword in there.
+It matches those keywords with internal description on how functions are 
+called and creates the .po file accordingly. (For example, it knows that 
+the first argument of gettext() is the translated string, but that it's 
+the second argument for dgettext)
+This is important because it means that if you use some neat Lua tricks
+(like renaming functions) xgettext won't recognize those calls and won't 
+extract the string to the .po file.
+So, this is why we create a local variagle gettext = dt.gettext, so 
+xgettext recognises gettext.gettext as a function but not dt.gettext.gettext
+
+To create a .mo file run:
+msgfmt -v gettextExample.po -o gettextExample.mo
+
+## Usage
+
+* require this script from your main lua file (Add 'require "gettextExample"' to luarc.)
+* copy the script to: .config/darktable/lua/
+* copy the gettextExample.mo to .config/darktable/lua/de_DE/LC_MESSAGES
+
+You need to start darktable with the Lua debug option: darktable -d lua
+$LANG must set to: de_DE
+
+The script run on darktable startup and should output this three lines:
+
+LUA ERROR Hello World!
+LUA ERROR Bild
+LUA ERROR Hallo Welt!
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Tobias Jakobs
+
+## Change Log

content/lua.scripts.manual/scripts/examples/hello_world.md

@@ -0,0 +1,31 @@
+---
+title: hello_world
+id: hello_world
+weight: 40
+draft: false
+author: "people"
+---
+
+## Name
+
+hello_world.lua - a simple lua script 
+
+## Description
+
+prints "hello world when DT starts
+
+## Usage
+
+* require this file from your main lua config file:
+
+## Additional Software Required
+
+
+## Limitations
+
+
+## Author
+
+Tobias Ellinghaus
+
+## Change Log