bug#3568: 23.0.94; no doc for character composition

bug#3568: 23.0.94; no doc for character composition

[Drew Adams]

I can find no doc at all regarding character composition, beyond the
cursory explanation given in the Emacs manual, node Input Methods.
 
In particular, there is nothing in the Elisp manual about it. No
documentation of functions such as `compose-region' and
`compose-chars'.
 
And there is no usage commentary in `composite.el'.
 
How does one compose characters using Emacs Lisp? If characters have
been composed, how do you decompose them? Are there any caveats to be
aware of? Users will have such questions.
 
For example, this snippet is commonly used here and there to display the word
`lambda' as the Greek character:
 
(font-lock-add-keywords
   mode `(("\\<lambda\\>"
   (0 (progn (compose-region (match-beginning 0) (match-end 0)
        ,(make-char 'greek-iso8859-7 107))
      nil)))))
 
But removing that keyword entry from font-lock-keywords, unfontifying, then
refontifying is not sufficient to display `lambda' as a word again. What needs
to be done, to restore the normal display of the word `lambda'?  This kind of
information is missing.
 
Perusing `composite.el', I see that this will do the job:
 
(font-lock-remove-keywords
     nil `(("\\<lambda\\>"
            (0 (progn (compose-region (match-beginning 0) (match-end 0)
                                      ,(make-char 'greek-iso8859-7 107))
                      nil)))))
(save-excursion
   (goto-char (point-min))
   (while (re-search-forward "\\<lambda\\>" nil t)
     (decompose-region (match-beginning 0) (match-end 0))))
 
But it would be helpful to have a little doc in the Elisp manual
explaining how to use character composition. This feature deserves some doc. 

Compare, for example, the doc for font-locking with that for character
composition. Even if these features are not of the same scale, you can see a
qualitative difference in the doc support.

Look at the commentary in file font-lock.el - a section explaining clearly "How
Font Lock mode fontifies", and another section explaining "What is fontification
for?". Plenty of Info doc, in both the Emacs and Elisp manuals.

Character composition should be better documented. I can understand if the
author is not comfortable providing lots of English doc, but someone who
understands character composition should do so. Think in terms of how Emacs
users and Emacs-Lisp users might make use of this feature, then write that up
for those of us who are ignorant.

Thanks.
 
In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600)
 of 2009-05-24 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#3568: 23.0.94; no doc for character composition

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> I can find no doc at all regarding character composition, beyond the
> cursory explanation given in the Emacs manual, node Input Methods.
>
> In particular, there is nothing in the Elisp manual about it. No
> documentation of functions such as `compose-region' and
> `compose-chars'.
>
> And there is no usage commentary in `composite.el'.
>
> How does one compose characters using Emacs Lisp? If characters have
> been composed, how do you decompose them? Are there any caveats to be
> aware of? Users will have such questions.

`compose-region' has a very long doc string...  And it seems to have
been added to after you wrote this bug report.  Does it answer your
questions now?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#3568: 23.0.94; no doc for character composition

[Drew Adams]

> > I can find no doc at all regarding character composition, beyond the
> > cursory explanation given in the Emacs manual, node Input Methods.
> >
> > In particular, there is nothing in the Elisp manual about it. No
> > documentation of functions such as `compose-region' and
> > `compose-chars'.
> >
> > And there is no usage commentary in `composite.el'.
> >
> > How does one compose characters using Emacs Lisp? If characters have
> > been composed, how do you decompose them? Are there any caveats to be
> > aware of? Users will have such questions.
> 
> `compose-region' has a very long doc string...  And it seems to have
> been added to after you wrote this bug report.  Does it answer your
> questions now?

No.  `compose-region' already had that doc string when the bug was
reported.  That doc string has been around since at least Emacs 22.

I would expect some conceptual explanation of character composition
in the Elisp manual.  Including how to decompose composed chars etc.
What the bug report mentions.  I don't think that a doc string for
one command covers this topic.

bug#3568: 23.0.94; no doc for character composition

[Eli Zaretskii]

> Date: Wed, 27 Apr 2016 12:42:56 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 3568@debbugs.gnu.org
> 
> No.  `compose-region' already had that doc string when the bug was
> reported.  That doc string has been around since at least Emacs 22.

Then I don't understand what else do you want to know about
compose-region and character composition in general.

> I would expect some conceptual explanation of character composition
> in the Elisp manual.

Please start by explaining what is missing from the doc string of
compose-region, because otherwise it is impossible to translate your
expectation to any concrete text.

The example you gave in the bug report is not about character
composition, it's about font-lock.  So maybe that is what you need to
be explained.  However, the bug report says "character composition",
so until you agree it's about something else, "character composition"
it is.

> Including how to decompose composed chars etc.

You can't.  This question makes no sense.  Character composition
converts several characters into one or more glyphs to be displayed;
you cannot "decompose" them, and in any case the result of such
decomposition is known in advance: they are the original characters.

> What the bug report mentions.  I don't think that a doc string for
> one command covers this topic.

Well, I think it does.  You could change my mind by telling what is it
that you miss in that doc string.

bug#3568: 23.0.94; no doc for character composition

[Drew Adams]

> > No.  `compose-region' already had that doc string when the bug was
> > reported.  That doc string has been around since at least Emacs 22.
> 
> Then I don't understand what else do you want to know about
> compose-region and character composition in general.
> 
> > I would expect some conceptual explanation of character composition
> > in the Elisp manual.
> 
> Please start by explaining what is missing from the doc string of
> compose-region, because otherwise it is impossible to translate your
> expectation to any concrete text.
> 
> The example you gave in the bug report is not about character
> composition, it's about font-lock.  So maybe that is what you need to
> be explained.  However, the bug report says "character composition",
> so until you agree it's about something else, "character composition"
> it is.
> 
> > Including how to decompose composed chars etc.
> 
> You can't.  This question makes no sense.  Character composition
> converts several characters into one or more glyphs to be displayed;
> you cannot "decompose" them, and in any case the result of such
> decomposition is known in advance: they are the original characters.
> 
> > What the bug report mentions.  I don't think that a doc string for
> > one command covers this topic.
> 
> Well, I think it does.  You could change my mind by telling what is it
> that you miss in that doc string.

I'd like an explanation of character composition, in the Elisp manual.
If you don't want to add one, or you don't think it is useful for users,
so be it.

As one user, I know nothing about this.  And I still know nothing
about it after reading that doc string.  FWIW.

bug#3568: 23.0.94; no doc for character composition

[Eli Zaretskii]

> Date: Wed, 27 Apr 2016 14:18:20 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: larsi@gnus.org, 3568@debbugs.gnu.org
> 
> > > What the bug report mentions.  I don't think that a doc string for
> > > one command covers this topic.
> > 
> > Well, I think it does.  You could change my mind by telling what is it
> > that you miss in that doc string.
> 
> I'd like an explanation of character composition, in the Elisp manual.

Would copying the doc string of compose-region into the manual do what
you want?  If not, what in that doc string is missing or not explained
well enough?

> As one user, I know nothing about this.  And I still know nothing
> about it after reading that doc string.  FWIW.

I don't understand this claim.  You certainly know what the doc string
says, which is definitely not "nothing".

Is this a serious bug report?  If it is, would you please help me
understand what is missing in the documentation, by at least answering
my questions, if not by elaborating some more about the problem?  TIA.