Skip to content

Commit aa33ae0

Browse files
wpfergusonwpferguson
authored
Merge pull request darktable-org#325 from wpferguson/doc_updates
Update documentation
2 parents f35cea7 + 4e9c45c commit aa33ae0

File tree

2 files changed

+121
-65
lines changed

2 files changed

+121
-65
lines changed

‎ChangeLog.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
## Changes from most recent to oldest
2+
3+
**17 Feb 2021 - wpferguson - API 6.2.3 register_action changes**
4+
5+
* Added check for API version and supplied a name argument if the
6+
API version was greater than or equal to 6.2.3
7+
8+
**10 Feb 2021 - wpferguson - bugfix select_untagged**
9+
10+
* Fixed callback to return a list of images as expected instead of
11+
doing the selection in the callback
12+
13+
**10 Feb 2021 - wpferguson - bugfix API 6.2.1 compatibility**
14+
15+
* The inline check for API version didn't handle argument return
16+
correctly so added a transition library with a register_event function
17+
override to check the API version and process the arguments correctly.
18+
19+
**9 Feb 2021 - wpferguson - bugfix API 6.2.2 compatibility**
20+
21+
* The inline check for API version didn't handle argument return
22+
correctly so changed it to a full if/else block
23+
24+
**4 Reb 2021 - wpferguson - API 6.2.2 compatibililty**
25+
26+
* Added check for API version and supplied a name argument to register_selection
27+
if the API version was greater than or eqal to 6.2.2
28+
29+
**1 Feb 2021 - wpferguson - API 6.2.1 compatibility**
30+
31+
* Added check for API version and supplied a name argument to register_event
32+
if the API version was greater than or eqal to 6.2.1
33+
34+
**21 Jan 2021 - wpferguson - Modified dtutils function find_image_by_id**
35+
36+
* For users with API 6.2.0 or greater - Enabled use of new API function
37+
darktable.database_get_image() in find_image_by_id().
38+
39+
**19 Jan 2021 - schwerdf - Added dtutils library function find_image_by_id()**
40+
41+
* Added new library function to retrieve an image from the library based on it's ID instead
42+
of it's row number in the database
43+
44+
**10 Jan 2021 - chrisaga - copy_attach_detach_tags localization**
45+
46+
**7 Jan 2021 - dtorop - add contrib/fujifilm_dynamic_range**
47+
48+
* add a new contrib script, fujifilm_dynamic_range to adjust exposure
49+
based on the exposure bias camera setting

‎README.md

Lines changed: 72 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,25 @@ efforts of the darktable developers, maintainers, contributors and community. Th
77
contained in the repository, whether they can be run by themselves (Standalone - Yes) or depend on other
88
scripts (Standalone - No), what operating systems they are known to work on (L - Linux, M - MacOS, W - Windows), and their purpose.
99

10+
For the latest changes, see the [ChangeLog](ChangeLog.md)
11+
1012
### Official Scripts
1113

1214
These scripts are written primarily by the darktable developers and maintained by the authors and/or repository maintainers. They are located in the official/ directory.
1315

1416
Name|Standalone|OS |Purpose
1517
----|:--------:|:---:|-------
16-
check_for_updates|Yes|LMW|Check for updates to darktable
17-
copy_paste_metadata|Yes|LMW|Copy and paste metadata, tags, ratings, and color labels between images
18-
delete_long_tags|Yes|LMW|Delete all tags longer than a specified length
19-
delete_unused_tags|Yes|LMW|Delete tags that have no associated images
20-
enfuse|No|L|Exposure blend several images (HDR)
21-
generate_image_txt|No|L|Generate txt sidecar files to be overlaid on zoomed images
22-
image_path_in_ui|Yes|LMW|Plugin to display selected image path
23-
import_filter_manager|Yes|LMW|Manager for import filters
24-
import_filters|No|LMW|Two import filters for use with import_filter_manager
25-
save_selection|Yes|LMW|Provide save and restore from multiple selection buffers
26-
selection_to_pdf|No|L|Generate a PDF file from the selected images
18+
[check_for_updates](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/check_for_updates)|Yes|LMW|Check for updates to darktable
19+
[copy_paste_metadata](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/copy_paste_metadata)|Yes|LMW|Copy and paste metadata, tags, ratings, and color labels between images
20+
[delete_long_tags](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/delete_long_tags)|Yes|LMW|Delete all tags longer than a specified length
21+
[delete_unused_tags](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/delete_unused_tags)|Yes|LMW|Delete tags that have no associated images
22+
[enfuse](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/enfuse)|No|L|Exposure blend several images (HDR)
23+
[generate_image_txt](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/generate_image_txt)|No|L|Generate txt sidecar files to be overlaid on zoomed images
24+
[image_path_in_ui](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/image_path_in_ui)|Yes|LMW|Plugin to display selected image path
25+
[import_filter_manager](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/import_filter_manager)|Yes|LMW|Manager for import filters
26+
[import_filters](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/import_filters)|No|LMW|Two import filters for use with import_filter_manager
27+
[save_selection](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/save_selection)|Yes|LMW|Provide save and restore from multiple selection buffers
28+
[selection_to_pdf](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/official/selection_to_pdf)|No|L|Generate a PDF file from the selected images
2729

2830

2931
### Contributed Scripts
@@ -32,69 +34,70 @@ These scripts are contributed by users. They are meant to have an "owner", i.e.
3234

3335
Name|Standalone|OS |Purpose
3436
----|:--------:|:---:|-------
35-
AutoGrouper|Yes|LMW|Group images together by time
36-
autostyle|Yes|LMW|Automatically apply styles on import
37-
clear_GPS|Yes|LMW|Reset GPS information for selected images
38-
CollectHelper|Yes|LMW|Add buttons to selected images module to manipulate the collection
39-
copy_attach_detach_tags|Yes|LMW|Copy and paste tags from/to images
40-
cr2hdr|Yes|L|Process image created with Magic Lantern Dual ISO
41-
enfuseAdvanced|No|LMW|Merge multiple images into Dynamic Range Increase (DRI) or Depth From Focus (DFF) images
42-
exportLUT|Yes|LMW|Create a LUT from a style and export it
43-
ext_editor|No|LW|Export pictures to collection and edit them with up to nine user-defined external editors
44-
face_recognition|No|LM|Identify and tag images using facial recognition
45-
fujifilm_ratings|No|LM|Support importing Fujifilm ratings
46-
geoJSON_export|No|L|Create a geo JSON script with thumbnails for use in ...
47-
geoToolbox|No|LMW|A toolbox of geo functions
48-
gimp|No|LMW|Open an image in GIMP for editing and return the result
49-
gpx_export|No|LMW|Export a GPX track file from selected images GPS data
50-
HDRMerge|No|LMW|Combine the selected images into an HDR DNG and return the result
51-
hugin|No|LMW|Combine selected images into a panorama and return the result
52-
image_stack|No|LMW|Combine a stack of images to remove noise or transient objects
53-
image_time|Yes|LMW|Adjust the EXIF image time
54-
kml_export|No|L|Export photos with a KML file for usage in Google Earth
55-
LabelsToTags|Yes|LMW|Apply tags based on color labels and ratings
56-
OpenInExplorer|No|LMW|Open the selected images in the system file manager
57-
passport_guide|Yes|LMW|Add passport cropping guide to darkroom crop tool
58-
pdf_slideshow|No|LM|Export images to a PDF slideshow
59-
[photils](https://github.com/scheckmedia/photils-dt)|No|LM|Automatic tag suggestions for your images
60-
quicktag|Yes|LMW|Create shortcuts for quickly applying tags
61-
rate_group|Yes|LMW|Apply or remove a star rating from grouped images
62-
rename-tags|Yes|LMW|Change a tag name
63-
RL_out_sharp|No|LW|Output sharpening using GMic (Richardson-Lucy algorithm)
64-
select_untagged|Yes|LMW|Enable selection of untagged images
65-
slideshowMusic|No|L|Play music during a slideshow
66-
transfer_hierarchy|Yes|LMW|Image move/copy preserving directory hierarchy
67-
video_ffmpeg|No|LMW|Export video from darktable
37+
[AutoGrouper](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/AutoGrouper)|Yes|LMW|Group images together by time
38+
[autostyle](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/autostyle)|Yes|LMW|Automatically apply styles on import
39+
[clear_GPS](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/clear_GPS)|Yes|LMW|Reset GPS information for selected images
40+
[CollectHelper](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/CollectHelper)|Yes|LMW|Add buttons to selected images module to manipulate the collection
41+
[copy_attach_detach_tags](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/copy_attach_detach_tags)|Yes|LMW|Copy and paste tags from/to images
42+
[cr2hdr](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/cr2hdr)|Yes|L|Process image created with Magic Lantern Dual ISO
43+
[enfuseAdvanced](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/enfuseAdvanced)|No|LMW|Merge multiple images into Dynamic Range Increase (DRI) or Depth From Focus (DFF) images
44+
[exportLUT](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/exportLUT)|Yes|LMW|Create a LUT from a style and export it
45+
[ext_editor](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/ext_editor)|No|LW|Export pictures to collection and edit them with up to nine user-defined external editors
46+
[face_recognition](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/face_recognition)|No|LM|Identify and tag images using facial recognition
47+
[fujifilm_dynamic_range](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/fujifilm_dynamic_range)|No|LMW|Correct fujifilm exposure based on exposure bias camera setting
48+
[fujifilm_ratings](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/fujifilm_ratings)|No|LM|Support importing Fujifilm ratings
49+
[geoJSON_export](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/geoJSON_export)|No|L|Create a geo JSON script with thumbnails for use in ...
50+
[geoToolbox](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/geoToolbox)|No|LMW|A toolbox of geo functions
51+
[gimp](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/gimp)|No|LMW|Open an image in GIMP for editing and return the result
52+
[gpx_export](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/gpx_export)|No|LMW|Export a GPX track file from selected images GPS data
53+
[HDRMerge](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/HDRMerge)|No|LMW|Combine the selected images into an HDR DNG and return the result
54+
[hugin](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/hugin)|No|LMW|Combine selected images into a panorama and return the result
55+
[image_stack](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/image_stack)|No|LMW|Combine a stack of images to remove noise or transient objects
56+
[image_time](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/image_time)|Yes|LMW|Adjust the EXIF image time
57+
[kml_export](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/kml_export)|No|L|Export photos with a KML file for usage in Google Earth
58+
[LabelsToTags](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/LabelsToTags)|Yes|LMW|Apply tags based on color labels and ratings
59+
[OpenInExplorer](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/OpenInExplorer)|No|LMW|Open the selected images in the system file manager
60+
[passport_guide](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/passport_guide)|Yes|LMW|Add passport cropping guide to darkroom crop tool
61+
[pdf_slideshow](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/pdf_slideshow)|No|LM|Export images to a PDF slideshow
62+
[photils](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/photils)|No|LM|Automatic tag suggestions for your images
63+
[quicktag](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/quicktag)|Yes|LMW|Create shortcuts for quickly applying tags
64+
[rate_group](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/rate_group)|Yes|LMW|Apply or remove a star rating from grouped images
65+
[rename-tags](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/rename-tags)|Yes|LMW|Change a tag name
66+
[RL_out_sharp](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/RL_out_sharp)|No|LW|Output sharpening using GMic (Richardson-Lucy algorithm)
67+
[select_untagged](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/select_untagged)|Yes|LMW|Enable selection of untagged images
68+
[slideshowMusic](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/slideshowMusic)|No|L|Play music during a slideshow
69+
[transfer_hierarchy](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/transfer_hierarchy)|Yes|LMW|Image move/copy preserving directory hierarchy
70+
[video_ffmpeg](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/contrib/video_ffmpeg)|No|LMW|Export video from darktable
6871

6972
### Example Scripts
7073

7174
These scripts provide examples of how to use specific portions of the API. They run, but are meant for demonstration purposes only. They are located in the examples/ directory.
7275

7376
Name|Standalone|OS |Purpose
7477
----|:--------:|:---:|-------
75-
api_version|Yes|LMW|Print the current API version
76-
darkroom_demo|Yes|LMW|Demonstrate changing images in darkoom
77-
gettextExample|Yes|LM|How to use translation
78-
hello_world|Yes|LMW|Prints hello world when darktable starts
79-
lighttable_demo|Yes|LMW|Demonstrate controlling lighttable mode, zoom, sorting and filtering
80-
moduleExample|Yes|LMW|How to create a lighttable module
81-
multi_os|No|LMW|How to create a cross platform script that calls an external executable
82-
panels_demo|Yes|LMW|Demonstrate hiding and showing darktable panels
83-
preferenceExamples|Yes|LMW|How to use preferences in a script
84-
printExamples|Yes|LMW|How to use various print functions from a script
85-
running_os|Yes|LMW|Print out the running operating system
78+
[api_version](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/api_version)|Yes|LMW|Print the current API version
79+
[darkroom_demo](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/darkroom_demo)|Yes|LMW|Demonstrate changing images in darkoom
80+
[gettextExample](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/gettextExample)|Yes|LM|How to use translation
81+
[hello_world](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/hello_world)|Yes|LMW|Prints hello world when darktable starts
82+
[lighttable_demo](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/lighttable_demo)|Yes|LMW|Demonstrate controlling lighttable mode, zoom, sorting and filtering
83+
[moduleExample](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/moduleExample)|Yes|LMW|How to create a lighttable module
84+
[multi_os](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/multi_os)|No|LMW|How to create a cross platform script that calls an external executable
85+
[panels_demo](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/panels_demo)|Yes|LMW|Demonstrate hiding and showing darktable panels
86+
[preferenceExamples](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/preferenceExamples)|Yes|LMW|How to use preferences in a script
87+
[printExamples](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/printExamples)|Yes|LMW|How to use various print functions from a script
88+
[running_os](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/examples/running_os)|Yes|LMW|Print out the running operating system
8689

8790
### Tools
8891

8992
Tool scripts perform functions relating to the repository, such as generating documentation. They are located in the tools/ directory.
9093

9194
Name|Standalone|OS |Purpose
9295
----|:--------:|:---:|-------
93-
executable_manager|Yes|LMW|Manage the external executables used by the lua scripts
94-
gen_i18n_mo|No|LMW|Generate compiled translation files (.mo) from source files (.po)
95-
get_lib_manpages|No|LM|Retrieve the library documentation and output it in man page and PDF format
96-
get_libdoc|No|LMW|Retrieve the library documentation and output it as text
97-
script_manager|No|LMW|Manage (install, update, enable, disable) the lua scripts
96+
[executable_manager](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/tools/executable_manager)|Yes|LMW|Manage the external executables used by the lua scripts
97+
[gen_i18n_mo](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/tools/gen_i18n_mo)|No|LMW|Generate compiled translation files (.mo) from source files (.po)
98+
[get_lib_manpages](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/tools/get_lib_manpages)|No|LM|Retrieve the library documentation and output it in man page and PDF format
99+
[get_libdoc](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/tools/get_libdoc)|No|LMW|Retrieve the library documentation and output it as text
100+
[script_manager](https://darktable-org.github.io/luadocs/lua.scripts.manual/scripts/tools/script_manager)|No|LMW|Manage (install, update, enable, disable) the lua scripts
98101

99102
### Related third-party projects
100103

@@ -219,15 +222,19 @@ To update the script repository, open a terminal or command prompt and do the fo
219222

220223
## Documentation
221224

222-
Each script includes its own documentation and usage in its header, please refer to them.
225+
The [Lua Scripts Manual](https://darktable-org.github.io/luadocs/lua.scripts.manual/) provides documentation
226+
for the scripts transcribed from the header comments. Each script also contains comments and usage instructions
227+
in the header comments.
223228

224-
Lua-script libraries documentation may be generated using the tools in the tools/ directory.
229+
The [Lua Scripts Library API Manual](https://darktable-org.github.io/luadocs/lua.scripts.api.manual/) provides
230+
documentation of the libraries and functions. Lua-script libraries documentation may also be generated using
231+
the tools in the tools/ directory.
225232

226233
More information about the scripting with Lua can be found in the darktable user manual:
227-
https://www.darktable.org/usermanual/en/lua_chapter.html
234+
[Scripting with Lua](https://darktable-org.github.io/dtdocs/lua/)
228235

229-
The darktable Lua API documentation is here:
230-
https://www.darktable.org/lua-api/
236+
The [Lua API Manual](https://darktable-org.github.io/luadocs/lua.api.manual/) provides docuemntation of the
237+
darktable Lua API.
231238

232239
## Troubleshooting
233240

0 commit comments

Comments
 (0)