From 1cf789109591924fed62fb539e8ff80c06b11d09 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 16:49:41 -0700 Subject: [PATCH 01/22] propose CCSMB-11 --- Standards/CCSMB-11.md | 91 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 Standards/CCSMB-11.md diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md new file mode 100644 index 0000000..8ac027e --- /dev/null +++ b/Standards/CCSMB-11.md @@ -0,0 +1,91 @@ +# *CCSMB-11*: Desktop Application Discovery + +*Author: Tomodachi94* + +*Version:* + +*Last revised:* + +## Rationale + +Currently, most ComputerCraft graphical operating systems, windowing and desktop management systems, and application launchers (collectively "target software") define their own method of discovering and launching applications. The behavior and expectations for each piece of target software vary wildly; for example, some target software expects programs to manage their own windowing through system-specific APIs, while other target software manages it entirely for all programs. Additionally, installation scripts and package managers ("software management tooling") contains wildly inconsistent behavior, varying from not defining any sort of application discovery, containing support for one or two specific target softwares, or attempting to maintain support for *all* target software. + +The purpose of this specification is to standardize behavior for installing, discovering, and launching graphical applications, enabling greater interoperability in all target software and software management tooling. + +## Application specifications + +Central to the specification are "application specifications". Each application specification MUST be a Lua file with valid syntax. Each specification MUST return a table. The table specified in each application specification MUST contain the following fields: + +| Field | Type | Description | +|-------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| Name | str | A human-readable name of the application. | +| Type | str ("Application") | The type of the entry. Compliant software SHOULD ignore the whole entry if this is set to an unknown value. | +| Exec | str | The path to the file to execute, including arguments. The full path MAY be omitted if it is present in `shell.getPath`. | +| Terminal | bool | Whether to run the application in a terminal or not. | +| ManagesOwnWindows | bool | Whether the application manages its own windows through a system-specific API. If set to `true`, compliant specifications SHOULD define `ShowIn` (see below) | + +Compliant application specifications MAY define the following additional fields: + +| Field | Type | Description | +|-------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | +| Categories | number-indexed array of str | Categories in which the application should be shown in application launchers. For a list of valid values, see the [FreeDesktop Desktop Menu specification](https://www.freedesktop.org/wiki/Specifications/menu-spec/). | +| Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | +| ShowIn | number-indexed array of str | A list of target software that the application specification should be listed in. Compliant target software SHOULD ignore the specification if this field is set and the target software is not listed here. | + +Compliant software MAY define extra fields, but they MUST prefixed with `X-`. Compliant software SHOULD ignore all unrecognized fields without the prefix. + +## Global variables + +Compliant graphical OSes and desktop managers MUST set the `CCSMB_DESKTOP_CURRENT_DESKTOP` global variable, a string containing the name or path of the file executed that launched the OS or desktop manager. The variable MAY contain the command-line arguments that the graphical OS or desktop manager was started with, but this is optional and SHOULD NOT be expected by software. + +Software MAY use this variable when determining what graphical OS or desktop manager is running. + +Compliant graphical OSes and desktop managers SHOULD set this variable to `nil` when exiting. + +## Module + +Compliant software MAY define the `ccsmb_desktop` module, but it MUST contain the `ccsmb_desktop.run` function. +`ccsmb_desktop.run` function. The function MUST open a new window. The function MUST accept arguments in the same way that `shell.run` does: +> All arguments are concatenated together and then parsed as a command line. As a result, shell.run("program a b") is the same as shell.run("program", "a", "b"). +> - [CC: Tweaked documentation](https://tweaked.cc/module/shell.html#v:run) + +The function MAY fail if the application fails to launch or continue running for any reason. + +The `ccsmb_desktop` module MUST NOT contain any functions not specified above. + +## Settings + +This section defines variables that SHOULD be defined through the `settings` API ("settings"). + +### `ccsmb_desktop.search_targets` + +This setting MUST be an array of absolute directories. Each directory SHOULD contain valid application specifications. + +Compliant software MUST search all directories (in the order listed). Compliant software MUST NOT assume the filenames in each directory are the same as the application names; however, software management tooling SHOULD install application specifications with a sensible filename. Application specifications SHOULD use the extension `.desktop`; `.lua` SHOULD also be allowed, but software management tooling SHOULD avoid installing specifications with this extension, to avoid confusion with actual programs. + +If this setting is not set, compliant software MAY search for the following directories in the order listed: +1. `/Application Specifications` +2. `/AppSpecs` +3. `/Applications` +4. `/etc/applications` +5. `/etc/ccsmb/applications` +6. `/usr/share/applications` +6. `/usr/share/ccsmb/applications` +7. `/Library/Application Specifications` + +### `ccsmb_desktop.install_target` + +This setting MUST be a string containing a path to a directory. The directory MUST be created. Compliant software management tooling MUST install applications in this directory. + +If the setting is not specified, software management tooling MUST search for all of the following directories and place specifications into them if they exist: +1. `/Application Specifications` +2. `/AppSpecs` +3. `/Applications` +4. `/etc/applications` +5. `/etc/ccsmb/applications` +6. `/usr/share/applications` +7. `/usr/share/ccsmb/applications` +8. `/Library/Application Specifications` + +Software management tooling MAY create a directory of its choosing from the above list if none exist. If software management tooling chooses to do this, the `ccsmb_desktop.install_target` setting MUST be set by the tooling. From 3a97c186370efceb6125dafdcb37ffaa4c6a4fe1 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 16:58:22 -0700 Subject: [PATCH 02/22] rename ManagesOwnWindows to CompliantWindowManagement --- Standards/CCSMB-11.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 8ac027e..2c93c91 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -17,12 +17,12 @@ The purpose of this specification is to standardize behavior for installing, dis Central to the specification are "application specifications". Each application specification MUST be a Lua file with valid syntax. Each specification MUST return a table. The table specified in each application specification MUST contain the following fields: | Field | Type | Description | -|-------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| Name | str | A human-readable name of the application. | -| Type | str ("Application") | The type of the entry. Compliant software SHOULD ignore the whole entry if this is set to an unknown value. | -| Exec | str | The path to the file to execute, including arguments. The full path MAY be omitted if it is present in `shell.getPath`. | -| Terminal | bool | Whether to run the application in a terminal or not. | -| ManagesOwnWindows | bool | Whether the application manages its own windows through a system-specific API. If set to `true`, compliant specifications SHOULD define `ShowIn` (see below) | +|---------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------| +| Name | str | A human-readable name of the application. | +| Type | str ("Application") | The type of the entry. Compliant software SHOULD ignore the whole entry if this is set to an unknown value. | +| Exec | str | The path to the file to execute, including arguments. The full path MAY be omitted if it is present in `shell.getPath`. | +| Terminal | bool | Whether to run the application in a terminal or not. | +| CompliantWindowManagement | bool | Whether the application manages its own windows through a system-specific API. If set to `false`, compliant specifications SHOULD define `ShowIn` (see below) | Compliant application specifications MAY define the following additional fields: From 175b9a7e63cdf803621c86daf390e6c8e7c8ac20 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:17:38 -0700 Subject: [PATCH 03/22] add Icon field --- Standards/CCSMB-11.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 2c93c91..9c59b35 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -28,6 +28,7 @@ Compliant application specifications MAY define the following additional fields: | Field | Type | Description | |-------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Icon | str | A path to a square image representing the application. The file MAY be a BIMG file; other formats are permitted but discouraged. | | GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | | Categories | number-indexed array of str | Categories in which the application should be shown in application launchers. For a list of valid values, see the [FreeDesktop Desktop Menu specification](https://www.freedesktop.org/wiki/Specifications/menu-spec/). | | Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | From af434b7beb935bae80f06f94439d7559148acad3 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:23:07 -0700 Subject: [PATCH 04/22] fix error --- Standards/CCSMB-11.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 9c59b35..b661d3b 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -46,8 +46,7 @@ Compliant graphical OSes and desktop managers SHOULD set this variable to `nil` ## Module -Compliant software MAY define the `ccsmb_desktop` module, but it MUST contain the `ccsmb_desktop.run` function. -`ccsmb_desktop.run` function. The function MUST open a new window. The function MUST accept arguments in the same way that `shell.run` does: +Compliant software MAY define the `ccsmb_desktop` module, but it MUST contain the `ccsmb_desktop.run` function. The function MUST open a new window. The function MUST accept arguments in the same way that `shell.run` does: > All arguments are concatenated together and then parsed as a command line. As a result, shell.run("program a b") is the same as shell.run("program", "a", "b"). > - [CC: Tweaked documentation](https://tweaked.cc/module/shell.html#v:run) From ce55041b3956aa58a337903112aee14a6ad0ff0a Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:25:40 -0700 Subject: [PATCH 05/22] CompliantWindowManagement implied true if Terminal true --- Standards/CCSMB-11.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index b661d3b..99e4e68 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -17,12 +17,12 @@ The purpose of this specification is to standardize behavior for installing, dis Central to the specification are "application specifications". Each application specification MUST be a Lua file with valid syntax. Each specification MUST return a table. The table specified in each application specification MUST contain the following fields: | Field | Type | Description | -|---------------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| Name | str | A human-readable name of the application. | -| Type | str ("Application") | The type of the entry. Compliant software SHOULD ignore the whole entry if this is set to an unknown value. | -| Exec | str | The path to the file to execute, including arguments. The full path MAY be omitted if it is present in `shell.getPath`. | -| Terminal | bool | Whether to run the application in a terminal or not. | -| CompliantWindowManagement | bool | Whether the application manages its own windows through a system-specific API. If set to `false`, compliant specifications SHOULD define `ShowIn` (see below) | +|---------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Name | str | A human-readable name of the application. | +| Type | str ("Application") | The type of the entry. Compliant software SHOULD ignore the whole entry if this is set to an unknown value. | +| Exec | str | The path to the file to execute, including arguments. The full path MAY be omitted if it is present in `shell.getPath`. | +| Terminal | bool | Whether to run the application in a terminal or not. | +| CompliantWindowManagement | bool | Whether the application manages its own windows through a system-specific API. If set to `false`, compliant specifications SHOULD define `ShowIn` (see below). If `Terminal` is set to `true`, this is implied to be `true`. | Compliant application specifications MAY define the following additional fields: From fa925079c323980c7dfefbcadaac84d35e1740c5 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:28:27 -0700 Subject: [PATCH 06/22] use emdash --- Standards/CCSMB-11.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 99e4e68..f9d94ac 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -46,9 +46,9 @@ Compliant graphical OSes and desktop managers SHOULD set this variable to `nil` ## Module -Compliant software MAY define the `ccsmb_desktop` module, but it MUST contain the `ccsmb_desktop.run` function. The function MUST open a new window. The function MUST accept arguments in the same way that `shell.run` does: +Compliant graphical OSes and desktop managers MAY define the `ccsmb_desktop` module, but it MUST contain the `ccsmb_desktop.run` function. The function MUST open a new window. The function MUST accept arguments in the same way that `shell.run` does: > All arguments are concatenated together and then parsed as a command line. As a result, shell.run("program a b") is the same as shell.run("program", "a", "b"). -> - [CC: Tweaked documentation](https://tweaked.cc/module/shell.html#v:run) +> — [CC: Tweaked documentation](https://tweaked.cc/module/shell.html#v:run) The function MAY fail if the application fails to launch or continue running for any reason. From 5c8a9f4bb938a9943a05bfd7f119a1efc554f2a6 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:31:10 -0700 Subject: [PATCH 07/22] define behavior for target programs where no path found --- Standards/CCSMB-11.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index f9d94ac..8e7bf18 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -64,21 +64,23 @@ This setting MUST be an array of absolute directories. Each directory SHOULD con Compliant software MUST search all directories (in the order listed). Compliant software MUST NOT assume the filenames in each directory are the same as the application names; however, software management tooling SHOULD install application specifications with a sensible filename. Application specifications SHOULD use the extension `.desktop`; `.lua` SHOULD also be allowed, but software management tooling SHOULD avoid installing specifications with this extension, to avoid confusion with actual programs. -If this setting is not set, compliant software MAY search for the following directories in the order listed: +If this setting is not set, compliant software MAY search in the following directories in the order listed: 1. `/Application Specifications` 2. `/AppSpecs` 3. `/Applications` 4. `/etc/applications` 5. `/etc/ccsmb/applications` 6. `/usr/share/applications` -6. `/usr/share/ccsmb/applications` -7. `/Library/Application Specifications` +7. `/usr/share/ccsmb/applications` +8. `/Library/Application Specifications` + +If none of the directories listed above exist, compliant software MAY create a directory of its choice, provided it sets this setting and `ccsmb_desktop.install_target` (defined below). ### `ccsmb_desktop.install_target` This setting MUST be a string containing a path to a directory. The directory MUST be created. Compliant software management tooling MUST install applications in this directory. -If the setting is not specified, software management tooling MUST search for all of the following directories and place specifications into them if they exist: +If the setting is not specified, software management tooling MUST search for all of the following directories and place specifications into them if the first match exists: 1. `/Application Specifications` 2. `/AppSpecs` 3. `/Applications` @@ -88,4 +90,4 @@ If the setting is not specified, software management tooling MUST search for all 7. `/usr/share/ccsmb/applications` 8. `/Library/Application Specifications` -Software management tooling MAY create a directory of its choosing from the above list if none exist. If software management tooling chooses to do this, the `ccsmb_desktop.install_target` setting MUST be set by the tooling. +Software management tooling MAY create a directory of its choosing from the above list if none exist. If software management tooling chooses to do this, the `ccsmb_desktop.install_target` and `ccsmb_desktop.search_targets` settings MUST be set by the tooling. From 33dabd7c738efe104e1ebbe677c7c478ac34b8ee Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:42:04 -0700 Subject: [PATCH 08/22] reorder suggested dirs --- Standards/CCSMB-11.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 8e7bf18..1329dac 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -67,11 +67,11 @@ Compliant software MUST search all directories (in the order listed). Compliant If this setting is not set, compliant software MAY search in the following directories in the order listed: 1. `/Application Specifications` 2. `/AppSpecs` -3. `/Applications` -4. `/etc/applications` -5. `/etc/ccsmb/applications` -6. `/usr/share/applications` -7. `/usr/share/ccsmb/applications` +3. `/etc/ccsmb/applications` +4. `/usr/share/ccsmb/applications` +5. `/Applications` +6. `/etc/applications` +7. `/usr/share/applications` 8. `/Library/Application Specifications` If none of the directories listed above exist, compliant software MAY create a directory of its choice, provided it sets this setting and `ccsmb_desktop.install_target` (defined below). @@ -83,11 +83,11 @@ This setting MUST be a string containing a path to a directory. The directory MU If the setting is not specified, software management tooling MUST search for all of the following directories and place specifications into them if the first match exists: 1. `/Application Specifications` 2. `/AppSpecs` -3. `/Applications` -4. `/etc/applications` -5. `/etc/ccsmb/applications` -6. `/usr/share/applications` -7. `/usr/share/ccsmb/applications` +3. `/etc/ccsmb/applications` +4. `/usr/share/ccsmb/applications` +5. `/Applications` +6. `/etc/applications` +7. `/usr/share/applications` 8. `/Library/Application Specifications` Software management tooling MAY create a directory of its choosing from the above list if none exist. If software management tooling chooses to do this, the `ccsmb_desktop.install_target` and `ccsmb_desktop.search_targets` settings MUST be set by the tooling. From ecdb9639c9be7cf5aa855c849f4d1a32a0b2d647 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:50:03 -0700 Subject: [PATCH 09/22] be more explicit about ccsmb_desktop module --- Standards/CCSMB-11.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 1329dac..303c004 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -46,7 +46,9 @@ Compliant graphical OSes and desktop managers SHOULD set this variable to `nil` ## Module -Compliant graphical OSes and desktop managers MAY define the `ccsmb_desktop` module, but it MUST contain the `ccsmb_desktop.run` function. The function MUST open a new window. The function MUST accept arguments in the same way that `shell.run` does: +Compliant graphical OSes and desktop managers MAY define the `ccsmb_desktop` module. The module MAY be loaded through `require`; it MAY also be defined in the `ccsmb_desktop` global, but this is strongly discouraged. + +The `ccsmb_desktop` module MUST contain the `ccsmb_desktop.run` function. The function MUST open a new window. The function MUST accept arguments in the same way that `shell.run` does: > All arguments are concatenated together and then parsed as a command line. As a result, shell.run("program a b") is the same as shell.run("program", "a", "b"). > — [CC: Tweaked documentation](https://tweaked.cc/module/shell.html#v:run) From 68e64c651fac23f36fac878e0b05e7b72de2c71a Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 17:52:59 -0700 Subject: [PATCH 10/22] define keywords --- Standards/CCSMB-11.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 303c004..8392ba4 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -6,6 +6,8 @@ *Last revised:* +The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are defined in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + ## Rationale Currently, most ComputerCraft graphical operating systems, windowing and desktop management systems, and application launchers (collectively "target software") define their own method of discovering and launching applications. The behavior and expectations for each piece of target software vary wildly; for example, some target software expects programs to manage their own windowing through system-specific APIs, while other target software manages it entirely for all programs. Additionally, installation scripts and package managers ("software management tooling") contains wildly inconsistent behavior, varying from not defining any sort of application discovery, containing support for one or two specific target softwares, or attempting to maintain support for *all* target software. From d8ff6723d0964496fc7dfcbcff460c438ff6d861 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 18:03:57 -0700 Subject: [PATCH 11/22] define behavior for app launchers when no search paths --- Standards/CCSMB-11.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 8392ba4..17d8779 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -80,6 +80,8 @@ If this setting is not set, compliant software MAY search in the following direc If none of the directories listed above exist, compliant software MAY create a directory of its choice, provided it sets this setting and `ccsmb_desktop.install_target` (defined below). +If none of the directories listed aboove exist, application launchers MAY choose to abort launching themselves or to remain open and empty. + ### `ccsmb_desktop.install_target` This setting MUST be a string containing a path to a directory. The directory MUST be created. Compliant software management tooling MUST install applications in this directory. From 3bb8e4e88c8967a73e9a9de2da91c6a8d1ee5af7 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 18:27:28 -0700 Subject: [PATCH 12/22] specify that funcs shouldn't be present --- Standards/CCSMB-11.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 17d8779..cabc245 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -16,7 +16,7 @@ The purpose of this specification is to standardize behavior for installing, dis ## Application specifications -Central to the specification are "application specifications". Each application specification MUST be a Lua file with valid syntax. Each specification MUST return a table. The table specified in each application specification MUST contain the following fields: +Central to the specification are "application specifications". Each application specification MUST be a Lua file with valid syntax. Each application specification SHOULD NOT call functions in their source. Each specification MUST return a table. The table specified in each application specification MUST contain the following fields: | Field | Type | Description | |---------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| From 1918d06333cb4af819c7ecfa32a995cf821b28e4 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 21:06:48 -0700 Subject: [PATCH 13/22] add examples --- .gitattributes | 2 ++ Standards/CCSMB-11/basic_compliant_program.desktop | 9 +++++++++ Standards/CCSMB-11/basic_noncompliant_program.desktop | 10 ++++++++++ 3 files changed, 21 insertions(+) create mode 100644 .gitattributes create mode 100644 Standards/CCSMB-11/basic_compliant_program.desktop create mode 100644 Standards/CCSMB-11/basic_noncompliant_program.desktop diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..43b4f7d --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# Syntax highlighting for .desktop files uses XDG syntax, not CCSMB syntax +Standards/CCSMB-11/*.desktop linguist-language=Lua diff --git a/Standards/CCSMB-11/basic_compliant_program.desktop b/Standards/CCSMB-11/basic_compliant_program.desktop new file mode 100644 index 0000000..5db1b1a --- /dev/null +++ b/Standards/CCSMB-11/basic_compliant_program.desktop @@ -0,0 +1,9 @@ +return { + Name = "pain"; + Type = "Application"; + Exec = "pain -n"; + Terminal = true; + CompliantWindowManagement = true; + GenericName = "Image Editor"; + Categories = { "Graphics", "RasterGraphics", "ImageProcessing" }; +} diff --git a/Standards/CCSMB-11/basic_noncompliant_program.desktop b/Standards/CCSMB-11/basic_noncompliant_program.desktop new file mode 100644 index 0000000..896d022 --- /dev/null +++ b/Standards/CCSMB-11/basic_noncompliant_program.desktop @@ -0,0 +1,10 @@ +return { + Name = "My Game With Noncompliant Windowing"; + Type = "Application"; + Icon = "/MyPartiallyCompliantOS/MyIcon.nfp"; + Exec = "/MyPartiallyCompliantOS/myfungame"; + Terminal = false; + CompliantWindowManagement = false; + ShowIn = { "/MyPartiallyCompliantOS/start" }; + Categories = { "Game", "Amusement" }; +} From 6374ff7f7d34cc49c8f5a926fdb080f383d82c6c Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 21:11:54 -0700 Subject: [PATCH 14/22] allow all deterministic functions in specs --- Standards/CCSMB-11.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index cabc245..b3c0f00 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -16,7 +16,7 @@ The purpose of this specification is to standardize behavior for installing, dis ## Application specifications -Central to the specification are "application specifications". Each application specification MUST be a Lua file with valid syntax. Each application specification SHOULD NOT call functions in their source. Each specification MUST return a table. The table specified in each application specification MUST contain the following fields: +Central to the specification are "application specifications". Each application specification MUST be a Lua file with valid syntax. Each application specification SHOULD NOT call non-builtin functions in their source (as well as functions introducing [non-determinism](https://en.wikipedia.org/wiki/Deterministic_system)). Each specification MUST return a table. The table specified in each application specification MUST contain the following fields: | Field | Type | Description | |---------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| From 0cc31ced2eaa48e9a273ff73b00610a60e126c22 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 22:55:38 -0700 Subject: [PATCH 15/22] permit icons to be multiple sizes Resolves https://github.com/CCSMB/Standards/pull/27#issuecomment-2016702738 --- Standards/CCSMB-11.md | 2 +- Standards/CCSMB-11/basic_noncompliant_program.desktop | 5 ++++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index b3c0f00..e487174 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -30,7 +30,7 @@ Compliant application specifications MAY define the following additional fields: | Field | Type | Description | |-------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Icon | str | A path to a square image representing the application. The file MAY be a BIMG file; other formats are permitted but discouraged. | +| Icon | str-indexed array of str | An array, where the keys are sizes in pixels (16x16 and 32x32 are common) and the values are paths to a square image representing the application. The file MAY be a BIMG file; other formats are permitted but discouraged. | | GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | | Categories | number-indexed array of str | Categories in which the application should be shown in application launchers. For a list of valid values, see the [FreeDesktop Desktop Menu specification](https://www.freedesktop.org/wiki/Specifications/menu-spec/). | | Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | diff --git a/Standards/CCSMB-11/basic_noncompliant_program.desktop b/Standards/CCSMB-11/basic_noncompliant_program.desktop index 896d022..d7f81fb 100644 --- a/Standards/CCSMB-11/basic_noncompliant_program.desktop +++ b/Standards/CCSMB-11/basic_noncompliant_program.desktop @@ -1,7 +1,10 @@ return { Name = "My Game With Noncompliant Windowing"; Type = "Application"; - Icon = "/MyPartiallyCompliantOS/MyIcon.nfp"; + Icon = { + ["16x16"] = "/MyPartiallyCompliantOS/MyIcon16x16.nfp"; + ["32x32"] = "/MyPartiallyCompliantOS/MyIcon32x32.nfp"; + }; Exec = "/MyPartiallyCompliantOS/myfungame"; Terminal = false; CompliantWindowManagement = false; From dee8c89558e3b1e04111a74c2388b3f3051301a6 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sat, 23 Mar 2024 23:03:45 -0700 Subject: [PATCH 16/22] Icon -> Icons --- Standards/CCSMB-11/basic_noncompliant_program.desktop | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Standards/CCSMB-11/basic_noncompliant_program.desktop b/Standards/CCSMB-11/basic_noncompliant_program.desktop index d7f81fb..c2fbd09 100644 --- a/Standards/CCSMB-11/basic_noncompliant_program.desktop +++ b/Standards/CCSMB-11/basic_noncompliant_program.desktop @@ -1,7 +1,7 @@ return { Name = "My Game With Noncompliant Windowing"; Type = "Application"; - Icon = { + Icons = { ["16x16"] = "/MyPartiallyCompliantOS/MyIcon16x16.nfp"; ["32x32"] = "/MyPartiallyCompliantOS/MyIcon32x32.nfp"; }; From 6c2bb0c7c2600b6a8a3cf7a802123aa18f56dacf Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sun, 24 Mar 2024 11:17:26 -0700 Subject: [PATCH 17/22] X- -> Extra array --- Standards/CCSMB-11.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index e487174..a53e0d9 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -29,14 +29,13 @@ Central to the specification are "application specifications". Each application Compliant application specifications MAY define the following additional fields: | Field | Type | Description | -|-------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Icon | str-indexed array of str | An array, where the keys are sizes in pixels (16x16 and 32x32 are common) and the values are paths to a square image representing the application. The file MAY be a BIMG file; other formats are permitted but discouraged. | -| GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | +|-------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Icons | str-indexed array of str | An array, where the keys are sizes in pixels (16x16 and 32x32 are common) and the values are paths to a square image representing the application. The file MAY be a BIMG file; other formats are permitted but discouraged. Software management tooling SHOULD install the icon(s) with an appropriate file extension. | +| GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | | Categories | number-indexed array of str | Categories in which the application should be shown in application launchers. For a list of valid values, see the [FreeDesktop Desktop Menu specification](https://www.freedesktop.org/wiki/Specifications/menu-spec/). | -| Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | -| ShowIn | number-indexed array of str | A list of target software that the application specification should be listed in. Compliant target software SHOULD ignore the specification if this field is set and the target software is not listed here. | - -Compliant software MAY define extra fields, but they MUST prefixed with `X-`. Compliant software SHOULD ignore all unrecognized fields without the prefix. +| Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | +| ShowIn | number-indexed array of str | A list of target software that the application specification should be listed in. Compliant target software SHOULD ignore the specification if this field is set and the target software is not listed here. | +| Extra | str-indexed array of str | An array containing extra fields not specified in this document. Software SHOULD ignore this field's values if it does not recognize them. | ## Global variables From b821fbaaa46766c651b431e11266f9ead05f221f Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sun, 24 Mar 2024 11:55:46 -0700 Subject: [PATCH 18/22] Make Icons into an array format --- Standards/CCSMB-11.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index a53e0d9..a53b45a 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -28,14 +28,23 @@ Central to the specification are "application specifications". Each application Compliant application specifications MAY define the following additional fields: -| Field | Type | Description | -|-------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Icons | str-indexed array of str | An array, where the keys are sizes in pixels (16x16 and 32x32 are common) and the values are paths to a square image representing the application. The file MAY be a BIMG file; other formats are permitted but discouraged. Software management tooling SHOULD install the icon(s) with an appropriate file extension. | -| GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | -| Categories | number-indexed array of str | Categories in which the application should be shown in application launchers. For a list of valid values, see the [FreeDesktop Desktop Menu specification](https://www.freedesktop.org/wiki/Specifications/menu-spec/). | -| Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | -| ShowIn | number-indexed array of str | A list of target software that the application specification should be listed in. Compliant target software SHOULD ignore the specification if this field is set and the target software is not listed here. | -| Extra | str-indexed array of str | An array containing extra fields not specified in this document. Software SHOULD ignore this field's values if it does not recognize them. | +| Field | Type | Description | +|-------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Icons | number-indexed array of array with fields | An array representing a set of icons for an application. Please see the below section for the format of this array. | +| GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | +| Categories | number-indexed array of str | Categories in which the application should be shown in application launchers. For a list of valid values, see the [FreeDesktop Desktop Menu specification](https://www.freedesktop.org/wiki/Specifications/menu-spec/). | +| Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | +| ShowIn | number-indexed array of str | A list of target software that the application specification should be listed in. Compliant target software SHOULD ignore the specification if this field is set and the target software is not listed here. | +| Extra | str-indexed array of str | An array containing extra fields not specified in this document. Software SHOULD ignore this field's values if it does not recognize them. | + +### `Icons` array + +| Field | Type | Description | +|--------|-----------------------------------|------------------------------------------------| +| Type | str (either "Vector" or "Bitmap") | The type of the icon, either bitmap or vector. | +| Width | number (must be same as Height) | The width of the icon, in pixels. | +| Height | number (must be same as Width) | The height of the icon, in pixels. | +| Path | str | The full path to the image file. | ## Global variables From 18237ce2082679c58bf8afe029d972115f41664f Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sun, 24 Mar 2024 15:16:41 -0700 Subject: [PATCH 19/22] rename settings options to be consistent --- Standards/CCSMB-11.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index a53b45a..c820708 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -70,7 +70,7 @@ The `ccsmb_desktop` module MUST NOT contain any functions not specified above. This section defines variables that SHOULD be defined through the `settings` API ("settings"). -### `ccsmb_desktop.search_targets` +### `ccsmb.desktop.search_targets` This setting MUST be an array of absolute directories. Each directory SHOULD contain valid application specifications. @@ -86,11 +86,11 @@ If this setting is not set, compliant software MAY search in the following direc 7. `/usr/share/applications` 8. `/Library/Application Specifications` -If none of the directories listed above exist, compliant software MAY create a directory of its choice, provided it sets this setting and `ccsmb_desktop.install_target` (defined below). +If none of the directories listed above exist, compliant software MAY create a directory of its choice, provided it sets this setting and `ccsmb.desktop.install_target` (defined below). If none of the directories listed aboove exist, application launchers MAY choose to abort launching themselves or to remain open and empty. -### `ccsmb_desktop.install_target` +### `ccsmb.desktop.install_target` This setting MUST be a string containing a path to a directory. The directory MUST be created. Compliant software management tooling MUST install applications in this directory. @@ -104,4 +104,4 @@ If the setting is not specified, software management tooling MUST search for all 7. `/usr/share/applications` 8. `/Library/Application Specifications` -Software management tooling MAY create a directory of its choosing from the above list if none exist. If software management tooling chooses to do this, the `ccsmb_desktop.install_target` and `ccsmb_desktop.search_targets` settings MUST be set by the tooling. +Software management tooling MAY create a directory of its choosing from the above list if none exist. If software management tooling chooses to do this, the `ccsmb.desktop.install_target` and `ccsmb.desktop.search_targets` settings MUST be set by the tooling. From 3cddd24e41b7bf202cdacd9ed2955493c8b53322 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sun, 24 Mar 2024 15:29:33 -0700 Subject: [PATCH 20/22] rework Icons again --- Standards/CCSMB-11.md | 8 ++++---- Standards/CCSMB-11/basic_noncompliant_program.desktop | 5 +++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index c820708..8f59967 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -28,9 +28,9 @@ Central to the specification are "application specifications". Each application Compliant application specifications MAY define the following additional fields: -| Field | Type | Description | +| Field | Type | Description | |-------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Icons | number-indexed array of array with fields | An array representing a set of icons for an application. Please see the below section for the format of this array. | +| Icons | number-indexed array of array with fields | An array representing a set of icons for an application. Compliant application specifications SHOULD have at least one square image (where width and height are identical). Please see the below section for the format of this array. | | GenericName | str | The "generic name" of the application. For example, for a file browser, this should be "File Browser". | | Categories | number-indexed array of str | Categories in which the application should be shown in application launchers. For a list of valid values, see the [FreeDesktop Desktop Menu specification](https://www.freedesktop.org/wiki/Specifications/menu-spec/). | | Keywords | number-indexed array of str | Keywords which, when combined with Name and GenericName, are useful for searching valid applications. | @@ -42,8 +42,8 @@ Compliant application specifications MAY define the following additional fields: | Field | Type | Description | |--------|-----------------------------------|------------------------------------------------| | Type | str (either "Vector" or "Bitmap") | The type of the icon, either bitmap or vector. | -| Width | number (must be same as Height) | The width of the icon, in pixels. | -| Height | number (must be same as Width) | The height of the icon, in pixels. | +| Width | number | The width of the icon, in pixels. | +| Height | number | The height of the icon, in pixels. | | Path | str | The full path to the image file. | ## Global variables diff --git a/Standards/CCSMB-11/basic_noncompliant_program.desktop b/Standards/CCSMB-11/basic_noncompliant_program.desktop index c2fbd09..d9626f6 100644 --- a/Standards/CCSMB-11/basic_noncompliant_program.desktop +++ b/Standards/CCSMB-11/basic_noncompliant_program.desktop @@ -2,8 +2,9 @@ return { Name = "My Game With Noncompliant Windowing"; Type = "Application"; Icons = { - ["16x16"] = "/MyPartiallyCompliantOS/MyIcon16x16.nfp"; - ["32x32"] = "/MyPartiallyCompliantOS/MyIcon32x32.nfp"; + { Type = "Bitmap"; Width = 16; Height = 16; Path = "/MyPartiallyCompliantOS/MyIcon16x16" }; + { Type = "Bitmap"; Width = 32; Height = 32; Path = "/MyPartiallyCompliantOS/MyIcon32x32" }; + { Type = "Bitmap"; Width = 60; Height = 32; Path = "/MyPartiallyCompliantOS/MyWordmark" }; }; Exec = "/MyPartiallyCompliantOS/myfungame"; Terminal = false; From 787b717a652bcf4885473c29ea99b4c2720a9254 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sun, 24 Mar 2024 15:48:32 -0700 Subject: [PATCH 21/22] add Icons[Format] --- Standards/CCSMB-11.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index 8f59967..e4d2df6 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -42,6 +42,7 @@ Compliant application specifications MAY define the following additional fields: | Field | Type | Description | |--------|-----------------------------------|------------------------------------------------| | Type | str (either "Vector" or "Bitmap") | The type of the icon, either bitmap or vector. | +| Format | str (e.g. "BIMG" or "NFP") | The format of the icon. | | Width | number | The width of the icon, in pixels. | | Height | number | The height of the icon, in pixels. | | Path | str | The full path to the image file. | From 6fbf8b2aaba0534b851729150bd5b844cbb39c26 Mon Sep 17 00:00:00 2001 From: Tomo <68489118+Tomodachi94@users.noreply.github.com> Date: Sun, 24 Mar 2024 16:52:09 -0700 Subject: [PATCH 22/22] remove Type in favor of Format --- Standards/CCSMB-11.md | 13 ++++++------- .../CCSMB-11/basic_noncompliant_program.desktop | 6 +++--- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/Standards/CCSMB-11.md b/Standards/CCSMB-11.md index e4d2df6..30cae15 100644 --- a/Standards/CCSMB-11.md +++ b/Standards/CCSMB-11.md @@ -39,13 +39,12 @@ Compliant application specifications MAY define the following additional fields: ### `Icons` array -| Field | Type | Description | -|--------|-----------------------------------|------------------------------------------------| -| Type | str (either "Vector" or "Bitmap") | The type of the icon, either bitmap or vector. | -| Format | str (e.g. "BIMG" or "NFP") | The format of the icon. | -| Width | number | The width of the icon, in pixels. | -| Height | number | The height of the icon, in pixels. | -| Path | str | The full path to the image file. | +| Field | Type | Description | +|--------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Format | str (e.g. `image/paint` or `image/nft`) | The MIME type of the format of the icon, as [assigned by the IANA](https://www.iana.org/assignments/media-types/media-types.xhtml) or CCSMB. Software SHOULD ignore icon arrays that have an unrecognized MIME type. Software MAY accept unassigned MIME types. | +| Width | number | The width of the icon, in pixels. | +| Height | number | The height of the icon, in pixels. | +| Path | str | The full path to the image file. | ## Global variables diff --git a/Standards/CCSMB-11/basic_noncompliant_program.desktop b/Standards/CCSMB-11/basic_noncompliant_program.desktop index d9626f6..dc3daac 100644 --- a/Standards/CCSMB-11/basic_noncompliant_program.desktop +++ b/Standards/CCSMB-11/basic_noncompliant_program.desktop @@ -2,9 +2,9 @@ return { Name = "My Game With Noncompliant Windowing"; Type = "Application"; Icons = { - { Type = "Bitmap"; Width = 16; Height = 16; Path = "/MyPartiallyCompliantOS/MyIcon16x16" }; - { Type = "Bitmap"; Width = 32; Height = 32; Path = "/MyPartiallyCompliantOS/MyIcon32x32" }; - { Type = "Bitmap"; Width = 60; Height = 32; Path = "/MyPartiallyCompliantOS/MyWordmark" }; + { Format = "image/paint"; Width = 16; Height = 16; Path = "/MyPartiallyCompliantOS/MyIcon16x16" }; + { Format = "image/paint"; Width = 32; Height = 32; Path = "/MyPartiallyCompliantOS/MyIcon32x32" }; + { Format = "image/paint"; Width = 60; Height = 32; Path = "/MyPartiallyCompliantOS/MyWordmark" }; }; Exec = "/MyPartiallyCompliantOS/myfungame"; Terminal = false;