Update debian files

[indicator-keyboard-led.git] / README.md

diff --git a/README.md b/README.md
index e8f123c..cf90a7b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -16,75 +16,72 @@ off.
 Menu of the indicator, shown on click. The locks can be toggled by clicking
 the respective item in the menu.
 
 Menu of the indicator, shown on click. The locks can be toggled by clicking
 the respective item in the menu.
 

-![indicator short][sc3]  
-Alternative (short) appearance of the indicator.
+## Installation from Ubuntu PPA

 
 

-## Dependencies
- - Python 3 (*)
- - GTK+ 3 (*)
- - AppIndicator 3 (*)
- - Python 3 GObject introspection (python3-gi)
- - xdotool
+    sudo add-apt-repository ppa:adrianiainlam/indicator-keyboard-led
+    sudo apt-get update
+    sudo apt-get install indicator-keyboard-led

 
 

-Those marked with (*) are probably installed by default in recent Ubuntu
-distributions. To install the rest, run:
+After installation the postinst script will prompt you for preferences
+configuration. These config are explained here:

 
 

-    sudo apt-get install python3-gi xdotool
+### Order

 
 

-**Note**: [`gdk_keymap_get_scroll_lock_state ()`][gtkdoc-scroll] is only
-available since GTK+ 3.18. The earliest Ubuntu release that supports
-GTK+ 3.18 is 16.04 (Xenial). This means that if you use an older version
-you will have to ignore Scroll lock functionality (See [Examples](#examples)).
+This option allows you to reorder the locks and also to hide
+some locks if you don't need them.

 
 

-[gtkdoc-scroll]: https://developer.gnome.org/gdk3/stable/gdk3-Keyboard-Handling.html#gdk-keymap-get-scroll-lock-state
+Use a string consisting of zero or one occurrence of the
+characters 'N', 'C' and 'S' to set this option.

 
 

-## Usage
+For exampe, the default order is "Num Caps Scroll".  
+![Num Caps Scroll][sc1]

 
 

- 1. Install the dependencies listed above.
- 2. Clone this repository.
- 3. Add the script as a startup application. (Use option `--short` for short
-    appearance; use option `--order` to customize the order of the locks
-    displayed. See [Examples](#examples))
- 4. Run the script manually for the first time. (Alternatively, log out
-    and log in again.)
- 5. The indicator should be shown at the top right corner, with a filled circle
-    representing a lock turned on and an unfilled circle representing a lock
-    turned off.
- 6. Clicking on the indicator should result in a menu with the three locks.
-    Clicking on the menu item would cause the corresponding lock to toggle.
-
-## Examples
+**CNS** changes this to "Caps Num Scroll".  
+![Caps Num Scroll][sc4]

 
 

-![indicator default][sc1]  
-Default appearance. `python3 indicator-keyboard-led.py`
+**NC** hides Scroll lock from the default appearance.  
+![Num Caps][sc5]

 
 

-![indicator short][sc3]  
-Short appearance. `python3 indicator-keyboard-led.py --short`
+[sc1]: screenshots/sc1.png
+[sc2]: screenshots/sc2.png
+[sc4]: screenshots/sc4.png
+[sc5]: screenshots/sc5.png

 
 

-![indicator CNS][sc4]  
-Order changed to Caps Num Scroll.
-`python3 indicator-keyboard-led.py --order CNS`
+### xdotool

 
 

-![indicator NC][sc5]  
-Hide Scroll lock. `python3 indicator-keyboard-led.py --order NC`
+`xdotool` is used to emulate key strokes to set/unset locks on mouse clicks.
+If you installed xdotool at a non-default location, please provide its full
+path (e.g. /home/user/bin/xdotool) with this option.

 
 

-![indicator C short][sc6]  
-Show Caps lock only, short appearance.
-`python3 indicator-keyboard-led.py --short --order C`
+If it is installed in your $PATH environment variable, or not installed at
+all, leave this option blank.

 
 

-![indicator default, French locale][sc7]  
-Default appearance in a French locale.
-`LANGUAGE=fr_FR python3 indicator-keyboard-led.py`
+### Changing your mind

 
 

-[sc1]: screenshots/sc1.png
-[sc2]: screenshots/sc2.png
-[sc3]: screenshots/sc3.png
-[sc4]: screenshots/sc4.png
-[sc5]: screenshots/sc5.png
-[sc6]: screenshots/sc6.png
-[sc7]: screenshots/sc7.png
+If you want to change these settings afterwards, simply run
+
+    sudo dpkg-reconfigure indicator-keyboard-led
+
+and you will be prompted again.
+
+## Usage

 
 

-## Known bugs
+The indicator will be configured to autostart on log-in. To start using the
+indicator after installation, log-out and log-in again, or manually start
+the indicator (search for "indicator-keyboard-led" in the dash).
+
+The indicator should be shown at the top right corner, with a filled circle
+representing a lock turned on and an unfilled circle representing a lock
+turned off.
+
+Clicking on the indicator should result in a menu with the three locks.
+Clicking on the menu item would cause the corresponding lock to toggle.
+
+## Known bugs / Troubleshooting
+
+### Indicator label does not show on Xfce / XUbuntu
+
+See [#6](https://github.com/adrianiainlam/indicator-keyboard-led/issues/6).

 
 ### Pressing Scroll Lock does nothing
 
 
 ### Pressing Scroll Lock does nothing
 


@@ -92,7 +89,7 @@ It seems to be a common problem that Scroll Lock is not usable in Ubuntu.
 To solve this, do the following (assuming US keyboard):
 
  >     # backup your symbols file
 To solve this, do the following (assuming US keyboard):
 
  >     # backup your symbols file

- >     sudo cp /usr/share/X11/xkb/symbols/us{,.distribution} 
+ >     sudo cp /usr/share/X11/xkb/symbols/us{,.distribution}

  >
  > Add the following line in the `xkb_symbols "basic" {` section. Do not worry
  > if that second line is not there, it is only there for some languages and
  >
  > Add the following line in the `xkb_symbols "basic" {` section. Do not worry
  > if that second line is not there, it is only there for some languages and


@@ -100,7 +97,7 @@ To solve this, do the following (assuming US keyboard):
  >
  >     ...
  >         modifier_map Mod3   { Scroll_Lock }; <==<< Add this line
  >
  >     ...
  >         modifier_map Mod3   { Scroll_Lock }; <==<< Add this line

- > 
+ >

  >         include "level3(ralt_switch)" <==<< before this line
  >     };
  >
  >         include "level3(ralt_switch)" <==<< before this line
  >     };
  >


@@ -119,29 +116,55 @@ modified. [Original source][origsrc] by dm+ on PCLinuxOS-Forums.
 [origsrc]: http://www.pclinuxos.com/forum/index.php/topic,125690.msg1052201.html?PHPSESSID=2qsv83lve6dgd0ivq14bfcjc30#msg1052201
 [quotesrc]: http://askubuntu.com/a/597757/274080
 
 [origsrc]: http://www.pclinuxos.com/forum/index.php/topic,125690.msg1052201.html?PHPSESSID=2qsv83lve6dgd0ivq14bfcjc30#msg1052201
 [quotesrc]: http://askubuntu.com/a/597757/274080
 

-### X11Keymap has no attribute 'get_scroll_lock_state'
+### Scroll lock does not appear on indicator

 
 

-If running the script gives the error message
+Your installed GTK+ version is probably older than 3.18, which
+does not support [`gdk_keymap_get_scroll_lock_state ()`][gtkdoc-scroll].
+The earliest Ubuntu release that supports GTK+ 3.18 is 16.04 (Xenial).
+If you use an older version, Scroll lock functionality will be disabled.
+Please consider upgrading your system if you really want Scroll lock.

 
 

-    AttributeError: 'gtk.gdk.X11Keymap' object has no attribute 'get_scroll_lock_state'
+If your installed GTK+ is 3.18+ then please file a bug report.
+
+[gtkdoc-scroll]: https://developer.gnome.org/gdk3/stable/gdk3-Keyboard-Handling.html#gdk-keymap-get-scroll-lock-state

 
 

-then your installed GTK+ version is probably older than 3.18, which
-does not support `get_scroll_lock_state`. Either hide all Scroll Lock
-functionality (See [Examples](#examples)), or upgrade your system.
+### Drop-down menu only has "Quit", the clickable locks do not appear
+
+Please verify that xdotool is installed in your PATH with the executable
+bit set. If you provided a custom path to xdotool please verify that it
+is correct and is an executable regular file.

 
 ## Localization
 
 
 ## Localization
 

-As motivated by Issue #1, this script has been localized to French (with
-the assistance of Wikipedia and Google Translate). Corrections to the
-translation, as well as translations to other languages, are welcome.
-Feel free to create a pull request or open an issue.
+Unfortunately, in order to work-around labels not being shown on newer
+non-Unity-based Ubuntus, I have re-designed the indicators to be based
+purely on icons instead. This means there will no longer be labels to
+localize, and I instead have hardcoded icons.
+
+The icons are SVGs so you can still manually edit them if you want.
+Look for the `<text>` tag at the end of the SVGs.
+
+The menu items shown on click are still localized.
+
+I have included a screenshot below to show the old design (version 1.1)
+which you can still install manually if you wish.
+
+> As motivated by Issue #1, this script has been localized to French (with
+> the assistance of Wikipedia and Google Translate). Corrections to the
+> translation, as well as translations to other languages, are welcome.
+> Feel free to create a pull request or open an issue.
+>
+> ![indicator default, French locale][sc7]  
+> Default appearance in a French locale.
+
+[sc7]: screenshots/sc7.png

 
 ## License
 
 The program "indicator-keyboard-led.py" is released under the MIT License.
 Please refer to the file for the full text of the license.
 
 
 ## License
 
 The program "indicator-keyboard-led.py" is released under the MIT License.
 Please refer to the file for the full text of the license.
 

-The icon "icon.svg" is released to the public domain.
+The icons "indicator-keyboard-led*.svg" are released to the public domain.

 
 ## Credits
 
 
 ## Credits
 


@@ -149,8 +172,9 @@ I would like to thank [Tobias Schlitt](https://github.com/tobyS), who wrote
 [indicator-chars](https://github.com/tobyS/indicator-chars) which I used
 as a reference when writing this software.
 
 [indicator-chars](https://github.com/tobyS/indicator-chars) which I used
 as a reference when writing this software.
 

-The icon used in the indicator (icon.svg) is modified from the file
-"emblem-readonly.svg" by [Jakub Steiner](http://jimmac.musichall.cz)
+The icons used in the indicator (indicator-keyboard-led*.svg) are modified
+from the file "emblem-readonly.svg" by
+[Jakub Steiner](http://jimmac.musichall.cz)

 who released it to the public domain for the
 [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library).
 
 who released it to the public domain for the
 [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library).