   Kickshaw - A Menu Editor for Openbox

   Copyright (c) 2010–2024        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/.


---

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.

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 compact, 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)
- 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.

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.

HINTS

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

LOCALIZATIONS

Localization is supported by the use of gettext. There are translations  
available which come with the original archive. They cover the following
languages:

- Afrikaans
- Albanian
- Azerbaijani (Latin Alphabet)
- Basque
- Bengali
- Catalan
- Chinese (simplified)
- Croatian
- Czech
- Danish
- Dutch
- Finnish
- French
- German
- Greek
- Hindi
- Hungarian
- Icelandic
- Indonesian
- Italian
- Japanese
- Korean
- Latvian
- Maltese
- Norwegian (Bokmål)
- Polish
- Portuguese
- Romanian
- Russian
- Spanish
- Swedish
- Turkish
- Vietnamese
- Welsh
- Western Frisian

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

The variety of English used in the program is American English.
Capitalization adheres to the APA Style.

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.
