Index entry for Object Replacement Character

Index entry for Object Replacement Character

[Eli Zaretskii]

I don't understand why you added an index entry for this.  Can you
explain?

Here's my take on this: Index entries exist to make it easier for the
reader to find the description/discussion of a subject.  In this case,
the subject of the text where the Object Replacement Character is
reordering of display properties in bidirectional text.  The fact that
the Emacs implementation treats text covered by a display property as
if it were a single character with the bidirectional properties of
u+FFFC is an implementation detail, mentioned by the way for those who
are interested enough to look up that character.  The text does not
explain anything about that character, and doesn't say why it was
chosen for this role.  The character is mentioned once, and that's it.

Therefore, I find it hard to believe that any reader will thing about
this character's name as a good string to try at the prompt of the
Info's 'i' command.  Likewise, I see no reason why someone who wants
to know about this character will look for its description in the ELisp
manual.  So having this index entry there is not useful.

More generally, not every term you see in a manual deserves an index
entry.  It only does deserve an entry if (a) the term is described and
explained at that place, and (b) there's a high probability that
readers will think about the phrase you put in an index entry when
they are looking for the subject described at that place.

Re: Index entry for Object Replacement Character

[Xue Fuqiao]

On Wed, Nov 6, 2013 at 1:59 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> I don't understand why you added an index entry for this.  Can you
> explain?
>
> Here's my take on this: Index entries exist to make it easier for the
> reader to find the description/discussion of a subject.  In this case,
> the subject of the text where the Object Replacement Character is
> reordering of display properties in bidirectional text.  The fact that
> the Emacs implementation treats text covered by a display property as
> if it were a single character with the bidirectional properties of
> u+FFFC is an implementation detail, mentioned by the way for those who
> are interested enough to look up that character.  The text does not
> explain anything about that character, and doesn't say why it was
> chosen for this role.  The character is mentioned once, and that's it.
>
> Therefore, I find it hard to believe that any reader will thing about
> this character's name as a good string to try at the prompt of the
> Info's 'i' command.  Likewise, I see no reason why someone who wants
> to know about this character will look for its description in the ELisp
> manual.  So having this index entry there is not useful.
>
> More generally, not every term you see in a manual deserves an index
> entry.  It only does deserve an entry if (a) the term is described and
> explained at that place, and (b) there's a high probability that
> readers will think about the phrase you put in an index entry when
> they are looking for the subject described at that place.

Thanks, I agree with you.  Sorry for the noise commit and I'll note that
in the future.

(I've reverted the change as trunk revision 115004.)

-- 
http://www.gnu.org/software/emacs/

Re: Index entry for Object Replacement Character

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 693 bytes --]

() Xue Fuqiao <xfq.free@gmail.com>
() Wed, 6 Nov 2013 22:22:40 +0800

   On Wed, Nov 6, 2013 at 1:59 AM, Eli Zaretskii <eliz@gnu.org> wrote:

   > I don't understand why you added an index entry for this.
   > Can you explain?

   Thanks, I agree with you.  Sorry for the noise commit and
   I'll note that in the future.

   (I've reverted the change as trunk revision 115004.)

I'm still curious about the motivation for the change.  Care to share?

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: Index entry for Object Replacement Character

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnu.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel <emacs-devel@gnu.org>
> Date: Thu, 07 Nov 2013 07:27:21 +0100
> 
> () Xue Fuqiao <xfq.free@gmail.com>
> () Wed, 6 Nov 2013 22:22:40 +0800
> 
>    On Wed, Nov 6, 2013 at 1:59 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>    > I don't understand why you added an index entry for this.
>    > Can you explain?
> 
>    Thanks, I agree with you.  Sorry for the noise commit and
>    I'll note that in the future.
> 
>    (I've reverted the change as trunk revision 115004.)
> 
> I'm still curious about the motivation for the change.  Care to share?

What change did you have in mind?

Re: Index entry for Object Replacement Character

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 466 bytes --]

() Eli Zaretskii <eliz@gnu.org>
() Thu, 07 Nov 2013 17:56:25 +0200

   What change did you have in mind?

The original addition of the index entry.
(I idly wonder if it is part of some larger
documentation thrust -- no big deal.)

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: Index entry for Object Replacement Character

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnu.org>
> Date: Fri, 08 Nov 2013 08:55:52 +0100
> 
>    What change did you have in mind?
> 
> The original addition of the index entry.
> (I idly wonder if it is part of some larger
> documentation thrust -- no big deal.)

Improvements in indexing are always welcome.  A good index is
invaluable in letting users find the relevant information very
quickly.

Re: Index entry for Object Replacement Character

[Xue Fuqiao]

On Thu, Nov 7, 2013 at 2:27 PM, Thien-Thi Nguyen <ttn@gnu.org> wrote:
> I'm still curious about the motivation for the change.  Care to share?

Sure.  My motivations for the change are: a) it is a term defined by
@dfn; b) although it is not an Emacs-specific term, there are many other
non-Emacs-specific terms in the index, like `.mailrc', `7z', `Bazaar'
etc..  But now I think that my excuses aren't good enough.

-- 
http://www.gnu.org/software/emacs/

Re: Index entry for Object Replacement Character

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 808 bytes --]

() Xue Fuqiao <xfq.free@gmail.com>
() Fri, 8 Nov 2013 15:50:44 +0800

   a) it is a term defined by @dfn;

   b) although it is not an Emacs-specific term, there are many other
   non-Emacs-specific terms in the index, like `.mailrc', `7z', `Bazaar'
   etc..

Thanks.

   But now I think that my excuses aren't good enough.

I think if "object replacement character" graduates from conceptual
analog ("as if they were" => not an authoritative affirmation) to
user-visible design detail (say), then those reasons will be fine.
Maybe you were just being prescient!

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: Index entry for Object Replacement Character

[Eli Zaretskii]

> From: Thien-Thi Nguyen <ttn@gnuvola.org>
> Date: Fri, 08 Nov 2013 12:32:59 +0100
> 
> I think if "object replacement character" graduates from conceptual
> analog ("as if they were" => not an authoritative affirmation) to
> user-visible design detail (say), then those reasons will be fine.

"Object replacement character" is the official Unicode name of U+FFFC,
that's all.

Re: Index entry for Object Replacement Character

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 439 bytes --]

() Eli Zaretskii <eliz@gnu.org>
() Fri, 08 Nov 2013 16:03:12 +0200

   "Object replacement character" is the official
   Unicode name of U+FFFC, that's all.

Right (this much i understand, at least :-D).

-- 
Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]