   Kickshaw - A Menu Editor for Openbox

   Copyright (c) 2010–2025       Marcus Schätzle

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License along 
   with Kickshaw. If not, see http://www.gnu.org/licenses/.

---

FEATURES

- Localization support
- Icon support. Changes made to image files outside the program — for example, 
  replacing an image file with a new one under the same name — are detected 
  within a second, and the new image is displayed automatically.
- (Unlimited) Undo/Redo
- (Multi-row) Drag and drop
- UTF-8-based search functionality with optional case sensitivity, “whole word” 
  search, and support for regular expressions (including validity checks)
- Find and replace with the same options as the search functionality, including 
  safeguards against invalid replacements (e.g., duplicate menu IDs or invalid 
  values for the "enabled" attribute such as anything other than "yes" or "no")
- Duplicate menu IDs cannot be created, either manually or through a 
  find-and-replace action. The program blocks this and shows an error message.
- Automatic backup of overwritten menu files (can be disabled)
- Automatic reconfiguration of the menu after saving
- Context menu
- Editable tree view cells (depending on cell type)
- Fast and efficient performance with minimal overhead (natively programmed 
  in C; the only dependency is GTK3; no additional packages or files are 
  required, except for a self-created settings file; no external Glade UI files 
  are used). Help texts are compressed to save space.
- Dynamic, context-sensitive interface
- Autosave
- The GUI adapts to dark themes and themes with gradients
- Customizable tree view (e.g., show/hide columns, enable/disable grid lines, 
  etc.)
- The "About" dialog notifies users if a newer version is available (requires 
  an active internet connection)
- Menu file text is checked for UTF-8 validity
- The program informs users about missing menu/item labels, invalid icon paths, 
  and menus defined outside the root menu that are not included in it. Upon 
  request, it can generate labels for these invisible menus/items, integrate 
  orphaned menus into the root menu, and open a file chooser dialog to fix 
  invalid icon paths.
- Detection and handling of conflicting menu attribute values (explained in the 
  “Hints” window; see section below)
- Deprecated “execute” options are automatically converted to “command” options
- Options within an “Execute” action or a startupnotify block can be 
  auto-sorted to maintain a consistent menu structure
- The GUI can be reconfigured (e.g., switching between server-side and 
  client-side decorations, or between a menu button and a menubar)
- Menu files can be saved either with a separate root menu containing links to 
  other menus (which are listed above the root menu) or with all content merged 
  into the root menu. Users can also choose between tab characters and four 
  spaces for indentation.

LOCALIZATIONS

The program is currently available in the following language versions:

- Afrikaans
- Albanian
- Amharic
- Arabic
- Armenian
- Assamese
- Azerbaijani (Latin script)
- Basque
- Belarusian
- Bengali
- Bhojpuri
- Bosnian
- Breton
- Bulgarian
- Burmese
- Catalan
- Cebuano
- Chinese (Cantonese, traditional)
- Chinese (simplified)
- Chinese (traditional)
- Croatian
- Czech
- Danish
- Dutch
- English (UK)
- English (US)
- Esperanto
- Estonian
- Faroese
- Filipino
- Finnish
- French
- Friulian
- Fulah
- Galician
- Georgian
- German
- German (Switzerland, Liechtenstein)
- Greek
- Greenlandic
- Gujarati
- Haitian Creole
- Hausa
- Hebrew
- Hindi
- Hungarian
- Icelandic
- Igbo
- Indonesian
- Irish
- isiXhosa
- isiZulu
- Italian
- Japanese
- Kannada
- Kashmiri
- Kazakh (Cyrillic, conversion to Latin script planned)
- Khmer
- Kinyarwanda
- Konkani
- Korean
- Kurdish (Kurmanji)
- Kyrgyz
- Lao
- Latvian
- Lithuanian
- Luxembourgish
- Macedonian
- Maithili
- Malagasy
- Malay
- Malayalam
- Maltese
- Marathi
- Māori
- Mongolian (Cyrillic) 
- Nepali
- Northern Sotho
- Norwegian (Bokmål)
- Norwegian (Nynorsk)
- Odia
- Oromo
- Pashto
- Persian
- Polish
- Portuguese (Brazil)
- Portuguese (Portugal)
- Punjabi (Gurmukhi)
- Romanian
- Russian
- Sardinian
- Scottish Gaelic
- Serbian (Latin script)
- Setswana
- Sindhi
- Sinhala
- Slovak
- Slovenian
- Spanish
- Standard Tibetan
- Swahili
- Swedish
- Tajik (Cyrillic)
- Tamil
- Tatar
- Telugu
- Thai
- Tigrinya
- Turkish
- Turkmen
- Ukrainian
- Upper Sorbian
- Urdu
- Uyghur
- Uzbek
- Vietnamese
- Welsh
- Western Frisian
- Wolof
- Yoruba

Positive selection criteria for languages, varieties, and dialects:

- Has official status somewhere and/or is taught in schools
- Has a written standard or, if multiple standards exist, a dominant standard 
  that is widely understood
- Has at least several thousand speakers (e.g., Faroese)
- Has established terminology for common IT concepts, so terms do not have to 
  be artificially invented (e.g., Breton)
- Is a significant variety of a major language that differs at least in 
  punctuation and/or the alphabet (e.g., Swiss German)

Languages and alphabets currently not considered for inclusion:

- Planned/constructed languages that:
  - have very few speakers (e.g., Interlingua, Interlingue, Ido)
  - are too incomplete (e.g., Klingon)
  - lack basic IT terminology
- Languages, varieties, or dialects that are so close to a larger language that 
  a separate translation would be nearly redundant (e.g., Valencian)
- Alphabets with no practical relevance (e.g., the Shavian alphabet for 
  English)

The translations are complete and cover the user interface, program messages, 
and help files.

The gettext internationalization and localization system is the technical 
foundation for translations. They are provided both as .po files and as 
compiled binary .mo files. Some longer texts (e.g., help files and shortcut 
lists) are not provided as .po files but are compiled into the program in 
compressed form. These texts are excluded from the .po files because they are 
easier to edit as plain text and doing so reduces redundancy — otherwise, the 
original English texts would be repeated for every language.

To ensure translations are used by the program, the installation script must 
copy the contents of source/resources/txts/translations to the usr/share/locale 
directory of the target system.

If you want to use Kickshaw in a different language than your system default, 
start the program like this:

LANGUAGE=xx kickshaw

Here, "xx" is a language code. For example, if your system language is Spanish 
but you want to run Kickshaw in Brazilian Portuguese, use:

LANGUAGE=pt_BR kickshaw

In the English variants of the program, capitalization follows APA Style.

HINTS

Usage hints for Kickshaw can be found within the program by selecting "Hints" 
from the "Help" menu or by pressing F1.

DEPENDENCIES

The only direct dependency of Kickshaw is GTK3. The code uses GNU extensions, 
so a compiler that supports them is required. Additionally, the program relies 
on a POSIX extension that allows positional parameters in printf(). Since 
Kickshaw is typically built using either GCC or Clang, both of which support 
the required extensions, no special configuration should be necessary.

Kickshaw is not dependent on Openbox and can be used in any window manager or 
desktop environment that supports GTK applications.

COMPILING AND INSTALLING

A Makefile is included in the source directory. Simply running make and make 
install is sufficient to compile and install the program — there is no need to 
run a separate configure script.

The default compiler set in the Makefile is GCC, but you can switch to Clang by 
running:

make CC=clang

Installing a GTK3 development package will typically provide all necessary 
dependencies if they aren't already installed.

Through conditional compilation, the program ensures compatibility with older 
systems that have GLib version ≥ 2.44 (released in 2015). The minimum GTK 
version required is 3.18 (also released in 2015).

Before compilation, the preprocessor checks that these minimum versions are met 
and will stop the build process with an appropriate error message if they are 
not. Since it's now unlikely that someone will attempt to compile Kickshaw with 
unsupported versions, these checks are implemented directly in the source code 
rather than via a configure script.

The default compilation standard is gnu11.

MENU FILE REQUIREMENTS

Kickshaw uses GLib’s XML subset parser to read menu files, allowing it to 
handle files regardless of formatting. However, files must be encoded in UTF-8. 
The program checks for valid UTF-8 encoding in the file content.

If an error occurs, Kickshaw provides a detailed message when possible. In some 
cases (e.g., invalid attribute values or missing image files), the program will 
offer the option to correct the issue in order to avoid premature termination.

STARTING KICKSHAW WITH OPTIONS OR ARGUMENTS

Kickshaw supports the following options:

-v, --version: Show version information
-h, --help:    Show general usage hints

You can also start Kickshaw with a path to a menu file as an argument, for 
example:

kickshaw ~/.config/openbox/test.xml

BUG REPORTS

Bug reports can be submitted at:

https://savannah.nongnu.org/bugs/?group=obladi&func=additem

This page is also accessible via the "Help" menu in the program.

TESTING SETUP DURING DEVELOPMENT

Operating systems used to test compilation and startup:

- Linux
- FreeBSD
- OpenIndiana

Static analysis tools used:

- Cppcheck
- Infer
- Static analyzers from both GCC and Clang
