   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
- Support for icons. Changes done outside the program to the image files, 
  for example a replacement of the image file with a new one under the 
  same name, are taken over within a second, and the program will show the 
  new image.
- (Unlimited) Undo/Redo
- (Multirow) Drag and drop
- UTF-8 based search functionality with optional case sensitivity, 
  "word only" search and processing of regular expressions (incl. validity 
  check)
- Find and replace with the same options as for the search functionality 
  and prevention of invalid replacements (creating double menu IDs, 
  "enabled" options other than "yes" and "no")
- It is impossible to accidentally create a double menu ID, either by 
  entering it manually or by a find and replace action. The program will 
  always block this and show an error message.
- Auto-backup of overwritten menu (can be deactivated)
- Auto-reconfiguration of the menu after saving
- Context menu
- Editable tree view cells (dependent on the type of the cell)
- Fast and avoidance of overhead (programmed natively in C, 
  only dependency is GTK3, no additional packages or files used with the 
  exception of a settings file created by the program itself, no inclusion 
  of external Glade UI files). Help texts are compressed to save space.
- Dynamic, context sensitive interface
- Autosave
- The GUI adapts to dark themes/themes with a gradient
- The tree view can be customized (show/hide columns, grid etc.)
- In the "About" dialog, users are informed about the availability of a 
  newer version than the one currently installed (requires active internet 
  connection)
- The text of the menu file is checked for UTF-8 validity
- The program informs the user if there are missing menu/item labels, 
  invalid icon paths and menus defined outside the root menu that are not 
  included inside the latter. By request the program creates labels for 
  these invisible menus/items, integrates the orphaned menus into the root 
  menu and opens a file chooser dialog so that invalid icon paths can be 
  corrected.
- Handling of double/contradictory menu attribute values (explained in 
  the "Hints" window, see section below)
- Deprecated "execute" options are converted to "command" options
- The options of an "Execute" action and "startupnotify" option block can 
  be auto-sorted to obtain a constant menu structure
- The GUI can be reconfigured (server side decorations <-> client side 
  decorations, menu button <-> menubar)
- Saved menu files can either have a separate root menu with links to the 
  menus, which are then listed above the root menu, or have everything 
  packed into the root menu. It is also possible to choose between tabs 
  and four spaces for indentations.

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
- Galician
- Georgian
- German
- German (Switzerland, Liechtenstein)
- Greek
- Greenlandic
- Gujarati
- Haitian Creole
- Hausa
- Hebrew
- Hindi
- Hungarian
- Icelandic
- 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
- Norwegian (Bokmål)
- Norwegian (Nynorsk)
- Odia
- Pashto
- Persian
- Polish
- Portuguese (Brazil)
- Portuguese (Portugal)
- Punjabi (Gurmukhi)
- Romanian
- Russian
- Scottish Gaelic
- Serbian (Latin script)
- Setswana
- Sindhi
- Sinhala
- Slovak
- Slovenian
- Spanish
- Standard Tibetan
- Swahili
- Swedish
- Tajik (Cyrillic)
- Tamil
- Telugu
- Thai
- Turkish
- Turkmen
- Ukrainian
- Urdu
- Uyghur
- Uzbek
- Vietnamese
- Welsh
- Western Frisian
- Wolof
- Yoruba

The selection of languages ​​is based on practical criteria. Even though Faroese, 
for example, is a small language, it is firmly established as a school and 
official language. This is not the case for a planned language such as 
Interlingua or English in the Shavian alphabet. Such peripheral languages ​​and 
writing systems are not considered due to a lack of reception. The inclusion of 
languages ​​such as Romansh, for which there is still no accepted standard for a 
universal written language, is also problematic.
In cases where a translation would be practically identical to that of a larger 
language version (Valencian - Catalan), inclusion is also omitted.

Languages not considered for inclusion:

- Other planned languages ​​besides Esperanto (no practical relevance)
- English using the Shavian alphabet (no practical relevance)
- Valencian (would be redundant to Catalan)

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

The gettext internationalization and localization system serves as technical 
base for the translations. Translations are provided both as po files as well 
as binary mo files created from the original po files. Some longer texts 
(help files and shortcuts lists) are not provided as po files, but are 
compiled into the program in compressed form. The texts are not part of the po 
files because they are easier to edit if stored as simple text files. This also 
reduces redundancies, because if the texts were part of the po files, 
the original English texts would be repeated each time.

To ensure that the program will use translations, the script which 
installs Kickshaw must copy the content of source/resources/txts/translations 
to the usr/share/locale directory of the target PC.

If you want to use Kickshaw with a different language than the one used
by default for the system, start the program as
LANGUAGE=xx kickshaw
"xx" has to be a language code, so for example if your standard system 
language is Spanish, but you want Kickshaw to use the Portuguese 
translation, start Kickshaw as
LANGUAGE=pt kickshaw

In the English variants of the program, capitalization adheres to the
APA Style.

HINTS

Hints for the usage of Kickshaw can be found in the program by choosing 
"Hints" from the "Help" menu or by pressing F1.

DEPENDENCIES

The only direct dependency of Kickshaw is GTK3. The code makes use of GNU 
extensions, so a compiler is needed that supports them. Also, the program 
makes use of the POSIX extension that allows for positional parameters 
inside printf(). Since Kickshaw will most likely always be built with one 
of the major compilers GCC or Clang and the extensions used by Kickshaw 
are supported by both, this shouldn't require any extra preparations.

The program is not dependent on Openbox; it can be used inside all window 
managers/desktop environments that support GTK applications.

COMPILING AND INSTALLING THE PROGRAM

A makefile is included in the source directory. "make" and "make install"
are sufficient to compile and install this program; there is no configure 
script file which has to be started first. The default compiler set in the 
makefile is GCC, but can be switched to Clang by using "make CC=clang". An 
installation of a GTK3 devel package should supply all packages that are 
needed for compilation, if they haven't been installed yet.

By the means of conditional compilation it is ensured that the program can 
be compiled on older systems that have a GLib version >= 2.44 installed.
(This version of GLib was released in 2015.) The minimum GTK version is 
3.18 (also released in 2015).
Before actually compiling the Kickshaw source code, the preprocessor checks 
that the minimum versions are adhered to and stops compiling immediately if 
they are not. This is accompanied by a corresponding error message.
Since it is now unlikely that someone will try to compile Kickshaw against 
GLib and GTK versions that do not fulfill the minimum version requirements, 
these checks have been placed in the source code and not inside a configure 
script.

The standard used for compilation is by default gnu11.

REQUIREMENTS REGARDING MENU FILES

The program uses GLib's XML subset parser to read menu files, so it will 
be able to read a menu file regardless its formatting; it is necessary 
though that the file is encoded in UTF-8 (the program checks if the text of 
the menu file is valid UTF-8). In the case of an error the program gives a 
detailed error message, if possible. In some cases, for example if options 
have a wrong value or an image file that can't be loaded, the program will 
offer the option to correct such errors to avoid a premature termination.

STARTING KICKSHAW WITH OPTIONS/AN ARGUMENT

Kickshaw can be started with the options -v/--version for version 
information and -h/--help for some general hints. The program can 
also be started with the location of 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 can also be reached via the "Help" menu of the program.

TESTING SETUP DURING DEVELOPMENT

Operating systems used to test compilation and startup of the program are 
Linux, FreeBSD, and OpenIndiana.

Static analyzers used to find bugs, superfluous code, etc. are 
Cppcheck, Infer, and the static analyzers of both GCC and Clang.
