def get_content_extra(self):
return "",
utils.get_bootstrap_alert(
heading=md("<strong>(*)</strong> ") + _("Why set a fixed applet width/height?"),
content=md(
"\n".join([
_("This option is for people that wants to use an instance of this applet at the end of a panel without an icon and without a label (like the button seen on Windows taskbars).")
])
)
),
def get_content_base(self, for_readme):
return "\n".join([
"## %s" % _("Description"),
"",
_("The function of this applet is very simple, create a menu based on the files/folders found inside a main folder (specified on this applet settings window). The files will be used to create menu items and the sub folders will be used to create sub-menus."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("I mainly created this applet to replicate the functionality of the XFCE plugin called **Directory Menu** and the KDE widget called **Quick access**."),
"",
utils.get_bootstrap_alert(
context="danger",
heading=_("Danger"),
content=_("This applet has to read every single file/folder inside a main folder to create its menu. So, do not try to use this applet to create a menu based on a folder that contains thousands of files!!! Your system may slow down, freeze or even crash!!!")
),
"",
"## %s" % _("Features"),
"",
"- %s" % _("More than one instance of this applet can be installed at the same time."),
"- %s" % _("A hotkey can be assigned to open/close the menu."),
"- %s" % _("Menu items to .desktop files will be displayed with the icon and name declared inside the .desktop files themselves."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _(
"The menu can be kept open while activating menu items by pressing [[Ctrl]] + **Left click** or with **Middle click**."),
"- %s" % _("This applet can create menu and sub-menu items even from symbolic links found inside the main folder."),
"",
])
def get_content_base(self, for_readme):
return "\n".join([
"## %s" % _("Description"),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("The Multi Translator extension is an extension ported from a gnome-shell extension called [Text Translator](https://github.com/gufoe/text-translator) by [gufoe](https://github.com/gufoe). It provides translation of text by different translation providers (currently [Google](https://translate.google.com), [Yandex](https://translate.yandex.net), [Bing](https://www.bing.com/translator), and [Apertium](https://www.apertium.org))."
),
"",
"## %s" % _("Dependencies"),
"",
utils.get_bootstrap_alert(
context="info",
heading=_("All dependencies are optional"),
content=md("\n".join([
"- %s" %
_("If the xsel command is missing, one cannot directly perform translations from selected text."
),
"- %s" %
_("If the trans command is missing, one cannot use translation engines that make use of translate-shell."
),
]))),
"",
# TO TRANSLATORS: Do not translate the word "xsel".
"- **%s**: %s" %
(_("xsel command"),
_("XSel is a command-line program for getting and setting the contents of the X selection."
)),
# TO TRANSLATORS: Do not translate the word "trans".
"- **%s**: %s" %
(_("trans command"),
_("Command provided by the package translate-shell. Is a simple command line interface for several translation providers (Google Translate, Yandex Translate, Bing Translate and Apertium) which allows you to translate strings in your terminal."
)),
" - [%s](https://github.com/soimort/translate-shell#dependencies)"
% _("Check translate-shell dependencies."),
" - [%s](https://github.com/soimort/translate-shell#recommended-dependencies)"
% _("Check translate-shell recommended dependencies."),
"",
utils.get_bootstrap_alert(
context="warning",
content=
_("The translate-shell package available on Ubuntu 16.04.x/Linux Mint 18.x repositories is outdated and broken. It can be installed anyway so it will also install its dependencies. But updating to the latest version should be done as described bellow."
)),
"",
])
def get_content_extra(self):
return md("{}".format("\n".join([
"## %s" % _("Usage"),
"",
utils.get_bootstrap_alert(
context="warning",
content="<strong>%s</strong>" % md(
_("Do not try to hide with this applet the Cinnamon's default System Tray applet (nor any other applet that acts as such). The original Drawer applet handles these types of applets in a very *hacky* way (it sets the size of the tray icons to zero when hiding them and sets them back to a hard-coded size when displaying them). I simply removed that behavior from this fork because I refuse to deal with the mess that the system tray mechanism is in Cinnamon."
))),
"",
"- %s" %
_("The applet does its job when it is placed inside the rigth box of a panel (bottom box for vertical panels). Do not place inside any other panel box."
),
"- %s" %
_("All applets that are placed in front of this applet (or on top of it in vertical panels) will be hidden."
),
])))
def get_content_base(self, for_readme):
return "\n".join([
"## %s" % _("Description"),
"",
_("The function of this applet is very simple, create a menu based on the files/folders found inside a main folder (specified on this applet settings window). The files will be used to create menu items and the sub folders will be used to create sub-menus."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("I mainly created this applet to replicate the functionality of the XFCE plugin called **Directory Menu** and the KDE widget called **Quick access**."),
"",
utils.get_bootstrap_alert(
context="danger",
heading=_("Danger"),
content=_("This applet has to read every single file/folder inside a main folder to create its menu. So, do not try to use this applet to create a menu based on a folder that contains thousands of files!!! Your system may slow down, freeze or even crash!!!")
),
"",
"## %s" % _("Features"),
"- %s" % _("More than one instance of this applet can be installed at the same time."),
"- %s" % _("A hotkey can be assigned to open/close the menu."),
"- %s" % _("Menu items to .desktop files will be displayed with the icon and name declared inside the .desktop files themselves."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _(
"The menu can be kept open while activating menu items by pressing [[Ctrl]] + **Left click** or with **Middle click**."),
"- %s" % _("This applet can create menu and sub-menu items even from symbolic links found inside the main folder."),
])
def get_content_extra(self):
return md("{}".format("\n".join([
'<span id="usage-{{lhc_lang_id}}"></span>',
"## %s" % _("Usage"),
"",
utils.get_bootstrap_alert(
content=md(
_("I will use the words *plugin* or *script* when referring to a script file associated with an instance of **Argos for Cinnamon** applet."))
),
"",
_("After placing a new instance of **Argos for Cinnamon** into a panel, one of the example scripts provided by this applet will be automatically attached to it and a menu will be created based on the output of the executed plugin. These example scripts contain various examples of what **Argos for Cinnamon** can do."),
"",
_("A just placed applet will have an initial execution interval of 0 seconds (zero seconds) and an initial applet text rotation interval of 3 seconds (three seconds). The execution interval is set to 0 seconds because the initial example script doesn't have any dynamic data that requires update. And the applet text rotation interval is set to 3 seconds so the text rotation of the example script can be seen in action."),
"",
_("For scripts that display non dynamic data, it isn't needed an execution interval. But if your script displays dynamic data (a clock for example), then an execution and/or applet text rotation interval needs to be specified. Both of these values can be set from the applet context menu."),
"",
utils.get_bootstrap_alert(
content=md(_("The three example scripts provided by this applet will produce the exact same output, but they are created using three different languages (**bash_examples.bash**, **python_examples.py** and **ruby_examples.rb**)."))
),
"",
utils.get_bootstrap_alert(
context="warning",
content="<strong>%s</strong>" % _(
"Never save your custom plugins/scripts inside this applet folder. Otherwise, you will loose them all when there is an update for the applet.")
),
"",
"### %s" % _("File name format"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("**Argos for Gnome Shell** parses the script's file name to extract certain set of preferences. **Argos for Cinnamon** doesn't parse the script's file name in such way (nor in any other way). All the applet settings can be set from the applet settings window and/or from the applet context menu."),
"### %s" % _("Output format"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Argos plugins are executables (such as shell scripts **(*)**) that print to standard output lines of the following form:"),
"""```
TEXT | ATTRIBUTE_1=VALUE ATTRIBUTE_2=VALUE ...
```""",
"",
_("All attributes are optional, so the most basic plugins simply print lines consisting of text to be displayed. To include whitespace, attribute values may be quoted using the same convention employed by most command line shells."),
"",
utils.get_bootstrap_alert(
content="<strong>%s</strong>" % _(
"(*) Not just shell scripts, but also python scripts, ruby scripts or any other script in any other language that can print to standard output.")
),
"",
"### %s" % _("Rendering"),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Lines containing only dashes (`---`) are *separators*."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Lines above the first separator belong to the applet button itself. If there are multiple such lines, they are displayed in succession, each of them for a configurable amount of time (rotation interval) before switching to the next. Additionally, all button lines get a dropdown menu item, except if their `dropdown` attribute is set to `false`."),
"",
_("Lines below the first separator are rendered as dropdown menu items. Further separators create graphical separator menu items."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Lines beginning with `--` are rendered in a submenu associated with the preceding unindented line. **Argos for Cinnamon** supports unlimited number of nested submenus."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("[Emoji codes](http://www.emoji-cheat-sheet.com) like `:horse:` and `:smile:` in the line text are replaced with their corresponding Unicode characters (unless the `emojize` attribute is set to `false`). Note that unpatched Cinnamon does not yet support multicolor emoji."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("[ANSI SGR escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code#graphics) and [Pango markup](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html) tags may be used for styling. This can be disabled by setting the `ansi` and `useMarkup` attributes, respectively, to `false`."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Backslash escapes such as `\\n` and `\\t` in the line text are converted to their corresponding characters (newline and tab in this case), which can be prevented by setting the `unescape` attribute to `false`. Newline escapes can be used to create multi-line menu items."),
"",
"## %s" % _("Line attributes"),
"",
"### %s" % _("Display"),
_("Control how the line is rendered."),
"",
"| %s | %s | %s |" % (_("Attribute"), _("Value"), _("Description")),
"| --- | --- | --- |",
"| `color` | %s | %s |" % (_("Hex RGB/RGBA or color name"),
_("Sets the text color for the item.")),
"| `font` | %s | %s |" % (_("Font name"), _("Sets the font for the item.")),
"| `size` | %s | %s |" % (_("Font size in points"), _(
"Sets the font size for the item.")),
"| `iconName` | %s | %s |" % (_("Icon name"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Sets a menu icon for the item. See the [freedesktop.org icon naming specification](https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html) for a list of names that should work anywhere, or run [gtk3-icon-browser](https://developer.gnome.org/gtk3/unstable/gtk3-icon-browser.html) to see the names of all icons in your current icon theme. **Argos only**. **Argos for Cinnamon** also supports a path to an icon file (paths starting with `~/` will be expanded to the user's home folder).")),
"| `image`, `templateImage` | %s | %s |" % (_("Base64-encoded image file"),
# TO TRANSLATORS: MARKDOWN string. Respect
# formatting.
_("Renders an image inside the item. The image is positioned to the left of the text and to the right of the icon. Cinnamon does not have a concept of *template images*, so `image` and `templateImage` are interchangeable in Argos.")),
"| `imageWidth`, `imageHeight` | %s | %s |" % (_("Width/height in pixels"),
# TO TRANSLATORS: MARKDOWN string. Respect
# formatting.
_("Sets the dimensions of the image. If only one dimension is specified, the image's original aspect ratio is maintained. **Argos only**.")),
"| `length` | %s | %s |" % (_("Length in characters"), _(
"Truncate the line text to the specified number of characters, ellipsizing the truncated part.")),
"| `trim` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |" %
(_("Boolean value"),
_("If disabled, preserve leading and trailing whitespace of the line text."), _("Enabled by default if not specified.")),
"| `dropdown` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |" %
(_("Boolean value"),
_("If disabled and the line is a button line (see above), exclude it from being displayed in the dropdown menu."), _("Enabled by default if not specified.")),
"| `alternate` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |" %
(_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If enabled, the item is hidden by default, and shown in place of the preceding item when the [[Alt]] key is pressed.")),
"| `emojize` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |" %
(_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If disabled, disable substitution of `:emoji_name:` with emoji characters in the line text."), _("Enabled by default if not specified.")),
"| `ansi` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |" %
(_("Boolean value"),
_("If disabled, disable interpretation of ANSI escape sequences in the line text."), _("Enabled by default if not specified.")),
"| `useMarkup` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |" %
(_("Boolean value"),
_("If disabled, disable interpretation of Pango markup in the line text. **Argos only**."), _("Enabled by default if not specified.")),
"| `unescape` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |" %
(_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If disabled, disable interpretation of backslash escapes such as `\\n` in the line text. **Argos only**."), _("Enabled by default if not specified.")),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Attributes available on **Argos for Cinnamon** only."),
"",
"| %s | %s | %s |" % (_("Attribute"), _("Value"), _("Description")),
"| --- | --- | --- |",
"| `tooltip` | %s | %s |" % (_("Text to display as toolip"),
_("Sets the tooltip for the item.")),
"| `iconSize` | %s | %s |" % (_("An integer from 12 to 512"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Sets the size for the menu item's icon if any. The size for menu item icons can be defined globally in the settings of an instance of Argos for Cinnamon.")),
"| `iconIsSymbolic` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |" %
(_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If enabled, the symbolic version of `iconName` will be used on the item (if exists). This attribute is ignored if the icon defined in `iconName` is a path to an icon file.")),
"### %s" % _("Actions"),
_("Define actions to be performed when the user clicks on the line's menu item."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Action attributes are *not* mutually exclusive. Any combination of them may be associated with the same item, and all actions are executed when the item is clicked."),
"",
"| %s | %s | %s |" % (_("Attribute"), _("Value"), _("Description")),
"| --- | --- | --- |",
"| `command`, `bash` | %s | **[(1)](#about-command-bash-attributes-{{lhc_lang_id}})** %s |" % (_("A command to execute"), _(
"Runs a command using a default shell specified in the options of an instance of Argos for Cinnamon or specified by the `shell` attribute.")),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `shell` | %s | %s |" % (_("Path or executable name of a shell program"), _(
"This attribute overrides the default shell set on the settings of an instance of Argos for Cinnamon. This attribute should only be used if one decides to use different shells to execute commands whithin the menu created by an instance of Argos for Cinnamon.")),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `shellArgument` | %s | %s |" % (_("Argument to pass to a shell program"), _(
"The argument used by a shell program that allows to execute a command. In most shells is '-c'. This attribute overrides the shell argument set on the settings of an instance of Argos for Cinnamon. This attribute should only be used if the shell argument set on the settings of an instance of Argos for Cinnamon isn't compatible with the shell specified in the `shell` attribute.")),
"| `terminal` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |" %
(_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If disabled, runs the command specified in the `command` or `bash` attributes in the background (i.e. without opening a terminal window). If enabled, a terminal will be opened to execute a command and will be kept open.")),
"| `param1`, `param2`, ... | %s | %s |" % (_("Command line arguments"),
# TO TRANSLATORS: MARKDOWN string. Respect
# formatting.
_("Arguments to be passed to the command specified in the `command` or `bash` attributes. *Note: Provided for compatibility with BitBar only. Argos allows placing arguments directly in the command string.*")),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `href` | URI | %s |" % _("Opens a URI in the application registered to handle it. URIs starting with `http://` launch the web browser, while `file://` URIs open the file in its associated default application. **Argos for Cinnamon** also supports paths starting with `~/` that will be automatically expanded to the user's home folder."),
"| `eval` | %s | %s |" % (_("JavaScript code"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Passes the code to JavaScript's `eval` function. **Argos only**.")),
"| `refresh` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |" %
(_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If enabled, re-runs the plugin, updating its output.")),
"",
'<span id="about-command-bash-attributes-{{lhc_lang_id}}"></span>',
"",
utils.get_bootstrap_alert(
heading="<strong>(1)</strong> %s" % _(
# TO TRANSLATORS: Full sentence:
# About the "command" and "bash" attributes.
# Do not translate nor modify the {command} and {bash} placeholders.
"About the {command} and {bash} attributes").format(
command="<code>command</code>",
bash="<code>bash</code>"),
content=md(_("These attributes are mutually exclusive. I added the `command` attribute because it didn't make much sense to have it named `bash` when Argos for Cinnamon can use any shell, not just Bash. I left the `bash` attribute so any scripts written for BitBar or for the original Argos for Gnome Shell extension can be used without modifications. I will never remove the `bash` attribute while the two previously mentioned tools keep using it."))
),
"",
'<span id="about-boolean-attributes-{{lhc_lang_id}}"></span>',
"",
utils.get_bootstrap_alert(
heading="<strong>(2)</strong> %s" % _("About boolean attributes"),
content=md(_("Any boolean attribute can have a value of `true` or `1` (one) to enable a feature/option. Or a value of `false` or `0` (zero) to disable a feature/option. Values are case-insensitive. Any other value will be considered `false`."))
),
"",
"### %s" % _("Environment variables"),
_("Plugin executables are run with the following special environment variables set:"),
"",
"| %s | %s |" % (_("Name"), _("Value")),
"| --- | --- |",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `ARGOS_VERSION` | %s |" % _(
"Version number of the Argos for Cinnamon applet. The presence of this environment variable can also be used to determine that the plugin is actually running in Argos, rather than BitBar or [kargos](https://github.com/lipido/kargos)."),
"| `ARGOS_MENU_OPEN` | %s |" % _(
"`true` if the dropdown menu was open at the time the plugin was run, and `false` otherwise."),
"",
'<span id="bitbar-plugins-with-argos-for-cinnamon-{{lhc_lang_id}}"></span>',
"",
"## %s" % _("BitBar plugins with Argos for Cinnamon"),
"",
utils.get_bootstrap_alert(
context="warning",
heading=_("WARNING!!! DO NOT RANDOMLY TEST SCRIPTS!!!"),
content=md("""
{0}
{1}
{2}
""".format("1. %s" % _("Apply common sense. Read and understand what a script does and how demanding it could be."),
"2. %s" % _(
"Test unknown scripts on an environment from which you can recover easily (for example, a virtual machine)."),
"3. %s" % _("I found one specific case in which a script can freeze and ultimately crash Cinnamon. It's a script that downloads a GIF image from the internet, converts it to Base64 and then that encoded image is inserted into a menu item using the *image* attribute. I will not provide a link to that script, but if you follow the very first advice that I listed here, when you see that script, you will know.")
)
)),
"",
_("These screenshots show how some scripts from the BitBar plugin repository look when rendered by Argos compared to the \"canonical\" BitBar rendering (macOS screenshots taken from https://getbitbar.com)."),
"",
"| %s | %s | %s |" % (_("Plugin"), _("BitBar on macOS"), _("Argos on Cinnamon")),
"| --- | :---: | :---: |",
"| [**Ping**](https://getbitbar.com/plugins/Network/ping.10s.sh) | <img src=\"./assets/images/image-ping-bitbar.png\" class=\"img-fluid\" alt=\"Ping/BitBar\"> | <img src=\"./assets/images/image-ping-argos.png\" class=\"img-fluid\" alt=\"Ping/Argos\"> |",
"| [**Stock Ticker**](https://getbitbar.com/plugins/Finance/gfinance.5m.py) | <img src=\"./assets/images/stock-ticker-bitbar.png\" class=\"img-fluid\" alt=\"Stock Ticker/BitBar\"> | <img src=\"./assets/images/stock-ticker-argos.png\" class=\"img-fluid\" alt=\"Stock Ticker/BitBar\"> |",
"| [**World Clock**](https://getbitbar.com/plugins/Time/worldclock.1s.sh) | <img src=\"./assets/images/world-clock-bitbar.png\" class=\"img-fluid\" alt=\"World Clock/BitBar\"> | <img src=\"./assets/images/world-clock-argos.png\" class=\"img-fluid\" alt=\"World Clock/BitBar\"> |",
"| [**ANSI**](https://getbitbar.com/plugins/Tutorial/ansi.sh) | <img src=\"./assets/images/ansi-bitbar.png\" class=\"img-fluid\" alt=\"ANSI/BitBar\"> | <img src=\"./assets/images/ansi-argos.png\" class=\"img-fluid\" alt=\"ANSI/BitBar\"> |",
])
))
def get_content_extra(self):
return md("{}".format("\n".join([
utils.get_bootstrap_alert(
context="warning",
content=md(
"\n".join([
"- %s" % _("This applet requires valid credentials from any of the weather provider services for it to work."),
"- %s" % _("The credentials cannot be used until they have been activated by the weather providers.")
])
)
),
"",
"## %s" % _("Getting API credentials"),
"",
_("Follow the instructions made available by the providers."),
"",
"### %s" % _("Weather providers"),
"",
"| %s | %s | %s |" % (_("Provider"), _(
"API credentials instructions"), _("Location finder")),
"| -- | -- | -- |",
"| %s | [%s](%s) | [%s](%s) |" % (
_("Dark Sky"),
_("Get credentials"), "https://darksky.net/dev",
_("Find location"), "https://darksky.net/forecast",
),
"| %s | [%s](%s) | [%s](%s) |" % (
_("OpenWeatherMap"),
_("Get credentials"), "https://openweathermap.org/appid",
_("Find location"), "https://openweathermap.org/find",
),
"| %s | [%s](%s) | [%s](%s) |" % (
_("WeatherBit"),
_("Get credentials"), "https://www.weatherbit.io/pricing",
_("Find location"), "https://openweathermap.org/find",
),
"| %s | [%s](%s) | [%s](%s) **(*)** |" % (
_("Yahoo! Weather"),
_("Get credentials"), "https://developer.yahoo.com/weather",
_("Find location"), "http://woeid.rosselliot.co.nz",
),
"",
"**(*)** %s" % _("WeatherBit uses the same city IDs returned by OpenWeatherMap's location finder in addition to coordinates."),
"",
"## %s" % _("Menu layout"),
"",
utils.get_image_container(
src="assets/images/menu-layout.png",
alt=_("Menu layout")
),
"",
"1. %s" % _("Current weather condition for the currently selected location."),
"2. %s" % _("Forecasts for the currently selected location."),
"3. %s" % _(
"The time in which the currently displayed data was published by the weather provider. Clicking it will attempt to retrieve updated weather data."),
"4. %s" % _("Button to open the locations selector menu."),
"5. %s" % _(
"Weather provider attribution. When clicked, it opens the weather provider website."),
"",
"## %s" % _("Locations manager"),
"",
utils.get_bootstrap_alert(
heading=_("Highlights"),
content=md(
"\n".join([
"- %s" % _("The locations manager can be accessed from this applet context menu."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("Locations with the exact same *Location ID* and *Provider* are considered duplicated and will be automatically removed when applying changes."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("The *Apply changes* button must be pressed for the applet to reflect the changes made in the locations manager."),
])
)
),
"",
utils.get_image_container(
src="assets/images/locations-manager.png",
alt=_("Locations manager")
),
"",
"- **%s**: %s" % (
_("Location name"),
_("This is an informative field and it isn't used to retrieve weather data. It is used to identify the displayed data in the menu and to generate the items inside the locations selector menu.")
),
"- **%s**: %s" % (
_("Location ID"),
_("A city/region ID used by the weather service providers to identify a location.")
),
" - %s" % _("Dark Sky uses only coordinates."),
" - %s" % _("Open Weather Map uses city IDs (the number at the end of a location URL) and coordinates."),
" - %s" % _("Yahoo! Weather uses WOEIDs and coordinates."),
"- **%s**: %s" % (
_("Language"),
_("Weather conditions localization. Languages are only used by DarkSky and OpenWeatherMap providers and it only affect weather conditions text. Any other text of the applet UI is localized by the applet itself (if available).")
),
"- **%s**: %s" % (
_("Forecast days"),
_("The amount of forecasts to display in the menu.")
),
"- **%s**: %s" % (
_("Forecast rows/columns"),
_("The amount of rows/cols to display the forecast days in.")
),
"- **%s**: %s" % (
_("Provider"),
_("Weather data provider. All weather providers require proper credentials to function.")
),
"",
"## %s" % _("Menu theme"),
"",
"- %s" % _("This applet supports custom themes to style its menu."),
"- %s" % _("The default theme (found in APPLET_FOLDER/themes/default.css) only sets a generic styling to accommodate the elements in the menu."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("To use a custom theme, just set the **Menu theme** option to **Custom** and set the **Path to custom style sheet** option to point to a style sheet file."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("To create a custom theme, just make a copy of the default theme file anywhere on the file system, **except** inside the applet folder. The default theme file has the complete list of CSS classes used by this applet."),
"- %s" % _("For the custom theme changes to be reflected on the menu while the theme file is modified, either Cinnamon can be restarted or the Cinnamon theme can be reloaded."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _(
"Cinnamon provides a command to reload its theme. Just open the **Run command** dialog ([[Alt]] + [[F2]]), type **rt** and press [[Enter]]."),
"",
"## %s" % _("Icon theme"),
"",
"- %s" % _("This applet supports custom icon themes."),
"- %s" % _("This applet comes with the possibility to choose 3 icon themes and they are named as follows."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - **%s**: %s" % (_("System"),
_("The applet will use the icons provided by the currently selected icon theme for the system.")),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - **%s**: %s" % (_("Built-in"),
_("The icons used are the ones found in APPLET_FOLDER/themes/icons.")),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - **%s**: %s" % (_("Custom"), _(
"The icons used are the ones found in the path defined in the **Path to custom icon theme** option.")),
"- %s" % _("An icon theme is just a folder that contains specifically named icon files."),
"- %s" % _("The built-in icon theme is a monochrome theme and is found in APPLET_FOLDER/themes/icons."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("The built-in icon theme can be used as full color or symbolic icons (applet settings **Menu icon type** and **Applet icon type**). The difference is that, if used as a full color theme, the icons will be black no matter if the Cinnamon theme selected has light or dark backgrounds for menus. On the other hand, if it is used as symbolic icons, the color of the icons will be set by the selected Cinnamon theme. Additionally, symbolic icons can be colorized through the custom CSS theme (applet setting **Menu theme**) by styling the `weather-forecast-icon` and `weather-current-icon` classes."),
"- %s" % _("To create a custom icon theme, the built-in icon theme can be used as a base."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("The built-in icon theme is composed of 36 *real images*, the rest of icons are symbolic links to these *real images*."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("Inside the built-in icon theme is a script called **z_symlinkify.bash** that can be used to create an icon theme from scratch. This script also contains the list of *real images* that are used to create the symbolic links."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("A custom icon theme can contain only full colored icons, only symbolic icons or both. The **Menu icon type** and **Applet icon type** applet settings should be set accordingly to the icon type used by the custom theme."),
"- %s" % _("A custom icon theme can contain SVG or PNG images; although SVG images are preferable due to their ability to scale into any icon size set in this applet settings without loosing quality. Other image types might be used, but I didn't test them."),
"- %s" % _("A custom icon theme should contain 232 icons to support both full color and symbolic icons. Or half of that (116) to support one or the other."),
])
))
def get_content_extra(self):
return md("{}".format("\n".join([
'<span id="usage-{{lhc_lang_id}}"></span>',
"## %s" % _("Usage"),
"",
utils.get_bootstrap_alert(content=md(
_("I will use the words *plugin* or *script* when referring to a script file associated with an instance of **Argos for Cinnamon** applet."
))),
"",
_("After placing a new instance of **Argos for Cinnamon** into a panel, one of the example scripts provided by this applet will be automatically attached to it and a menu will be created based on the output of the executed plugin. These example scripts contain various examples of what **Argos for Cinnamon** can do."
),
"",
_("A just placed applet will have an initial execution interval of 0 seconds (zero seconds) and an initial applet text rotation interval of 3 seconds (three seconds). The execution interval is set to 0 seconds because the initial example script doesn't have any dynamic data that requires update. And the applet text rotation interval is set to 3 seconds so the text rotation of the example script can be seen in action."
),
"",
_("For scripts that display non dynamic data, it isn't needed an execution interval. But if your script displays dynamic data (a clock for example), then an execution and/or applet text rotation interval needs to be specified. Both of these values can be set from the applet context menu."
),
"",
utils.get_bootstrap_alert(content=md(
_("The three example scripts provided by this applet will produce the exact same output, but they are created using three different languages (**bash_examples.bash**, **python_examples.py** and **ruby_examples.rb**)."
))),
"",
utils.get_bootstrap_alert(
context="warning",
content="<strong>%s</strong>" %
_("Never save your custom plugins/scripts inside this applet folder. Otherwise, you will loose them all when there is an update for the applet."
)),
"",
"### %s" % _("File name format"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("**Argos for Gnome Shell** parses the script's file name to extract certain set of preferences. **Argos for Cinnamon** doesn't parse the script's file name in such way (nor in any other way). All the applet settings can be set from the applet settings window and/or from the applet context menu."
),
"### %s" % _("Output format"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Argos plugins are executables (such as shell scripts **(*)**) that print to standard output lines of the following form:"
),
"""```
TEXT | ATTRIBUTE_1=VALUE ATTRIBUTE_2=VALUE ...
```""",
"",
_("All attributes are optional, so the most basic plugins simply print lines consisting of text to be displayed. To include whitespace, attribute values may be quoted using the same convention employed by most command line shells."
),
"",
utils.get_bootstrap_alert(content="<strong>%s</strong>" % _(
"(*) Not just shell scripts, but also python scripts, ruby scripts or any other script in any other language that can print to standard output."
)),
"",
"### %s" % _("Rendering"),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Lines containing only dashes (`---`) are *separators*."),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Lines above the first separator belong to the applet button itself. If there are multiple such lines, they are displayed in succession, each of them for a configurable amount of time (rotation interval) before switching to the next. Additionally, all button lines get a dropdown menu item, except if their `dropdown` attribute is set to `false`."
),
"",
_("Lines below the first separator are rendered as dropdown menu items. Further separators create graphical separator menu items."
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Lines beginning with `--` are rendered in a submenu associated with the preceding unindented line. **Argos for Cinnamon** supports unlimited number of nested submenus."
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("[Emoji codes](http://www.emoji-cheat-sheet.com) like `:horse:` and `:smile:` in the line text are replaced with their corresponding Unicode characters (unless the `emojize` attribute is set to `false`). Note that unpatched Cinnamon does not yet support multicolor emoji."
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("[ANSI SGR escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code#graphics) and [Pango markup](https://developer.gnome.org/pango/stable/PangoMarkupFormat.html) tags may be used for styling. This can be disabled by setting the `ansi` and `useMarkup` attributes, respectively, to `false`."
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Backslash escapes such as `\\n` and `\\t` in the line text are converted to their corresponding characters (newline and tab in this case), which can be prevented by setting the `unescape` attribute to `false`. Newline escapes can be used to create multi-line menu items."
),
"",
"## %s" % _("Line attributes"),
"",
"### %s" % _("Display"),
_("Control how the line is rendered."),
"",
"| %s | %s | %s |" %
(_("Attribute"), _("Value"), _("Description")),
"| --- | --- | --- |",
"| `color` | %s | %s |" % (_("Hex RGB/RGBA or color name"),
_("Sets the text color for the item.")),
"| `font` | %s | %s |" %
(_("Font name"), _("Sets the font for the item.")),
"| `size` | %s | %s |" %
(_("Font size in points"), _("Sets the font size for the item.")),
"| `iconName` | %s | %s |" % (
_("Icon name"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Sets a menu icon for the item. See the [freedesktop.org icon naming specification](https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html) for a list of names that should work anywhere, or run [gtk3-icon-browser](https://developer.gnome.org/gtk3/unstable/gtk3-icon-browser.html) to see the names of all icons in your current icon theme. **Argos only**. **Argos for Cinnamon** also supports a path to an icon file (paths starting with `~/` will be expanded to the user's home folder)."
)),
"| `image`, `templateImage` | %s | %s |" % (
_("Base64-encoded image file"),
# TO TRANSLATORS: MARKDOWN string. Respect
# formatting.
_("Renders an image inside the item. The image is positioned to the left of the text and to the right of the icon. Cinnamon does not have a concept of *template images*, so `image` and `templateImage` are interchangeable in Argos."
)),
"| `imageWidth`, `imageHeight` | %s | %s |" % (
_("Width/height in pixels"),
# TO TRANSLATORS: MARKDOWN string. Respect
# formatting.
_("Sets the dimensions of the image. If only one dimension is specified, the image's original aspect ratio is maintained. **Argos only**."
)),
"| `length` | %s | %s |" %
(_("Length in characters"),
_("Truncate the line text to the specified number of characters, ellipsizing the truncated part."
)),
"| `trim` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |"
%
(_("Boolean value"),
_("If disabled, preserve leading and trailing whitespace of the line text."
), _("Enabled by default if not specified.")),
"| `dropdown` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |"
%
(_("Boolean value"),
_("If disabled and the line is a button line (see above), exclude it from being displayed in the dropdown menu."
), _("Enabled by default if not specified.")),
"| `alternate` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |"
% (
_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If enabled, the item is hidden by default, and shown in place of the preceding item when the [[Alt]] key is pressed."
)),
"| `emojize` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |"
% (
_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If disabled, disable substitution of `:emoji_name:` with emoji characters in the line text."
),
_("Enabled by default if not specified.")),
"| `ansi` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |"
%
(_("Boolean value"),
_("If disabled, disable interpretation of ANSI escape sequences in the line text."
), _("Enabled by default if not specified.")),
"| `useMarkup` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |"
%
(_("Boolean value"),
_("If disabled, disable interpretation of Pango markup in the line text. **Argos only**."
), _("Enabled by default if not specified.")),
"| `unescape` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s %s |"
% (
_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If disabled, disable interpretation of backslash escapes such as `\\n` in the line text. **Argos only**."
),
_("Enabled by default if not specified.")),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Attributes available on **Argos for Cinnamon** only."),
"",
"| %s | %s | %s |" %
(_("Attribute"), _("Value"), _("Description")),
"| --- | --- | --- |",
"| `tooltip` | %s | %s |" % (_("Text to display as toolip"),
_("Sets the tooltip for the item.")),
"| `iconSize` | %s | %s |" % (
_("An integer from 12 to 512"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Sets the size for the menu item's icon if any. The size for menu item icons can be defined globally in the settings of an instance of Argos for Cinnamon."
)),
"| `iconIsSymbolic` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |"
% (
_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If enabled, the symbolic version of `iconName` will be used on the item (if exists). This attribute is ignored if the icon defined in `iconName` is a path to an icon file."
)),
"### %s" % _("Actions"),
_("Define actions to be performed when the user clicks on the line's menu item."
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Action attributes are *not* mutually exclusive. Any combination of them may be associated with the same item, and all actions are executed when the item is clicked."
),
"",
"| %s | %s | %s |" %
(_("Attribute"), _("Value"), _("Description")),
"| --- | --- | --- |",
"| `command`, `bash` | %s | **[(1)](#about-command-bash-attributes-{{lhc_lang_id}})** %s |"
%
(_("A command to execute"),
_("Runs a command using a default shell specified in the options of an instance of Argos for Cinnamon or specified by the `shell` attribute."
)),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `shell` | %s | %s |" %
(_("Path or executable name of a shell program"),
_("This attribute overrides the default shell set on the settings of an instance of Argos for Cinnamon. This attribute should only be used if one decides to use different shells to execute commands whithin the menu created by an instance of Argos for Cinnamon."
)),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `shellArgument` | %s | %s |" %
(_("Argument to pass to a shell program"),
_("The argument used by a shell program that allows to execute a command. In most shells is '-c'. This attribute overrides the shell argument set on the settings of an instance of Argos for Cinnamon. This attribute should only be used if the shell argument set on the settings of an instance of Argos for Cinnamon isn't compatible with the shell specified in the `shell` attribute."
)),
"| `terminal` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |"
% (
_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If disabled, runs the command specified in the `command` or `bash` attributes in the background (i.e. without opening a terminal window). If enabled, a terminal will be opened to execute a command and will be kept open."
)),
"| `param1`, `param2`, ... | %s | %s |" % (
_("Command line arguments"),
# TO TRANSLATORS: MARKDOWN string. Respect
# formatting.
_("Arguments to be passed to the command specified in the `command` or `bash` attributes. *Note: Provided for compatibility with BitBar only. Argos allows placing arguments directly in the command string.*"
)),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `href` | URI | %s |" %
_("Opens a URI in the application registered to handle it. URIs starting with `http://` launch the web browser, while `file://` URIs open the file in its associated default application. **Argos for Cinnamon** also supports paths starting with `~/` that will be automatically expanded to the user's home folder."
),
"| `eval` | %s | %s |" % (
_("JavaScript code"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Passes the code to JavaScript's `eval` function. **Argos only**."
)),
"| `refresh` | **[(2)](#about-boolean-attributes-{{lhc_lang_id}})** %s | %s |"
% (
_("Boolean value"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If enabled, re-runs the plugin, updating its output.")),
"",
'<span id="about-command-bash-attributes-{{lhc_lang_id}}"></span>',
"",
utils.get_bootstrap_alert(
heading="<strong>(1)</strong> %s" % _(
# TO TRANSLATORS: Full sentence:
# About the "command" and "bash" attributes.
# Do not translate nor modify the {command} and {bash} placeholders.
"About the {command} and {bash} attributes").format(
command="<code>command</code>",
bash="<code>bash</code>"),
content=md(
_("These attributes are mutually exclusive. I added the `command` attribute because it didn't make much sense to have it named `bash` when Argos for Cinnamon can use any shell, not just Bash. I left the `bash` attribute so any scripts written for BitBar or for the original Argos for Gnome Shell extension can be used without modifications. I will never remove the `bash` attribute while the two previously mentioned tools keep using it."
))),
"",
'<span id="about-boolean-attributes-{{lhc_lang_id}}"></span>',
"",
utils.get_bootstrap_alert(
heading="<strong>(2)</strong> %s" %
_("About boolean attributes"),
content=md(
_("Any boolean attribute can have a value of `true` or `1` (one) to enable a feature/option. Or a value of `false` or `0` (zero) to disable a feature/option. Values are case-insensitive. Any other value will be considered `false`."
))),
"",
"### %s" % _("Environment variables"),
_("Plugin executables are run with the following special environment variables set:"
),
"",
"| %s | %s |" % (_("Name"), _("Value")),
"| --- | --- |",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"| `ARGOS_VERSION` | %s |" %
_("Version number of the Argos for Cinnamon applet. The presence of this environment variable can also be used to determine that the plugin is actually running in Argos, rather than BitBar or [kargos](https://github.com/lipido/kargos)."
),
"| `ARGOS_MENU_OPEN` | %s |" %
_("`true` if the dropdown menu was open at the time the plugin was run, and `false` otherwise."
),
"",
'<span id="bitbar-plugins-with-argos-for-cinnamon-{{lhc_lang_id}}"></span>',
"",
"## %s" % _("BitBar plugins with Argos for Cinnamon"),
"",
utils.get_bootstrap_alert(
context="warning",
heading=_("WARNING!!! DO NOT RANDOMLY TEST SCRIPTS!!!"),
content=md("""
{0}
{1}
{2}
""".format(
"1. %s" %
_("Apply common sense. Read and understand what a script does and how demanding it could be."
), "2. %s" %
_("Test unknown scripts on an environment from which you can recover easily (for example, a virtual machine)."
), "3. %s" %
_("I found one specific case in which a script can freeze and ultimately crash Cinnamon. It's a script that downloads a GIF image from the internet, converts it to Base64 and then that encoded image is inserted into a menu item using the *image* attribute. I will not provide a link to that script, but if you follow the very first advice that I listed here, when you see that script, you will know."
)))),
"",
_("These screenshots show how some scripts from the BitBar plugin repository look when rendered by Argos compared to the \"canonical\" BitBar rendering (macOS screenshots taken from https://getbitbar.com)."
),
"",
"| %s | %s | %s |" %
(_("Plugin"), _("BitBar on macOS"), _("Argos on Cinnamon")),
"| --- | :---: | :---: |",
"| [**Ping**](https://getbitbar.com/plugins/Network/ping.10s.sh) | <img src=\"./assets/images/image-ping-bitbar.png\" class=\"img-fluid\" alt=\"Ping/BitBar\"> | <img src=\"./assets/images/image-ping-argos.png\" class=\"img-fluid\" alt=\"Ping/Argos\"> |",
"| [**Stock Ticker**](https://getbitbar.com/plugins/Finance/gfinance.5m.py) | <img src=\"./assets/images/stock-ticker-bitbar.png\" class=\"img-fluid\" alt=\"Stock Ticker/BitBar\"> | <img src=\"./assets/images/stock-ticker-argos.png\" class=\"img-fluid\" alt=\"Stock Ticker/BitBar\"> |",
"| [**World Clock**](https://getbitbar.com/plugins/Time/worldclock.1s.sh) | <img src=\"./assets/images/world-clock-bitbar.png\" class=\"img-fluid\" alt=\"World Clock/BitBar\"> | <img src=\"./assets/images/world-clock-argos.png\" class=\"img-fluid\" alt=\"World Clock/BitBar\"> |",
"| [**ANSI**](https://getbitbar.com/plugins/Tutorial/ansi.sh) | <img src=\"./assets/images/ansi-bitbar.png\" class=\"img-fluid\" alt=\"ANSI/BitBar\"> | <img src=\"./assets/images/ansi-argos.png\" class=\"img-fluid\" alt=\"ANSI/BitBar\"> |",
])))
def get_content_extra(self):
return md("{}".format("\n".join([
"## %s" % _("Extension options details"),
"",
utils.get_bootstrap_alert(
context="warning",
heading=_("Warning"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
content=_("Some tweaks have warnings, dependencies, limitations and or known issues that must be read and understood before a tweak is enabled. No worries, nothing *fatal* could ever happen.")
),
"",
"## %s" % _("Table of Content"),
"",
"- [%s](#appletsdesklets-tweaks-{{lhc_lang_id}})" % _("Applets/Desklets tweaks"),
"- [%s](#hot-corners-tweaks-{{lhc_lang_id}})" % _("Hot Corners tweaks"),
"- [%s](#desktop-area-tweaks-{{lhc_lang_id}})" % _("Desktop area tweaks"),
"- [%s](#popup-menus-tweaks-{{lhc_lang_id}})" % _("Popup menus tweaks"),
"- [%s](#tooltips-tweaks-{{lhc_lang_id}})" % _("Tooltips tweaks"),
"- [%s](#notifications-tweaks-{{lhc_lang_id}})" % _("Notifications tweaks"),
"- [%s](#window-focus-tweaks-{{lhc_lang_id}})" % _("Window focus tweaks"),
"- [%s](#window-shadows-tweaks-{{lhc_lang_id}})" % _("Window Shadows tweaks"),
"- [%s](#auto-move-windows-{{lhc_lang_id}})" % _("Auto move windows"),
"- [%s](#windows-decorations-removal-{{lhc_lang_id}})" % _(
"Windows decorations removal"),
"",
'<span id="appletsdesklets-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Applets/Desklets tweaks"),
"- **%s** %s" % (_("Ask for confirmation on applet/desklet removal:"), _(
"Instead of directly remove the applet/desklet from the context menus, it will ask for confirmation. This option doesn't affect the removal of applets/desklets from the Applets/Desklets manager in Cinnamon settings (there will be no confirmation).")),
"- **%s** & **%s** %s" % (_("Display \"Open applet/desklet folder\" on context menu for applets/desklets"), _("Display \"Edit applet/desklet main file\" on context menu for applets/desklet:"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("These options will add new menu items to the applets/desklets context menus. The place where this items will be located is chosen by the option **Where to place the menu item?**.")),
"",
'<span id="hot-corners-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Hot Corners tweaks"),
_("This tweak is only available for Cinnamon versions lower than 3.2. Cinnamon 3.2.x already has hot corners delay activation."),
"- **%s** %s" % (_("Top left hot corner activation delay:"), _("Crystal clear.")),
"- **%s** %s" % (_("Top right hot corner activation delay:"), _("Crystal clear.")),
"- **%s** %s" % (_("Bottom left hot corner activation delay:"), _("Crystal clear.")),
"- **%s** %s" % (_("Bottom right hot corner activation delay:"), _("Crystal clear.")),
"",
'<span id="desktop-area-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Desktop area tweaks"),
"- **%s** %s" % (_("Enable applications drop to the Desktop:"), _(
"This tweak enables the ability to drag and drop applications from the menu applet and from the panel launchers applet into the desktop.")),
"",
'<span id="popup-menus-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Popup menus tweaks"),
"##### %s" % _("Panel menus behavior"),
"**%s** %s" % (_("Note:"), _(
"This setting affects only the behavior of menus that belongs to applets placed on any panel.")),
"",
"- **%s** %s" % (_("Don't eat clicks:"), _("By default, when one opens an applet's menu on Cinnamon and then click on another applet to open its menu, the first click is used to close the first opened menu, and then another click has to be performed to open the menu of the second applet. With this option enabled, one can directly open the menu of any applet even if another applet has its menu open.")),
"",
'<span id="tooltips-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Tooltips tweaks"),
"- **%s** %s" % (_("Avoid mouse pointer overlapping tooltips:"), _("Tooltips on Cinnamon's UI are aligned to the top-left corner of the mouse pointer. This leads to having tooltips overlapped by the mouse pointer. This tweak aligns the tooltip to the bottom-right corner of the mouse pointer (approximately), reducing the possibility of the mouse pointer to overlap the tooltip. This tweak is only available for Cinnamon versions lower than 3.2. Cinnamon 3.2.x already has the position of the tooltips changed.")),
"- **%s** %s" % (_("Tooltips show delay:"), _("Crystal clear.")),
"",
'<span id="notifications-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Notifications tweaks"),
"- **%s** %s" % (_("Enable notifications open/close animation:"), _("Crystal clear.")),
"- **%s** %s" % (_("Notifications position:"), _(
"Notifications can be displayed at the top-right of screen (system default) or at the bottom-right of screen.")),
"- **%s**" % (_("Distance from panel:")),
" - **%s** %s" % (_("For notifications displayed at the top-right of screen:"), _(
"This is the distance between the bottom border of the top panel (if no top panel, from the top of the screen) to the top border of the notification popup.")),
" - **%s** %s" % (_("For notifications displayed at the bottom-right of screen:"), _(
"This is the distance between the top border of the bottom panel (if no bottom panel, from the bottom of the screen) to the bottom border of the notification popup.")),
"- **%s** %s" % (_("Notification popup right margin:"), _(
"By default, the right margin of the notification popup is defined by the currently used theme. This option, set to any value other than 0 (zero), allows to set a custom right margin, ignoring the defined by the theme.")),
"",
'<span id="window-focus-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Window focus tweaks"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Tweak based on the gnome-shell extension called [Steal My Focus](https://github.com/v-dimitrov/gnome-shell-extension-stealmyfocus) by [Valentin Dimitrov](https://github.com/v-dimitrov) and another gnome-shell extension called [Window Demands Attention Shortcut](https://github.com/awamper/window-demands-attention-shortcut) by [awamper](https://github.com/awamper)."),
"",
_("Some windows that demands attention will not gain focus regardless of the settings combination on Cinnamon settings. This option will allow you to correct that."),
"",
"- **%s**" % _("The activation of windows demanding attention...:"),
" - **%s** %s" % (_("...is handled by the system:"), _("Crystal clear.")),
" - **%s** %s" % (_("...is immediate:"),
_("will force windows demanding attention to be focused immediately.")),
" - **%s** %s" % (_("...is performed with a keyboard shortcut:"),
_("will focus windows demanding attention with a keyboard shortcut.")),
"- **%s** %s" % (_("Keyboard shortcut:"),
_("Set a keyboard shortcut for the option **...is performed with a keyboard shortcut**.")),
"",
'<span id="window-shadows-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Window Shadows tweaks"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Tweak based on a Cinnamon extension called [Custom Shadows](https://cinnamon-spices.linuxmint.com/extensions/view/43) created by [mikhail-ekzi](https://github.com/mikhail-ekzi). It allows to modify the shadows used by Cinnamon's window manager (Muffin)."),
"",
"**%s** %s" % (_("Note:"),
_("Client side decorated windows aren't affected by this tweak.")),
"",
"##### %s" % _("Shadow presets"),
"- **%s**" % _("Custom shadows"),
"- **%s**" % _("Default shadows"),
"- **%s**" % _("No shadows"),
"- **%s**" % _("Windows 10 shadows"),
"",
'<span id="auto-move-windows-{{lhc_lang_id}}"></span>',
"### %s" % _("Auto move windows"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Tweak based on the gnome-shell extension called [Auto Move Windows](https://extensions.gnome.org/extension/16/auto-move-windows/) by [Florian Muellner](https://github.com/fmuellner). It enables the ability to set rules to open determined applications on specific workspaces."),
"",
"**%s** %s" % (_("Note:"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If the application that you want to select doesn't show up on the application chooser dialog, read the section on this help file called **Applications not showing up on the applications chooser dialogs**.")),
"",
'<span id="windows-decorations-removal-{{lhc_lang_id}}"></span>',
"### %s" % _("Windows decorations removal"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Tweak based on the extension called [Cinnamon Maximus](https://cinnamon-spices.linuxmint.com/extensions/view/29) by [Fatih Mete](https://github.com/fatihmete) with some options from the gnome-shell extension called [Maximus NG](https://github.com/luispabon/maximus-gnome-shell) by [Luis Pabon](https://github.com/luispabon). This tweak allows to remove the windows decorations from maximized/half-maximized/tiled windows."),
"",
"**%s** %s" % (_("Note:"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("If the application that you want to select doesn't show up on the application chooser dialog, read the section on this help file called **Applications not showing up on the applications chooser dialogs**.")),
"",
"#### %s" % _("Dependencies"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("This tweak requires two commands available on the system (**xprop** and **xwininfo**) for it to work."),
"",
"- %s %s" % (_("Debian based distributions:"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("These commands are provided by the **x11-utils** package. Linux Mint already has this package installed.")),
"- %s %s" % (_("Archlinux based distributions:"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("These commands are provided by the **xorg-xprop** and **xorg-xwininfo** packages.")),
"- %s %s" % (_("Fedora based distributions:"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("These commands are provided by the **xorg-x11-utils** package.")),
"",
"#### %s" % _("Warnings"),
"- %s" % _("Client side decorated windows and WINE applications aren't affected by this tweak."),
"- %s" % _("Close all windows that belongs to an application that is going to be added to the applications list and before applying the settings of this tweak."),
"- %s" % _("As a general rule to avoid issues, before enabling and configuring this tweak, close all windows currently opened, enable and configure this tweak and then log out and log back in."),
"",
"#### %s" % _("Known issues"),
"- **%s** %s" % (_("Invisible windows:"), _("Sometimes, windows of applications that are configured to remove their decorations can become invisible. The application's icon can still be seen in the panel (taskbar) and when clicked to focus its respective window, the invisible window will block the clicks as if it were visible. To fix this, the window needs to be unmaximized (it will become visible again) and then closed. When reopened, the window should behave normally.")),
"- **%s** %s" % (_("Applications stuck undecorated:"), _(
"Some times, an application will get stuck undecorated even after unmaximizing it. Restarting the application will recover its ability to decorate and undecorate itself.")),
"",
"#### %s" % _("Alternative"),
_("There is an alternative way of hiding the title bar of absolutely all maximized windows without exceptions. By editing your Metacity theme (window decorations theme). It works infinitely better and without any of the issues this tweak on this extension has."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("Simply go to `/Path/To/Your/Theme/metacity-1` folder and edit with any text editor the file called **metacity-theme-3.xml**. If that file doesn't exists in your theme, then it should exist one called **metacity-theme-2.xml** or **metacity-theme-1.xml**. Choose the one with the bigger number."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("Find the **frame_geometry** element named **max** (or **maximized** or **normal_max** or **normal_maximized**). Its exact name may vary depending on the theme."),
"- %s" % _("Basically, one has to set to that element the attribute **has_title** to false, and then set all sizes of all its properties to 0 (zero). Some themes might require to add more properties and set them to 0 (zero) to completely get rid of the title bar."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("Next you will find examples on how to edit the Metacity themes found on the **Mint-X** and **Mint-Y** themes."),
"",
"##### %s" % _("For the Metacity theme found on the Mint-X theme"),
"",
"""```xml
<frame_geometry name="maximized" has_title="false" title_scale="medium" parent="normal" rounded_top_left="false" rounded_top_right="false">
<distance name="right_width" value="0" />
<distance name="left_titlebar_edge" value="0"/>
<distance name="right_titlebar_edge" value="0"/>
<distance name="title_vertical_pad" value="0"/>
<border name="title_border" left="0" right="0" top="0" bottom="0"/>
<border name="button_border" left="0" right="0" top="0" bottom="0"/>
<distance name="bottom_height" value="0" />
</frame_geometry>
```""",
"",
"##### %s" % _("For the Metacity theme found on Mint-Y theme"),
"",
"""```xml
<frame_geometry name="max" has_title="false" title_scale="medium" parent="normal" rounded_top_left="false" rounded_top_right="false">
<distance name="right_width" value="0" />
<distance name="left_titlebar_edge" value="0"/>
<distance name="right_titlebar_edge" value="0"/>
<distance name="title_vertical_pad" value="0"/>
<border name="title_border" left="0" right="0" top="0" bottom="0"/>
<border name="button_border" left="0" right="0" top="0" bottom="0"/>
<distance name="bottom_height" value="0" />
<distance name="button_width" value="0"/>
<distance name="button_height" value="0"/>
</frame_geometry>
```""",
"",
"## %s" % _("General extension issues"),
"### %s" % _("Applications not showing up on the applications chooser dialogs"),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("The application chooser dialog used by the settings window of this extension lists only those applications that have available .desktop files. Simply because these applications are the only ones that any of the tweaks that require an application ID (**Auto move windows** and **Windows decorations removal**) will recognize and handle."),
"",
_("Following the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/index.html), one can create a .desktop file for any application that doesn't appear in the applications list."),
"## %s" % _("Xlet's settings window"),
_("From this xlet settings window, all options can be imported, exported and/or reseted to their defaults."),
"",
"- %s" % _("To be able to perform any of these actions, the settings schema needs to be installed in the system. This is done automatically when the xlet is installed from the Cinnamon xlets manager. But if the xlet was installed manually, the settings schema also needs to be installed manually. This is achieved by simply going to the xlet folder and launch the following command:"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - %s %s" % (_("Command to install the settings schema:"),
"`./settings.py install-schema`"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - %s %s" % (_("Command to uninstall the settings schema:"),
"`./settings.py remove-schema`"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("To import/export settings, the **dconf** command needs to be available on the system."),
"",
])
))
def get_content_base(self, for_readme):
return "\n".join([
"",
utils.get_bootstrap_alert(
heading=_("Disclaimer"),
content=md(
_("I don't possess any certified knowledge about color vision deficiency nor the science of color. This extension is provided with the hope that it might be useful to persons with a color vision deficiency pathology. The algorithms used to calculate the simulation/compensation effects for the different pathologies are based on scientific researches, theses and blog posts that I came across."
) + " " + _("See %s.") %
("**[%s](#xlet-contributors)**" % _("References")))),
"",
"## %s" % _("Description"),
"",
_("Color Blindness Assistant is a Cinnamon extension that provides tools to assist users with color vision deficiency (CVD)."
),
"",
utils.get_bootstrap_alert(
heading=_("Basic references"),
content=md("\n".join([
"- **%s**: %s %s" %
(_("Acromatopia (rod monochromatism)"),
_("Total or almost total color blindness."),
"[Wiktionary](https://en.wiktionary.org/wiki/achromatopia)"
),
"- **%s**: %s %s" %
(_("Acromatopia (blue-cone monochromatism)"),
_("Total or almost total color blindness."),
"[Wiktionary](https://en.wiktionary.org/wiki/achromatopia)"
),
"- **%s**: %s %s" %
(_("Protanopia"),
_("First colors (reds) vision deficiency."),
"[Wiktionary](https://en.wiktionary.org/wiki/protanopia)"
),
"- **%s**: %s %s" %
(_("Deuteranopia"),
_("Second colors (greens) vision deficiency."),
"[Wiktionary](https://en.wiktionary.org/wiki/deuteranopia)"
),
"- **%s**: %s %s" %
(_("Tritanopia"),
_("Third colors (blues) vision deficiency."),
"[Wiktionary](https://en.wiktionary.org/wiki/tritanopia)"
),
]))),
"",
"## %s" % _("Features"),
"",
_("This extension provides mainly three features."),
"",
"- **%s**: %s" %
(_("Color blindness compensation"),
_("A user can apply an effect (specific to her/his pathology) that will (might) help her/him to better differentiate colors."
)),
"- **%s**: %s" %
(_("Color blindness simulation"),
_("A developer can apply an effect that will show her/him how a person with color vision deficiency will (might) see certain color combinations."
)),
"- **%s**: %s" %
(_("Color naming"),
_("This feature is useful for knowing the name of the color that's immediately under the cursor."
)),
])
def get_content_extra(self):
return md("{}".format("\n".join([
"## %s" % _("Extension options details"),
"",
utils.get_bootstrap_alert(
context="warning",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
content=
_("Some tweaks have warnings, dependencies, limitations and or known issues that must be read and understood before a tweak is enabled. No worries, nothing *fatal* could ever happen."
)),
"",
"## %s" % _("Table of Content"),
"",
"- [%s](#desktop-area-tweaks-{{lhc_lang_id}})" %
_("Desktop area tweaks"),
"- [%s](#popup-menus-tweaks-{{lhc_lang_id}})" %
_("Popup menus tweaks"),
"- [%s](#tooltips-tweaks-{{lhc_lang_id}})" % _("Tooltips tweaks"),
"- [%s](#window-focus-tweaks-{{lhc_lang_id}})" %
_("Window focus tweaks"),
"- [%s](#window-shadows-tweaks-{{lhc_lang_id}})" %
_("Window Shadows tweaks"),
"- [%s](#auto-move-windows-{{lhc_lang_id}})" %
_("Auto move windows"),
"- [%s](#windows-decorations-removal-{{lhc_lang_id}})" %
_("Windows decorations removal"),
"- [%s](#miscellaneous-tweaks-{{lhc_lang_id}})" %
_("Miscellaneous tweaks"),
"- [%s](#removed-tweaks-{{lhc_lang_id}})" % _("Removed tweaks"),
"***",
'<span id="desktop-area-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Desktop area tweaks"),
"- **%s:** %s" %
(_("Enable applications drop to the Desktop"),
_("This tweak enables the ability to drag and drop applications from the menu applet and from the panel launchers applet into the desktop."
)),
"***",
'<span id="popup-menus-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Popup menus tweaks"),
"##### %s" % _("Panel menus behavior"),
"",
utils.get_bootstrap_alert(content=_(
"This setting affects only the behavior of menus that belongs to applets placed on any panel."
)),
"",
"- **%s:** %s" %
(_("Don't eat clicks"),
_("By default, when one opens an applet's menu on Cinnamon and then click on another applet to open its menu, the first click is used to close the first opened menu, and then another click has to be performed to open the menu of the second applet. With this option enabled, one can directly open the menu of any applet even if another applet has its menu open."
)),
"***",
'<span id="tooltips-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Tooltips tweaks"),
"- **%s:** %s" %
(_("Intelligent positioning"),
_("It prevents the mouse cursor overlapping the tooltip and also allows to display a tooltip above the mouse cursor if there is no room on the screen to completely show the tooltip below it."
)),
"- **%s:** %s" %
(_("Never center tooltip text"),
_("Override the centered alignment of tooltips text set by certain Cinnamon themes (all the default ones). With this tweak enabled, the tooltip text will be aligned to the left or right depending on the text direction of the current system language."
)),
"- **%s:** %s" %
(_("Restrict tooltips width to half monitor width"),
_("Crystal clear.")),
"- **%s:** %s" % (_("Tooltips show delay"), _("Crystal clear.")),
"***",
'<span id="window-focus-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Window focus tweaks"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Tweak based on the gnome-shell extension called [Steal My Focus](https://github.com/v-dimitrov/gnome-shell-extension-stealmyfocus) by [Valentin Dimitrov](https://github.com/v-dimitrov) and another gnome-shell extension called [Window Demands Attention Shortcut](https://github.com/awamper/window-demands-attention-shortcut) by [awamper](https://github.com/awamper)."
),
"",
_("Some windows that demand attention will not gain focus regardless of the settings combination on Cinnamon settings. This option will allow you to correct that."
),
"",
"- **%s:**" %
_("The activation of windows demanding attention..."),
" - **%s:** %s" %
(_("...is handled by the system"), _("Crystal clear.")),
" - **%s:** %s" %
(_("...is immediate"),
_("will force windows demanding attention to be focused immediately."
)),
" - **%s:** %s" %
(_("...is performed with a keyboard shortcut"),
_("will focus windows demanding attention with a keyboard shortcut."
)),
"- **%s:** %s" %
(_("Keyboard shortcut"),
_("Set a keyboard shortcut for the option **...is performed with a keyboard shortcut**."
)),
"***",
'<span id="window-shadows-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Window Shadows tweaks"),
"",
utils.get_bootstrap_alert(content=_(
"Client side decorated windows aren't affected by this tweak.")
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Tweak based on a Cinnamon extension called [Custom Shadows](https://cinnamon-spices.linuxmint.com/extensions/view/43) created by [mikhail-ekzi](https://github.com/mikhail-ekzi). It allows to modify the shadows used by Cinnamon's window manager (Muffin)."
),
"",
"##### %s" % _("Shadow presets"),
"- **%s**" % _("Custom shadows"),
"- **%s**" % _("Default shadows"),
"- **%s**" % _("No shadows"),
"- **%s**" % _("Windows 10 shadows"),
"***",
'<span id="auto-move-windows-{{lhc_lang_id}}"></span>',
"### %s" % _("Auto move windows"),
"",
"%s:" %
_("This tweak is composed of two features that work in conjunction"
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"1. **%s:** %s" %
(_("Auto move application to specific workspaces"),
_("Tweak based on the gnome-shell extension called [Auto Move Windows](https://extensions.gnome.org/extension/16/auto-move-windows/) by [Florian Muellner](https://github.com/fmuellner). It enables the ability to set rules to open determined applications on specific workspaces."
)),
"2. **%s:** %s" %
(_("Move full screen applications to their own workspace"),
_("Tweak based on two gnome-shell extensions; one called [Fullscreen On New Workspace](https://extensions.gnome.org/extension/1502/fullscreen-on-new-workspace) by [Satyajit Ranjeev](https://github.com/satran) and another one called [Maximize To Workspace](https://extensions.gnome.org/extension/1181/maximize-to-workspace) by [rliang](https://github.com/rliang)."
)),
"",
"#### %s" % _("Usage"),
"",
"- %s" %
_("When an application is opened, it will be moved to the workspace that it is configured to be opened on."
),
"- %s" %
_("When an application enters full screen, it will be moved to the first empty workspace (a workspace that has no windows on it). Except when the application is configured to be opened into an specific workspace."
),
"- %s" %
_("If an application is not configured to be opened into an specific workspace, and there are no empty workspaces, when the application enters full screen, a new workspace will be created."
),
"- %s" %
_("When an application that entered into full screen exits that state, it will be moved back into the workspace from which the application was set to full screen."
),
"- %s" %
_("When an application that entered into full screen is closed, the first workspace will be activated."
),
"- %s" %
_("If an application needed to create a new workspace, that workspace will be removed when the application exits full screen or is closed, but only if there are no other windows in it."
),
"",
utils.get_bootstrap_alert(content=_("See %s.") % (
'<a href="#applications-not-showing-up-{{lhc_lang_id}}">%s</a>'
%
_("Applications not showing up on the applications chooser dialogs"
))),
"",
"***",
'<span id="windows-decorations-removal-{{lhc_lang_id}}"></span>',
"### %s" % _("Windows decorations removal"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Tweak based on the extension called [Cinnamon Maximus](https://cinnamon-spices.linuxmint.com/extensions/view/29) by [Fatih Mete](https://github.com/fatihmete) with some options from the gnome-shell extension called [Maximus NG](https://github.com/luispabon/maximus-gnome-shell) by [Luis Pabon](https://github.com/luispabon). This tweak allows to remove the windows decorations from maximized/half-maximized/tiled windows."
),
"",
utils.get_bootstrap_alert(content=_("See %s.") % (
'<a href="#applications-not-showing-up-{{lhc_lang_id}}">%s</a>'
%
_("Applications not showing up on the applications chooser dialogs"
))),
"",
"#### %s" % _("Dependencies"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("This tweak requires two commands available on the system (**xprop** and **xwininfo**) for it to work."
),
"",
"- %s: %s" % (
_("Debian based distributions"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("These commands are provided by the **x11-utils** package. Linux Mint already has this package installed."
)),
"- %s: %s" % (
_("Archlinux based distributions"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("These commands are provided by the **xorg-xprop** and **xorg-xwininfo** packages."
)),
"- %s: %s" % (
_("Fedora based distributions"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("These commands are provided by the **xorg-x11-utils** package."
)),
"",
"#### %s" % _("Warnings"),
"- %s" %
_("Client side decorated windows and WINE applications aren't affected by this tweak."
),
"- %s" %
_("Close all windows that belongs to an application that is going to be added to the applications list and before applying the settings of this tweak."
),
"- %s" %
_("As a general rule to avoid issues, before enabling and configuring this tweak, close all windows currently opened, enable and configure this tweak and then log out and log back in."
),
"",
"#### %s" % _("Known issues"),
"- **%s:** %s" %
(_("Invisible windows"),
_("Sometimes, windows of applications that are configured to remove their decorations can become invisible. The application's icon can still be seen in the panel (taskbar) and when clicked to focus its respective window, the invisible window will block the clicks as if it were visible. To fix this, the window needs to be unmaximized (it will become visible again) and then closed. When reopened, the window should behave normally."
)),
"- **%s:** %s" %
(_("Applications stuck undecorated"),
_("Some times, an application will get stuck undecorated even after unmaximizing it. Restarting the application will recover its ability to decorate and undecorate itself."
)),
"",
"#### %s" % _("Alternative"),
_("There is an alternative way of hiding the title bar of absolutely all maximized windows without exceptions. By editing your Metacity theme (window decorations theme). It works infinitely better and without any of the issues this tweak on this extension has."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("Simply go to `/Path/To/Your/Theme/metacity-1` folder and edit with any text editor the file called **metacity-theme-3.xml**. If that file doesn't exists in your theme, then it should exist one called **metacity-theme-2.xml** or **metacity-theme-1.xml**. Choose the one with the bigger number."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("Find the **frame_geometry** element named **max** (or **maximized** or **normal_max** or **normal_maximized**). Its exact name may vary depending on the theme."
),
"- %s" %
_("Basically, one has to set to that element the attribute **has_title** to false, and then set all sizes of all its properties to 0 (zero). Some themes might require to add more properties and set them to 0 (zero) to completely get rid of the title bar."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("Next you will find examples on how to edit the Metacity themes found on the **Mint-X** and **Mint-Y** themes."
),
"",
"##### %s" % _("For the Metacity theme found on the Mint-X theme"),
"",
"""```xml
<frame_geometry name="maximized" has_title="false" title_scale="medium" parent="normal" rounded_top_left="false" rounded_top_right="false">
<distance name="right_width" value="0" />
<distance name="left_titlebar_edge" value="0"/>
<distance name="right_titlebar_edge" value="0"/>
<distance name="title_vertical_pad" value="0"/>
<border name="title_border" left="0" right="0" top="0" bottom="0"/>
<border name="button_border" left="0" right="0" top="0" bottom="0"/>
<distance name="bottom_height" value="0" />
</frame_geometry>
```""",
"",
"##### %s" % _("For the Metacity theme found on Mint-Y theme"),
"",
"""```xml
<frame_geometry name="max" has_title="false" title_scale="medium" parent="normal" rounded_top_left="false" rounded_top_right="false">
<distance name="right_width" value="0" />
<distance name="left_titlebar_edge" value="0"/>
<distance name="right_titlebar_edge" value="0"/>
<distance name="title_vertical_pad" value="0"/>
<border name="title_border" left="0" right="0" top="0" bottom="0"/>
<border name="button_border" left="0" right="0" top="0" bottom="0"/>
<distance name="bottom_height" value="0" />
<distance name="button_width" value="0"/>
<distance name="button_height" value="0"/>
</frame_geometry>
```""",
"***",
"## %s" % _("General extension issues"),
'<span id="applications-not-showing-up-{{lhc_lang_id}}"></span>',
"### %s" %
_("Applications not showing up on the applications chooser dialogs"
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("The application chooser dialog used by the settings window of this extension lists only those applications that have available .desktop files. Simply because these applications are the only ones that any of the tweaks that require an application ID (**Auto move windows** and **Windows decorations removal**) will recognize and handle."
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Following the [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/index.html), one can create a .desktop file for any application that doesn't appear in the applications list."
),
"***",
'<span id="miscellaneous-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Miscellaneous tweaks"),
"",
"- **%s:** %s" %
(_("Restore logging to glass.log file"),
_("Originally, this file was located at ~/.cinnamon/glass.log. I changed its location to ~/.local/share/cinnamon/logs/glass.log."
)),
"***",
'<span id="removed-tweaks-{{lhc_lang_id}}"></span>',
"### %s" % _("Removed tweaks"),
"",
"- %s: %s" %
(_("Notifications tweaks"),
_("Removed due to Cinnamon now having the option to display notifications at the bottom of the screen and also having a close button."
)),
"- %s: %s" %
(_("Hot Corners tweaks"),
_("The ability to add a delay for the hot corners activation was added to Cinnamon around verison 3.2.x."
)),
"- %s: %s" %
(_("Xlets tweaks"),
_("A confirmation dialog when deleting applets/desklets was added to Cinnamon around verison 4.2.x."
))
])))
def get_content_extra(self):
return md("{}".format("\n".join([
utils.get_bootstrap_alert(
context="warning",
content=md(
"\n".join([
"- %s" % _("This applet requires valid credentials from any of the weather provider services for it to work."),
"- %s" % _("The credentials cannot be used until they have been activated by the weather providers.")
])
)
),
"",
"## %s" % _("Getting API credentials"),
"",
_("Follow the instructions made available by the providers."),
"",
"### %s" % _("Weather providers"),
"",
"| %s | %s | %s |" % (_("Provider"), _(
"API credentials instructions"), _("Location finder")),
"| -- | -- | -- |",
"| %s | [%s](%s) | [%s](%s) |" % (
_("OpenWeatherMap"),
_("Get credentials"), "https://openweathermap.org/appid",
_("Find location"), "https://openweathermap.org/find",
),
"| %s | [%s](%s) | [%s](%s) **(*)** |" % (
_("WeatherBit"),
_("Get credentials"), "https://www.weatherbit.io/pricing",
_("Find location"), "https://openweathermap.org/find",
),
"",
"**(*)** %s" % _("WeatherBit uses the same city IDs returned by OpenWeatherMap's location finder in addition to coordinates."),
"",
"## %s" % _("Menu layout"),
"",
utils.get_image_container(
src="assets/images/menu-layout.png",
alt=_("Menu layout")
),
"",
"1. %s" % _("Current weather condition for the currently selected location."),
"2. %s" % _("Forecasts for the currently selected location."),
"3. %s" % _(
"The time in which the currently displayed data was published by the weather provider. Clicking it will attempt to retrieve updated weather data."),
"4. %s" % _("Button to open the locations selector menu."),
"5. %s" % _(
"Weather provider attribution. When clicked, it opens the weather provider website."),
"",
"## %s" % _("Locations manager"),
"",
utils.get_bootstrap_alert(
heading=_("Highlights"),
content=md(
"\n".join([
"- %s" % _("The locations manager can be accessed from this applet settings window."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("Locations with the exact same *Location ID* and *Provider* are considered duplicated and will be automatically removed when applying changes."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("The *Apply changes* button must be pressed for the applet to reflect the changes made in the locations manager."),
])
)
),
"",
utils.get_image_container(
src="assets/images/locations-manager.png",
alt=_("Locations manager")
),
"",
"- **%s**: %s" % (
_("Location name"),
_("This is an informative field and it isn't used to retrieve weather data. It is used to identify the displayed data in the menu and to generate the items inside the locations selector menu.")
),
"- **%s**: %s" % (
_("Location ID"),
_("A city/region ID used by the weather service providers to identify a location.")
),
" - %s" % _("Open Weather Map uses city IDs (the number at the end of a location URL) and coordinates."),
"- **%s**: %s" % (
_("Language"),
_("Weather conditions localization. Languages are only used by OpenWeatherMap provider and it only affect weather conditions text. Any other text of the applet UI is localized by the applet itself (if available).")
),
"- **%s**: %s" % (
_("Forecast days"),
_("The amount of forecasts to display in the menu.")
),
"- **%s**: %s" % (
_("Forecast rows/columns"),
_("The amount of rows/cols to display the forecast days in.")
),
"- **%s**: %s" % (
_("Provider"),
_("Weather data provider. All weather providers require proper credentials to function.")
),
"",
"## %s" % _("Menu theme"),
"",
"- %s" % _("This applet supports custom themes to style its menu."),
"- %s" % _("The default theme (found in APPLET_FOLDER/themes/default.css) only sets a generic styling to accommodate the elements in the menu."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("To use a custom theme, just set the **Menu theme** option to **Custom** and set the **Path to custom style sheet** option to point to a style sheet file."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("To create a custom theme, just make a copy of the default theme file anywhere on the file system, **except** inside the applet folder. The default theme file has the complete list of CSS classes used by this applet."),
"- %s" % _("For the custom theme changes to be reflected on the menu while the theme file is modified, either Cinnamon can be restarted or the Cinnamon theme can be reloaded."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _(
"Cinnamon provides a command to reload its theme. Just open the **Run command** dialog ([[Alt]] + [[F2]]), type **rt** and press [[Enter]]."),
"",
"## %s" % _("Icon theme"),
"",
"- %s" % _("This applet supports custom icon themes."),
"- %s" % _("This applet comes with the possibility to choose 3 icon themes and they are named as follows."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - **%s**: %s" % (_("System"),
_("The applet will use the icons provided by the currently selected icon theme for the system.")),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - **%s**: %s" % (_("Built-in"),
_("The icons used are the ones found in APPLET_FOLDER/themes/icons.")),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
" - **%s**: %s" % (_("Custom"), _(
"The icons used are the ones found in the path defined in the **Path to custom icon theme** option.")),
"- %s" % _("An icon theme is just a folder that contains specifically named icon files."),
"- %s" % _("The built-in icon theme is a monochrome theme and is found in APPLET_FOLDER/themes/icons."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("The built-in icon theme can be used as full color or symbolic icons (applet settings **Menu icon type** and **Applet icon type**). The difference is that, if used as a full color theme, the icons will be black no matter if the Cinnamon theme selected has light or dark backgrounds for menus. On the other hand, if it is used as symbolic icons, the color of the icons will be set by the selected Cinnamon theme. Additionally, symbolic icons can be colorized through the custom CSS theme (applet setting **Menu theme**) by styling the `weather-forecast-icon` and `weather-current-icon` classes."),
"- %s" % _("To create a custom icon theme, the built-in icon theme can be used as a base."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("The built-in icon theme is composed of 36 *real images*, the rest of icons are symbolic links to these *real images*."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("Inside the built-in icon theme is a script called **z_symlinkify.bash** that can be used to create an icon theme from scratch. This script also contains the list of *real images* that are used to create the symbolic links."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" % _("A custom icon theme can contain only full colored icons, only symbolic icons or both. The **Menu icon type** and **Applet icon type** applet settings should be set accordingly to the icon type used by the custom theme."),
"- %s" % _("A custom icon theme can contain SVG or PNG images; although SVG images are preferable due to their ability to scale into any icon size set in this applet settings without loosing quality. Other image types might be used, but I didn't test them."),
"- %s" % _("A custom icon theme should contain 240 icons to support both full color and symbolic icons. Or half of that (120) to support one or the other."),
""
])
))
def get_content_extra(self):
return md("{}".format("\n".join([
"### %s" % _("How to install latest version of translate-shell"),
"#### %s" % _("Option 1. Direct Download"),
_("This method will only install the trans script into the specified locations."
),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("For the current user only. **~/.local/bin** needs to be in your PATH."
),
"",
"""```shell
$ wget -O ~/.local/bin/trans git.io/trans && chmod ugo+rx ~/.local/bin/trans
```""",
"",
_("For all users without overwriting the installed version."),
"",
"""```shell
$ sudo wget -O /usr/local/bin/trans git.io/trans && sudo chmod ugo+rx /usr/local/bin/trans
```""",
"",
"#### %s" %
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Option 2. From Git - [More details](https://github.com/soimort/translate-shell/blob/develop/README.md#option-3-from-git-recommended-for-seasoned-hackers)"
),
_("This method will not just install the trans script but also its man pages. Refer to the link above for more installation details."
),
"",
"""```shell
$ git clone https://github.com/soimort/translate-shell
$ cd translate-shell
$ make
$ sudo make install
```""",
"",
"## %s" % _("Extension usage"),
_("Once installed and enabled, the following shortcuts will be available."
),
"### %s" % _("Global keyboard shortcuts"),
"",
"These shortcuts are empty by default and need to be configured from the extension settings window."
"",
"1. %s" % _("Open translator dialog."),
"2. %s" %
_("Open translator dialog and translate text from clipboard."),
"3. %s" %
_("Open translator dialog and translate from primary selection."),
"",
"### %s" %
_("Keyboard shortcuts available on the translation dialog"),
"",
"- **[[F1]]**: %s" % _("Show help dialog."),
"- **[[%s]] + [[%s]]**: %s." %
(_("Ctrl"), _("Enter"), _("Translate text")),
"- **[[%s]] + [[%s]]**: %s" %
(_("Shift"), _("Enter"),
_("Force text translation. Ignores translation history.")),
"- **[[%s]] + [[%s]] + [[C]]**: %s" %
(_("Ctrl"), _("Shift"), _("Copy translated text to clipboard.")),
"- **[[%s]] + [[S]]**: %s." % (_("Ctrl"), _("Swap languages")),
"- **[[%s]] + [[R]]**: %s" %
(_("Ctrl"), _("Reset languages to default.")),
"- **[[%s]] + [[P]]**: %s." %
(_("Ctrl"), _("Provider selector menu")),
"- **[[%s]] + [[M]]**: %s." % (_("Ctrl"), _("Main menu")),
"- **[[%s]]**: %s" % (_("Escape"), _("Close dialog.")),
"",
"## %s" % _("Translation history"),
"",
utils.get_bootstrap_alert(
context="warning",
content=
_("NEVER edit the translation history file manually!!! Always use the translation history window to import/export/clear the history."
)),
"",
utils.get_image_container(
src="assets/images/translation-history.png",
alt=_("Translation history window.")),
"",
"",
"- %s" %
_("The main purpose of the translation history is to avoid or at the very least minimize possible abuses while using a translation provider service."
),
" - %s" %
_("If the Google Translate service is \"abused\", Google may block temporarily your IP. Or what is worse, they could change the translation mechanism making this extension useless and forcing me to update its code."
),
" - %s" %
_("If the Yandex Translate service is \"abused\", you are \"wasting\" your API keys quota and they will be blocked (temporarily or permanently)."
),
"- %s" %
_("The translation history can be accessed from the main menu found in the translation dialog."
),
"",
"## %s" % _("GUI theme"),
"",
utils.get_image_container(
src="assets/images/translation-dialog.png",
alt=_("Translation dialog.")),
"",
"- %s" %
_("This extension supports custom themes to style its GUI (the translation dialog)."
),
"- %s" %
_("The default theme (found in EXTENSION_FOLDER/themes/default.css) only sets a generic styling to accommodate the elements in the GUI."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("To use a custom theme, just set the **Dialog theme** option to **Custom** and set the **Custom theme path** option to point to a style sheet file."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("To create a custom theme, just make a copy of the default theme file anywhere on the file system, **except** inside the extension folder. The default theme file has the complete list of CSS classes and IDs used by this extension."
),
"- %s" %
_("For the custom theme changes to be reflected while the theme file is modified, either Cinnamon can be restarted or the Cinnamon theme can be reloaded."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("Cinnamon provides a command to reload its theme. Just open the **Run command** dialog ([[Alt]] + [[F2]]), type **rt** and press [[Enter]]."
),
"",
"## %s" % _("How to get Yandex translator API keys"),
"",
"- %s" %
_("Visit one of the following links and register a Yandex account (or use one of the available social services)."
),
# TO TRANSLATORS: URL pointing to website in English
" - %s: %s" %
(_("English"), "https://tech.yandex.com/keys/get/?service=trnsl"),
# TO TRANSLATORS: URL pointing to website in Russian
" - %s: %s" %
(_("Russian"), "https://tech.yandex.ru/keys/get/?service=trnsl"),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("Once you successfully finish creating your Yandex account, you can visit the link provided several times to create several API keys. **DO NOT ABUSE!!!**"
),
"- %s" %
_("Once you have several API keys, you can add them to Multi Translator's settings window (one API key per line)."
),
"",
"### %s" % _("Important notes about Yandex API keys"),
"",
"- %s" %
_("The API keys will be stored into a preference. Keep your API keys backed up in case you reset Multi Translator's preferences."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("**NEVER make your API keys public!!!** The whole purpose of going to the trouble of getting your own API keys is that the only one \"consuming their limits\" is you and nobody else."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
"- %s" %
_("With each Yandex translator API key you can translate **UP TO** 1.000.000 (1 million) characters per day **BUT NOT MORE** than 10.000.000 (10 millions) per month."
),
""
])))
def get_content_extra(self):
return md("{}".format("\n".join([
"",
"## %s" % _("Programs support"),
"",
_("In addition to Cinnamon's built-in screenshot/screencast tools, this applet also supports third-party programs to take captures. By default, this applet comes with support for several known programs (Shutter, Gnome Screenshot, XWD, ImageMagic, FFmepg, RecordMyDesktop, Byzanz and Kazam)."),
"",
utils.get_bootstrap_alert(
heading=_("Highlights"),
content=md("""
- {0}
- {1}
- {2}
- {3}
- {4}
- {5}
- {6}""".format(
# TO TRANSLATORS: Do not translate the words "camera" and "recorder".
# MARKDOWN string. Respect formatting.
_("Programs are stored inside an applet preference. They are grouped by devices. A device called **camera** that contains programs that take screenshots. And a device called **recorder** that contains programs that capture screencasts."),
_("Programs can be added/removed/modified as much as needed/wanted from this applet context menu by simply exporting the existent programs, modifying the generated JSON file and importing the modified file again."),
_("Commands are exactly that, commands. They are composed of command line arguments , placeholders, and/or flags."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_(
"Placeholders are strings specifically formatted with double curly braces (`{{PLACEHOLDER_NAME}}`) and can be placed in any part of a string. These strings are replaced with dynamically generated data (an applet preference, screen coordinates, etc.) when a command is executed."),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Flags are another type of specifically formatted strings surrounded by hashes (`#FLAG_NAME#`) and they always must be placed at the beginning of a string. Flags indicate that an action must be taken before a command is executed."),
_("The exported JSON file exemplifies almost all the options, flags and placeholders documented below."),
_("The command that will be executed can be previewed before actually executing it by simply right clicking a menu item."),
))
),
"",
utils.get_bootstrap_alert(
context="warning",
heading=_("Warnings"),
content=md("""
- {0}
- {1}
- {2}
- {3}""".format(
_("All option names, flags, and placeholders are case sensitive. Command option names are lower cased and use dashes as word separators. Placeholders and flags are upper cased and use low dashes as word separators."),
_("An imported JSON file will overwrite an existent preference."),
_("Importing a malformed/invalid JSON file will cancel the import operation without modifying an existent preference."),
_("There isn't a mechanism to check if a command is available or not on the system the applet is installed. So, use common sense."),
))
),
"",
"### %s" % _("Basic example"),
"",
"""```
{{
"camera": {{
"{pro_name}": {{
"title": "{pro_title}",
"cursor": {{
"on": "{cursor_on}",
"off": "{cursor_off}"
}},
"timer": true,
"append-1": "{append_1}",
"menuitems": {{
"{item_label} 1": "{item_command}",
"---": "{separator}",
"{item_label} 2": "{item_command}",
}}
}}
}},
"recorder": {{
"{pro_name}": {{
"title": "{pro_title}",
"fps": true,
"cursor": {{
"on": "{cursor_on}",
"off": "{cursor_off}"
}},
"sound": {{
"on": "{sound_on}",
"off": "{sound_off}"
}},
"menuitems": {{
"#{item_label} 1": "{item_command} ({item_label_hash})",
"---": "{separator}",
"{item_label} 2": "{item_command}",
}},
"stop-command": "{stop_command}"
}}
}}
}}
```""".format(
pro_name=_("Program/Command name"),
pro_title=_("Name of the program shown on the program selector menu"),
sound_on=_("Argument to include sound in capture"),
sound_off=_("Argument to not include sound in capture"),
stop_command=_("Command to stop recording"),
separator=_("This is a separator"),
cursor_on=_("Argument to include cursor in capture"),
cursor_off=_("Argument to not include cursor in capture"),
# TO TRANSLATORS: Do not translate the word "APPEND_1".
append_1=_("The content here will be used to replace the {{APPEND_1}} placeholder"),
item_label=_("Menu item label"),
item_label_hash=_("See %s." % ("**%s**" % _("Menu item label flags"))),
item_command=_("Command to execute when clicking this menu item"),
),
"",
"### %s" % _("Program options"),
"",
"| %s | %s | %s |" % (_("Option"), _("Usage"), _("Description")),
"| --- | --- | --- |",
"| `title` | %s | %s |" % (_("Mandatory"), _(
"This option will be used as the program name in the program selector sub-menu.")),
"| `menuitems` | %s | %s |" % (_("Mandatory"), _(
"This option contains all the data that will be used to create the menu items for a program.")),
"| `stop-command` | %s - %s | %s |" % (_("Mandatory"), _(
"Recorder only"), _("The command to stop recording a screencast.")),
"| `timer` | %s - %s | %s |" % (_("Optional"), _("Camera only"),
# TO TRANSLATORS: Do not translate the words "true" and "DELAY".
# MARKDOWN string. Respect formatting.
_("This option is used in combination with the `{{DELAY}}` placeholder. If set to **true**, sets the visibility of the **Capture delay** option inside this applet menu.")),
"| `fps` | %s - %s | %s |" % (_("Optional"), _("Recorder only"),
# TO TRANSLATORS: Do not translate the word "true".
# MARKDOWN string. Respect formatting.
_("This option, if set to **true**, sets the visibility of the **Frames per second** option inside this applet menu.")),
"| `cursor` | %s | %s |" % (_("Optional"),
# TO TRANSLATORS: Do not translate the words "on", "off", and "CURSOR".
# MARKDOWN string. Respect formatting.
_("This option is used in combination with the `{{CURSOR}}` placeholder. It must contain two keys named **on** and **off** which respectively must contain a comand line argument for enabling/disabling the display of the mouse cursor on the captured file.")),
"| `sound` | %s - %s | %s |" % (_("Optional"), _("Recorder only"),
# TO TRANSLATORS: Do not translate the words "on", "off", and "SOUND".
# MARKDOWN string. Respect formatting.
_("This option is used in combination with the `{{SOUND}}` placeholder. It must contain two keys named **on** and **off** which respectively must contain a comand line argument for enabling/disabling the inclusion of sound on the captured file.")),
"| `append-1` ... `append-10` | %s | %s |" % (_("Optional"), _(
"These options are used in combination with the `{{APPEND_1}}` to `{{APPEND_10}}` placeholders. This is done to avoid repeating the same arguments on all menu items commands.")),
"",
"### %s" % _("Flags"),
"",
"#### %s" % _("Menu item label flags"),
"",
"| %s | %s |" % (_("Flag"), _("Description")),
"| --- | --- |",
"| `#` | %s |" % _(
"The hash (#) character in front of a menu item label is a flag that inhibits the menu item from changing the state of the applet (the change of the applet icon from normal to recording)."),
"",
"#### %s" % _("Menu item command flags"),
"",
"| %s | %s |" % (_("Flag"), _("Description")),
"| --- | --- |",
"| `#INTERACTIVE_AREA_HELPER#` | %s |" % _(
"This flag will allow the use of this applet area selector helper. See %s" % ("**[%s](#menu-item-command-interactive-placeholders-{{lhc_lang_id}})**" % _("Menu item command interactive placeholders"))),
"| `#INTERACTIVE_WINDOW_HELPER#` | %s |" % _(
"This flag will allow the use of this applet window selector helper. See %s" % ("**[%s](#menu-item-command-interactive-placeholders-{{lhc_lang_id}})**" % _("Menu item command interactive placeholders"))),
"",
"### %s" % _("Menu item command placeholders"),
"",
"| %s | %s | %s |" % (_("Placeholder"), _("Usage"), _("Description")),
"| --- | --- | --- |",
# TO TRANSLATORS: Do not translate the word "append".
# MARKDOWN string. Respect formatting.
"| `{{APPEND_1}}` ... `{{APPEND_10}}` | | %s |" % _(
"Placeholder for the program options `append-1` to `append-10`."),
"| `{{CURSOR}}` | | %s |" % _(
"The command line argument used to decide if the capture will display the cursor or not."),
"| `{{DELAY}}` | %s | %s |" % (_("Camera only"), _(
"Delay in seconds before taking a screenshot.")),
"| `{{DIRECTORY}}` | | %s |" % _("The directory used as storage for the captures."),
"| `{{EXT}}` | | %s |" % _(
"The file extension that the generated capture will have. It has to be used in pairs (Example: `{{EXT}}png{{EXT}}`)."),
"| `{{FILENAME}}` | | %s |" % _(
"The file name (no extension included) that the generated capture will have."),
"| `{{FPS}}` | %s | %s |" % (_("Recorder only"), _(
"Frames per second (frame rate).")),
"| `{{RECORDER_DIR}}` | | %s |" % _(
"The directory used to store the screencast captures."),
"| `{{SCREEN_DIMENSIONS}}` | | %s |" %
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("The screen dimensions with format `widthxheight`. Example: `1440x900`"),
"| `{{SCREEN_HEIGHT}}` | | %s |" % _("The screen height."),
"| `{{SCREEN_WIDTH}}` | | %s |" % _("The screen width."),
"| `{{SCREENSHOT_DIR}}` | | %s |" % _(
"The directory used to store the screenshot captures."),
"| `{{SOUND}}` | %s | %s |" % (_("Recorder only"), _(
"The command line argument used to decide if the capture include sound or not.")),
"",
'<span id="menu-item-command-interactive-placeholders-{{lhc_lang_id}}"></span>',
"",
"### %s" % _("Menu item command interactive placeholders"),
"",
"| %s | %s |" % (_("Placeholder"), _("Description")),
"| --- | --- |",
"| `{{I_X}}` | %s |" % _("`x` screen coordinates."),
"| `{{I_Y}}` | %s |" % _("`y` screen coordinates."),
"| `{{I_X_Y}}` | %s |" % _("`x` and `y` screen coordinates separated by a comma."),
"| `{{I_WIDTH}}` | %s |" % _(
"It could be either the width of a selected area or the width of a selected window."),
"| `{{I_HEIGHT}}` | %s |" % _(
"It could be either the height of a selected area or the height of a selected window."),
"| `{{I_NICE_WIDTH}}` | %s |" % _(
"Same as `I_WIDTH`, but with `1` added to its value."),
"| `{{I_NICE_HEIGHT}}` | %s |" % _(
"Same as `I_HEIGHT`, but with `1` added to its value."),
"| `{{I_X_WINDOW_ID}}` | %s |" % _("The selected window ID."),
"| `{{I_X_WINDOW_FRAME}}` | %s |" % _(
"The 'x-window' property of the selected window."),
"| `{{I_WM_CLASS}}` | %s |" % _("The selected window class name."),
"| `{{I_WINDOW_TITLE}}` | %s |" % _("The selected window class title."),
"",
"## %s" % _("Cinnamon recorder profiles"),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("The built-in Cinnamon recorder uses the GStreamer general-purpose multimedia framework ([GStreamer documentation](https://gstreamer.freedesktop.org/documentation/index.html)). It generates a video file with the `webm` extension using the `vp8enc` encoder and the `webmmux` muxer. This applet exposes the use of the Cinnamon recorder through profiles."),
"",
utils.get_bootstrap_alert(
heading=_("Highlights"),
content=md("""
- {0}
- {1}
""".format(
_("Profiles are stored inside an applet preference."),
_("Profiles can be added/removed/modified as much as needed/wanted from this applet context menu by simply exporting the existent profiles, modifying the generated JSON file and importing the modified file again."),
))
),
"",
utils.get_bootstrap_alert(
context="warning",
heading=_("Warnings"),
content=md("""
- {0}
- {1}
- {2}""".format(
_("An imported JSON file will overwrite an existent preference."),
_("Importing a malformed/invalid JSON file will cancel the import operation without modifying an existent preference."),
_("Like everything coming from Gnome, GStreamer is an always-evolving-never-finished-barely-functional piece of software. With that in mind, when using the wrong combination of encoder/muxer, Cinnamon will miserably crash. So, experiment at your own risk."),
))
),
"",
"### %s" % _("Basic example"),
"",
_("Below are the two Cinnamon recorder profiles shipped with this applet. The profile named default cannot be modified/deleted."),
"",
"""```
{
"default": {
"title": "Default",
"description": "Encoder: On2 VP8\\nMuxer: WebM\\nFile extension: webm",
"file-extension": "webm",
"pipeline": "vp8enc min_quantizer=13 max_quantizer=13 cpu-used=5 deadline=1000000 threads=%T ! queue ! webmmux"
},
"x264enc": {
"title": "H264",
"description": "Encoder: H264\\nMuxer: Matroska\\nFile extension: mkv",
"file-extension": "mkv",
"pipeline": "x264enc ! queue ! matroskamux"
}
}
```""",
"",
"### %s" % _("Profile options"),
"",
_("All profile options are mandatory."),
"",
"| %s | %s |" % (_("Option"), _("Description")),
"| --- | --- |",
"| `title` | %s |" % _("Name of the profile shown on the profile selector menu."),
"| `description` | %s |" % _(
"Basic description of the profile that will be displayed as a tooltip."),
"| `file-extension` | %s |" % _("The file extension of the generated file."),
"| `pipeline` | %s |" % _("GStreamer pipeline."),
"",
"## %s" % _("Keyboard shortcuts"),
"",
_("Keyboard shortcuts are tied to specific capture types."),
"",
"## %s" % _("Known issues"),
"",
"<h3 class='text-danger'>%s</h3>" % _(
"Cinnamon 3.0.x and its built-in screenshot mechanism"),
"",
"<p class='text-danger'><strong>%s</strong></p>" % _(
"The Cinnamon's 3.0.x built-in screenshot mechanism is broken!"),
"",
"<p class='text-danger'><strong>%s</strong></p>" % _(
"Do not use it or Cinnamon will crash!"),
"",
"<p class='text-danger'><strong>%s</strong></p>" % _(
"It can only be fixed by building from source the cinnamon package for version 3.0.x with the following patch (%s). Or by simply updating to any other newer version of Cinnamon (3.2.x, 3.4.x, etc.)." % "<a href='https://github.com/linuxmint/Cinnamon/pull/5777'>PR#5777</a>"),
"",
"<p class='text-danger'><strong>%s</strong></p>" % _(
"To permanently dismiss the critical notification displayed when the applet is used under Cinnamon 3.0.x, enable the option found in this applet settings window called \"I read the disclaimer and I'm aware of the consequences\", under the \"Disclaimer\" section."),
"",
])
))
def get_content_extra(self):
return md("{}".format("\n".join([
"",
"## %s" % _("Programs support"),
"",
_("In addition to Cinnamon's built-in screenshot/screencast tools, this applet also supports third-party programs to take captures. By default, this applet comes with support for several known programs (Shutter, Gnome Screenshot, XWD, ImageMagic, FFmepg, RecordMyDesktop, Byzanz and Kazam)."
),
"",
utils.get_bootstrap_alert(
heading=_("Highlights"),
content=md("""
- {0}
- {1}
- {2}
- {3}
- {4}
- {5}
- {6}""".format(
# TO TRANSLATORS: Do not translate the words "camera" and "recorder".
# MARKDOWN string. Respect formatting.
_("Programs are stored inside an applet preference. They are grouped by devices. A device called **camera** that contains programs that take screenshots. And a device called **recorder** that contains programs that capture screencasts."
),
_("Programs can be added/removed/modified as much as needed/wanted from this applet context menu by simply exporting the existent programs, modifying the generated JSON file and importing the modified file again."
),
_("Commands are exactly that, commands. They are composed of command line arguments , placeholders, and/or flags."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Placeholders are strings specifically formatted with double curly braces (`{{PLACEHOLDER_NAME}}`) and can be placed in any part of a string. These strings are replaced with dynamically generated data (an applet preference, screen coordinates, etc.) when a command is executed."
),
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("Flags are another type of specifically formatted strings surrounded by hashes (`#FLAG_NAME#`) and they always must be placed at the beginning of a string. Flags indicate that an action must be taken before a command is executed."
),
_("The exported JSON file exemplifies almost all the options, flags and placeholders documented below."
),
_("The command that will be executed can be previewed before actually executing it by simply right clicking a menu item."
),
))),
"",
utils.get_bootstrap_alert(context="warning",
heading=_("Warnings"),
content=md("""
- {0}
- {1}
- {2}
- {3}""".format(
_("All option names, flags, and placeholders are case sensitive. Command option names are lower cased and use dashes as word separators. Placeholders and flags are upper cased and use low dashes as word separators."
),
_("An imported JSON file will overwrite an existent preference."
),
_("Importing a malformed/invalid JSON file will cancel the import operation without modifying an existent preference."
),
_("There isn't a mechanism to check if a command is available or not on the system the applet is installed. So, use common sense."
),
))),
"",
"### %s" % _("Basic example"),
"",
"""```
{{
"camera": {{
"{pro_name}": {{
"title": "{pro_title}",
"cursor": {{
"on": "{cursor_on}",
"off": "{cursor_off}"
}},
"timer": true,
"append-1": "{append_1}",
"menuitems": {{
"{item_label} 1": "{item_command}",
"---": "{separator}",
"{item_label} 2": "{item_command}",
}}
}}
}},
"recorder": {{
"{pro_name}": {{
"title": "{pro_title}",
"fps": true,
"cursor": {{
"on": "{cursor_on}",
"off": "{cursor_off}"
}},
"sound": {{
"on": "{sound_on}",
"off": "{sound_off}"
}},
"menuitems": {{
"#{item_label} 1": "{item_command} ({item_label_hash})",
"---": "{separator}",
"{item_label} 2": "{item_command}",
}},
"stop-command": "{stop_command}"
}}
}}
}}
```""".format(
pro_name=_("Program/Command name"),
pro_title=_(
"Name of the program shown on the program selector menu"),
sound_on=_("Argument to include sound in capture"),
sound_off=_("Argument to not include sound in capture"),
stop_command=_("Command to stop recording"),
separator=_("This is a separator"),
cursor_on=_("Argument to include cursor in capture"),
cursor_off=_("Argument to not include cursor in capture"),
# TO TRANSLATORS: Do not translate the word "APPEND_1".
append_1=
_("The content here will be used to replace the {{APPEND_1}} placeholder"
),
item_label=_("Menu item label"),
item_label_hash=_("See %s." %
("**%s**" % _("Menu item label flags"))),
item_command=_(
"Command to execute when clicking this menu item"),
),
"",
"### %s" % _("Program options"),
"",
"| %s | %s | %s |" % (_("Option"), _("Usage"), _("Description")),
"| --- | --- | --- |",
"| `title` | %s | %s |" %
(_("Mandatory"),
_("This option will be used as the program name in the program selector sub-menu."
)),
"| `menuitems` | %s | %s |" %
(_("Mandatory"),
_("This option contains all the data that will be used to create the menu items for a program."
)),
"| `stop-command` | %s - %s | %s |" %
(_("Mandatory"), _("Recorder only"),
_("The command to stop recording a screencast.")),
"| `timer` | %s - %s | %s |" % (
_("Optional"),
_("Camera only"),
# TO TRANSLATORS: Do not translate the words "true" and "DELAY".
# MARKDOWN string. Respect formatting.
_("This option is used in combination with the `{{DELAY}}` placeholder. If set to **true**, sets the visibility of the **Capture delay** option inside this applet menu."
)),
"| `fps` | %s - %s | %s |" % (
_("Optional"),
_("Recorder only"),
# TO TRANSLATORS: Do not translate the word "true".
# MARKDOWN string. Respect formatting.
_("This option, if set to **true**, sets the visibility of the **Frames per second** option inside this applet menu."
)),
"| `cursor` | %s | %s |" % (
_("Optional"),
# TO TRANSLATORS: Do not translate the words "on", "off", and "CURSOR".
# MARKDOWN string. Respect formatting.
_("This option is used in combination with the `{{CURSOR}}` placeholder. It must contain two keys named **on** and **off** which respectively must contain a comand line argument for enabling/disabling the display of the mouse cursor on the captured file."
)),
"| `sound` | %s - %s | %s |" % (
_("Optional"),
_("Recorder only"),
# TO TRANSLATORS: Do not translate the words "on", "off", and "SOUND".
# MARKDOWN string. Respect formatting.
_("This option is used in combination with the `{{SOUND}}` placeholder. It must contain two keys named **on** and **off** which respectively must contain a comand line argument for enabling/disabling the inclusion of sound on the captured file."
)),
"| `append-1` ... `append-10` | %s | %s |" %
(_("Optional"),
_("These options are used in combination with the `{{APPEND_1}}` to `{{APPEND_10}}` placeholders. This is done to avoid repeating the same arguments on all menu items commands."
)),
"",
"### %s" % _("Flags"),
"",
"#### %s" % _("Menu item label flags"),
"",
"| %s | %s |" % (_("Flag"), _("Description")),
"| --- | --- |",
"| `#` | %s |" %
_("The hash (#) character in front of a menu item label is a flag that inhibits the menu item from changing the state of the applet (the change of the applet icon from normal to recording)."
),
"",
"#### %s" % _("Menu item command flags"),
"",
"| %s | %s |" % (_("Flag"), _("Description")),
"| --- | --- |",
"| `#INTERACTIVE_AREA_HELPER#` | %s |" %
_("This flag will allow the use of this applet area selector helper. See %s"
%
("**[%s](#menu-item-command-interactive-placeholders-{{lhc_lang_id}})**"
% _("Menu item command interactive placeholders"))),
"| `#INTERACTIVE_WINDOW_HELPER#` | %s |" %
_("This flag will allow the use of this applet window selector helper. See %s"
%
("**[%s](#menu-item-command-interactive-placeholders-{{lhc_lang_id}})**"
% _("Menu item command interactive placeholders"))),
"",
"### %s" % _("Menu item command placeholders"),
"",
"| %s | %s | %s |" %
(_("Placeholder"), _("Usage"), _("Description")),
"| --- | --- | --- |",
# TO TRANSLATORS: Do not translate the word "append".
# MARKDOWN string. Respect formatting.
"| `{{APPEND_1}}` ... `{{APPEND_10}}` | | %s |" %
_("Placeholder for the program options `append-1` to `append-10`."
),
"| `{{CURSOR}}` | | %s |" %
_("The command line argument used to decide if the capture will display the cursor or not."
),
"| `{{DELAY}}` | %s | %s |" %
(_("Camera only"),
_("Delay in seconds before taking a screenshot.")),
"| `{{DIRECTORY}}` | | %s |" %
_("The directory used as storage for the captures."),
"| `{{EXT}}` | | %s |" %
_("The file extension that the generated capture will have. It has to be used in pairs (Example: `{{EXT}}png{{EXT}}`)."
),
"| `{{FILENAME}}` | | %s |" %
_("The file name (no extension included) that the generated capture will have."
),
"| `{{FPS}}` | %s | %s |" %
(_("Recorder only"), _("Frames per second (frame rate).")),
"| `{{RECORDER_DIR}}` | | %s |" %
_("The directory used to store the screencast captures."),
"| `{{SCREEN_DIMENSIONS}}` | | %s |" %
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("The screen dimensions with format `widthxheight`. Example: `1440x900`"
),
"| `{{SCREEN_HEIGHT}}` | | %s |" % _("The screen height."),
"| `{{SCREEN_WIDTH}}` | | %s |" % _("The screen width."),
"| `{{SCREENSHOT_DIR}}` | | %s |" %
_("The directory used to store the screenshot captures."),
"| `{{SOUND}}` | %s | %s |" %
(_("Recorder only"),
_("The command line argument used to decide if the capture include sound or not."
)),
"",
'<span id="menu-item-command-interactive-placeholders-{{lhc_lang_id}}"></span>',
"",
"### %s" % _("Menu item command interactive placeholders"),
"",
"| %s | %s |" % (_("Placeholder"), _("Description")),
"| --- | --- |",
"| `{{I_X}}` | %s |" % _("`x` screen coordinates."),
"| `{{I_Y}}` | %s |" % _("`y` screen coordinates."),
"| `{{I_X_Y}}` | %s |" %
_("`x` and `y` screen coordinates separated by a comma."),
"| `{{I_WIDTH}}` | %s |" %
_("It could be either the width of a selected area or the width of a selected window."
),
"| `{{I_HEIGHT}}` | %s |" %
_("It could be either the height of a selected area or the height of a selected window."
),
"| `{{I_NICE_WIDTH}}` | %s |" %
_("Same as `I_WIDTH`, but with `1` added to its value."),
"| `{{I_NICE_HEIGHT}}` | %s |" %
_("Same as `I_HEIGHT`, but with `1` added to its value."),
"| `{{I_X_WINDOW_ID}}` | %s |" % _("The selected window ID."),
"| `{{I_X_WINDOW_FRAME}}` | %s |" %
_("The 'x-window' property of the selected window."),
"| `{{I_WM_CLASS}}` | %s |" % _("The selected window class name."),
"| `{{I_WINDOW_TITLE}}` | %s |" %
_("The selected window class title."),
"",
"## %s" % _("Cinnamon recorder profiles"),
"",
# TO TRANSLATORS: MARKDOWN string. Respect formatting.
_("The built-in Cinnamon recorder uses the GStreamer general-purpose multimedia framework ([GStreamer documentation](https://gstreamer.freedesktop.org/documentation/index.html)). It generates a video file with the `webm` extension using the `vp8enc` encoder and the `webmmux` muxer. This applet exposes the use of the Cinnamon recorder through profiles."
),
"",
utils.get_bootstrap_alert(heading=_("Highlights"),
content=md("""
- {0}
- {1}
""".format(
_("Profiles are stored inside an applet preference."
),
_("Profiles can be added/removed/modified as much as needed/wanted from this applet context menu by simply exporting the existent profiles, modifying the generated JSON file and importing the modified file again."
),
))),
"",
utils.get_bootstrap_alert(context="warning",
heading=_("Warnings"),
content=md("""
- {0}
- {1}
- {2}""".format(
_("An imported JSON file will overwrite an existent preference."
),
_("Importing a malformed/invalid JSON file will cancel the import operation without modifying an existent preference."
),
_("Like everything coming from Gnome, GStreamer is an always-evolving-never-finished-barely-functional piece of software. With that in mind, when using the wrong combination of encoder/muxer, Cinnamon will miserably crash. So, experiment at your own risk."
),
))),
"",
"### %s" % _("Basic example"),
"",
_("Below are the two Cinnamon recorder profiles shipped with this applet. The profile named default cannot be modified/deleted."
),
"",
"""```
{
"default": {
"title": "Default",
"description": "Encoder: On2 VP8\\nMuxer: WebM\\nFile extension: webm",
"file-extension": "webm",
"pipeline": "vp8enc min_quantizer=13 max_quantizer=13 cpu-used=5 deadline=1000000 threads=%T ! queue ! webmmux"
},
"x264enc": {
"title": "H264",
"description": "Encoder: H264\\nMuxer: Matroska\\nFile extension: mkv",
"file-extension": "mkv",
"pipeline": "x264enc ! queue ! matroskamux"
}
}
```""",
"",
"### %s" % _("Profile options"),
"",
_("All profile options are mandatory."),
"",
"| %s | %s |" % (_("Option"), _("Description")),
"| --- | --- |",
"| `title` | %s |" %
_("Name of the profile shown on the profile selector menu."),
"| `description` | %s |" %
_("Basic description of the profile that will be displayed as a tooltip."
),
"| `file-extension` | %s |" %
_("The file extension of the generated file."),
"| `pipeline` | %s |" % _("GStreamer pipeline."),
"",
"## %s" % _("Keyboard shortcuts"),
"",
_("Keyboard shortcuts are tied to specific capture types."),
"",
"## %s" % _("Known issues"),
"",
"<h3 class='text-danger'>%s</h3>" %
_("Cinnamon 3.0.x and its built-in screenshot mechanism"),
"",
"<p class='text-danger'><strong>%s</strong></p>" %
_("The Cinnamon's 3.0.x built-in screenshot mechanism is broken!"),
"",
"<p class='text-danger'><strong>%s</strong></p>" %
_("Do not use it or Cinnamon will crash!"),
"",
"<p class='text-danger'><strong>%s</strong></p>" %
_("It can only be fixed by building from source the cinnamon package for version 3.0.x with the following patch (%s). Or by simply updating to any other newer version of Cinnamon (3.2.x, 3.4.x, etc.)."
%
"<a href='https://github.com/linuxmint/Cinnamon/pull/5777'>PR#5777</a>"
),
"",
"<p class='text-danger'><strong>%s</strong></p>" %
_("To permanently dismiss the critical notification displayed when the applet is used under Cinnamon 3.0.x, enable the option found in this applet settings window called \"I read the disclaimer and I'm aware of the consequences\", under the \"Disclaimer\" section."
),
"",
])))