(no subject)

(no subject)

[Luc Teirlinck]

`(emacs)Requesting Formatted Text' contains:

   You can add annotations for saving additional text properties,
   which Emacs normally does not save, by adding to
   `enriched-translations'.  Note that the text/enriched standard
   requires any non-standard annotations to have names starting with
   `x-', as in `x-read-only'.  This ensures that they will not
   conflict with standard annotations that may be added later.

   *Note Text Properties: (elisp)Text Properties, for more information
   about text properties.

But `enriched-translations' is defined in enriched.el with a
def_const_.  This suggest (maybe misleadingly) that the value should
not be messed with.  Also, if enriched.el gets (re-)loaded, any user
redefined value will be overridden again.  I believe that the defconst
should be changed to a defvar.  There seem to be unusually many
defconst's in enriched.el.  Do some other ones also need to be made
into defvar's?

There also is the problem that the text quoted above makes things look
much simpler than they are.  If one wants to successfully add
annotations for saving additional text properties, one will have to
(at least) read through three docstrings, two of which are rather long
and some parts of which assume at least some familiarity with Elisp
and with the text/enriched standard.  Depending on what one wants to
do, one might have to be able to write reasonably complex Lisp functions.
Remember that this is the Emacs (not Elisp) manual.

Do we want to keep the above paragraph in the Emacs manual?  It also
occurs in enriched.doc, where it more clearly seems aimed at a more
sophisticated audience:

    - You can add annotations for your own text properties by making
    additions to enriched-translations.  Note that the standard
    requires you to name your annotation starting "x-" (as in
    "x-read-only").  Please send me any such additions that you
    think might be of general interest so that I can include them
    in the distribution.

I personally believe that we should make `enriched-translations' into
a defvar, regardless of whether we keep the above text in the Emacs manual.

Sincerely,

Luc.

enriched-translations

[Luc Teirlinck]

I forgot to include a proper subject in my previous message.

Sincerely,

Luc.

Re: (no subject)

[Richard Stallman]

    But `enriched-translations' is defined in enriched.el with a
    def_const_.  This suggest (maybe misleadingly) that the value should
    not be messed with.

Thanks for noticing that.  Please fix that.

    There also is the problem that the text quoted above makes things look
    much simpler than they are.  If one wants to successfully add
    annotations for saving additional text properties, one will have to
    (at least) read through three docstrings, two of which are rather long
    and some parts of which assume at least some familiarity with Elisp
    and with the text/enriched standard.

Could you add xrefs in the doc string for enriched-translations to
point to the other two symbols whose doc strings people need to read?

It might be better to mention this somewhere other than the Emacs Manual,
but there is no logical other place to do it.  I think it is right for the
text in the Emacs manual to be brief and refer people to other sources.

Re: (no subject)

[Luc Teirlinck]

Richard Stallman wrote:
       
       But `enriched-translations' is defined in enriched.el with a
       def_const_.  This suggest (maybe misleadingly) that the value should
       not be messed with.

   Thanks for noticing that.  Please fix that.

Done.

   Could you add xrefs in the doc string for enriched-translations to
   point to the other two symbols whose doc strings people need to read?

The docstring already contains those xrefs.

Sincerely,

Luc.