After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 633534 - Offer documentation of all compose key sequences
Offer documentation of all compose key sequences
Status: VERIFIED FIXED
Product: gnome-user-docs
Classification: Core
Component: gnome-help
2.22.x
Other All
: Normal enhancement
: ---
Assigned To: Maintainers of Gnome user documentation
Maintainers of Gnome user documentation
Depends on:
Blocks:
 
 
Reported: 2010-10-30 09:58 UTC by Pander
Modified: 2016-07-28 13:15 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Proposed output (18.54 KB, application/vnd.oasis.opendocument.spreadsheet)
2011-07-07 06:51 UTC, Pander
Details

Description Pander 2010-10-30 09:58:09 UTC
Please offer TXT, HTML and PDF files in /usr/share/doc/libgtk with an exhaustive list of compose key sequences which are defined in:
  http://svn.gnome.org/viewvc/gtk%2B/trunk/gtk/gtkimcontextsimpleseqs.h?view=markup
and in:
  http://svn.gnome.org/viewvc/gtk%2B/trunk/gtk/gtk-compose-lookaside.txt?view=markup

Ubuntu community is offering a list only in HTML which is managed manually https://help.ubuntu.com/community/GtkComposeTable but will always be lagging behind and it will be prone to errors.

Also notify known downstream applications such as https://help.ubuntu.com/community/GtkComposeTable, gnome-control-center and gnome-keyboard-properties to offer a link to this PDF.

Implementing this will allow users to discover more compose key sequences and improve user satisfaction when entering non-standard characters.
Comment 1 Christian Persch 2010-10-30 17:07:40 UTC
Wouldn't this be more suitable for the gnome-user-docs instead of the gtk documentation (which is targeting developers, not users) ?
Comment 2 Pander 2010-10-30 18:56:53 UTC
Depends on what the GTK/GNOME developers implementing this would like. Of course gnome-user-docs can refer to these files. Both is fine with me.
Comment 3 Pander 2011-01-09 14:57:33 UTC
changed prodcut to gnome-user-docs, please confirm this bug.
Comment 4 Phil Bull 2011-06-08 20:36:12 UTC
Thanks for reporting this bug. This has been fixed in the new gnome-help, which targets GNOME 3.0 (we are no longer supporting user-guide). An exhaustive list of compose sequences has not been provided because we don't see any point in maintaining a list ourselves. We link out to the exhaustive list on Wikipedia instead.
Comment 5 Pander 2011-06-08 21:38:23 UTC
What is the URL?
Comment 6 Phil Bull 2011-06-08 21:49:17 UTC
You can find the page where this is documented here:

http://library.gnome.org/users/gnome-help/stable/tips-specialchars.html.en#compose

It links to the following Wikipedia page:

http://en.wikipedia.org/wiki/Compose_key#Common_compose_combinations
Comment 7 Pander 2011-06-09 06:21:24 UTC
I'm sorry but both URLs provide even less information that is available in https://help.ubuntu.com/community/GtkComposeTable

The bug reports asks for an exhaustive list documenting all defined compose key sequences. This documentation is to be generated automatically from source files.

A friend of mine has some code that does this for emacs regarding the GNOME compose key sequences. I can ask if I can post it here as an example.

Could you please reopen this bug?
Comment 8 Phil Bull 2011-06-09 12:03:40 UTC
When writing the documentation, we need to think about more than just dumping a lot of information on the user just in case they need it. Why the user needs the information, how it should be presented, and ways the user can find their way to the information all need to be considered. In particular, the more information you add to a help system, the more difficult it becomes for users to find relevant topics. As a result, I'm hesitant to add large reference tables like this to the main user documentation.

Why might a user need an exhaustive list of the key sequences? In what context would you expect them to need this information?
Comment 9 Pander 2011-06-09 14:26:23 UTC
Please review the proposal below:

Use case 1
New or experienced user of GNOME is using a lot of Unicode. The usual compose key sequences are know, but more less-used compose key sequences are unknown. Some are very hard to find by simply trying. Labour-intensive copy-pasting of Unicode from a web browser, any other document or symbol application is the only alternative. An exhaustive list containing all compose key sequences in the reference manual or web-page helps this user find the compose key sequence he or she is looking for.

Use case 2
User or developer would like to request a new compose key combination and would like an overview of the existing ones in order to propose a combination that is still available and is in accordance with the expected convention for that type of Unicode (math, greek, etc.). Browsing an exhaustive list containing all compose key sequences in the reference manual or web-page helps this user.

Use case 3
Developers working on compose key sequences use above mentioned list as documentation to fine tune compose key sequences with other compose key facilities, for example Xorg, emacs. etc.

Technical note 1
The source code should be scanned for compose sequences which should be grouped on subject and enriched with comments where needed, for example 'Number sign' would be turn into 'Number sign (#)'. Output should be written in XML from which HTML and PDF can be processed.

Technical note 2
Both current stable source and latest greatest head of version control should be processed and differences should be reflected in the output. For example, green for new code, red for a removed code and orange for a changed code.

Technical note 3
I (Pander) am willing to make a contribution if GNOME developers agree with a final proposal and one of the developers will implement it in the release procedure.

Benefits
Providing this generated documentation will improve user satisfaction in working with GNOME and easily entering common and more exotic Unicode by means of compose key. It will also provide reference documentation for other implementations and save time and effort that currently goes into https://help.ubuntu.com/community/GtkComposeTable
Comment 10 Phil Bull 2011-06-12 23:05:18 UTC
Thanks for the detailed response. This is the sort of thing that would probably be better off as a standalone document rather than being integrated into the desktop help.

Can you help me understand why an end-user might be making heavy use of uncommon Unicode symbols? Also, is there a reason why they would need a large document-style listing of all of the possible characters rather than using the Character Map application?
Comment 11 Pander 2011-06-13 07:24:16 UTC
For me it doesn't matter so much as where the document is published. It could be a Compose Key Sequence Reference Guide available in PDF and HTML. It might even serve as a reference implementation or industry standard.

An end-user could write in one document in Latin script (with æ and ß), Cyrillic script (š and č), Greek (µ) and Kana script (romaji with ū and ō) and use symbols such as degrees (°), n-dashes, m-dashes, centered dots, ellipses, opening and closing quotation marks and so on. It doesn't have to be prose, many proper geographical names require Unicode.

Many people prefer to enter these codes themselves (when they know they exist) rather then have a word processor do that for them by automatic replacements, also in times when they don't want that.

It be much more efficient to look up the compose key sequence for č when writing a few days about the city of Vrsač then using the character map application or copy paste all the time. And later using that acquired knowledge to produce a š in the Veršet. So end-user have a choice to use the character map application or step by step increase their knowledge of compose key sequence and being able to look them up when forgotten or unknown.

As a spin-off, this information could also be presented by the character map application as a tooltip or on the far right of the status bar.

What would be a good tool to be called in the build process to extract the initial information from the source file? Is Python an option that will be supported by the GNOME/GTK build process?
Comment 12 David Regev 2011-06-13 07:55:42 UTC
Another relevant use case is transliteration from a different language. The odd combinations of diacritics and special characters can easily build up, and learning the combinations for those obscure characters can speed things up greatly. Besides that, wasn’t every sequence added because someone thought it would be useful? If it weren’t, it wouldn’t make much sense much sense to dedicate a special quick way of entering these characters.

Bug 321896 has a script that parses the X.org list of sequences[*]. Could that be used as a start to create a simple web page with a table?

[*] http://cgit.freedesktop.org/xorg/lib/libX11/plain/nls/en_US.UTF-8/Compose.pre
Comment 13 Pander 2011-07-06 16:14:13 UTC
Ah, that one is made by http://git.gnome.org/browse/gtk+/tree/gtk/compose-parse.py
Comment 14 Pander 2011-07-07 06:51:41 UTC
Created attachment 191434 [details]
Proposed output

First sheet is for end-users, second sheet is as reference for developers and compose key maintainers. Output formats should be at least TXT, HTML and PDF.
Comment 15 Pander 2011-12-13 18:01:52 UTC
Hi all, I have generated a draft PDF documenting *all* GNOME compose key sequences. If you would like to review it, please send me an email.
Comment 16 Pander 2013-02-01 10:09:45 UTC
Fixed myself, see http://bit.ly/WCq8Qt
Comment 17 Mats Blakstad 2015-10-10 01:54:58 UTC
Where can pacthes to submit new Compose Key Sequences be added?

In GtkComposeTable documentation for Ubuntu it is written:
"The Gtk Compose Table was derived from the X compose tables of XFree86 version 4.0 with further modification intended to provide a Gnome standard for all locales. It is likely that in future it will follow more closely the xorg version."
https://help.ubuntu.com/community/GtkComposeTable

Are there Gnome locale compose keys? Where can there packs be found?

And what exactly does this "move towards" xorg version mean?
Comment 18 ju2gle 2016-04-18 08:30:16 UTC
Proposal to add the following to GtkComposeTable:

(exclam) (exclam) () (0323) (dot below)

I was looking forever to find this. It is entered by typing an exclamation mark and then the according letter and you'll get the letter with a dot below.
Comment 19 Pander 2016-04-26 10:26:01 UTC
Your reqeust should be made in a separate bug report, if it is still needed after discussion.

(exclam) (exclam) is already resulting in inverted exclamatin mark ¡ See also https://en.wikipedia.org/wiki/Inverted_question_and_exclamation_marks So that sequence is already taken. Dot below on a character can be found with e.g. U!a ặ or U!A Ặ. Perhaps _. or _! could be used for this, but it is uncommon to give a combining diacritic such predominant compose key sequence. So Ctrl+Shift+U 323 is a good workaround.

By the way, the link above from 2013 is defunct now, persistent url is https://www.createspace.com/3758226 In 2017 an updated version will be published.
Comment 20 Pander 2016-04-26 11:41:11 UTC
To answer Mats, there are different definitions in X and GNOME. The ones in X are leading, see https://cgit.freedesktop.org/xorg/lib/libX11/plain/nls/en_US.UTF-8/Compose.pre and that is the place to request now sequences.
Comment 21 ju2gle 2016-04-26 13:05:23 UTC
I was not talking about changing the source code, but adding some more description to the wiki.

I realize, my description above was wrong, but what I actually was looking for was a documentation of  the sequence exclam-character. Like

(a) (exclam) -> (a with dot below)
(b) (exclam) -> (b with dot below)
...

This works for me (Ubuntu 15.10 with Gnome Shell), but I couldn't find it documented anywhere.
Comment 22 Pander 2016-04-26 13:28:12 UTC
I was frustrated about that for a long long time too. So, eventually wrote a book about it. ☺ See the link above. All that is in there from 2012 is still valid and will remain valid as only sequences will be added and not revoked. See https://i.imgur.com/XGZ8xAG.jpg and https://i.imgur.com/nOVHmwG.jpg for an impression.
Comment 23 Audrey Toskin 2016-07-13 03:04:22 UTC
So wait, what's the status on this issue? The top of the page says "VERIFIED FIXED", but I don't see a Compose Key reference page anywhere in wiki.gnome.org or help.gnome.org, and the Compose Key page in Yelp is still very minimal.
Comment 24 Pander 2016-07-13 07:56:28 UTC
The software I have developed to write my book can also output (in wiki or other format) a table that can be included to document all compose key sequences. However, I have never found anyone who is willing to help out with that. Would you? If it is usable, I am willing to donate that part of my code so it can be included in the GNOME continuous integration build process or whatever exists.

I prefer to work on maintaining my documentation software, but need a GNOME maintainer to do the integration part.
Comment 25 Audrey Toskin 2016-07-14 22:24:51 UTC
@Pander
I could help edit/format a wiki page. But you were talking about automating the generation and updates to the page, and I don't know anything about GNOME's code base or git infrastructure.

The Ubuntu GtkComposeTable seems pretty good, but I dunno if it's 100% complete. And anyway, since this is a GNOME feature, it would make sense for GNOME to document it.