all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Leading * in docstrings of defcustoms.
@ 2008-11-22 19:31 Lute Kamstra
  2008-11-22 22:00 ` Juanma Barranquero
  0 siblings, 1 reply; 13+ messages in thread
From: Lute Kamstra @ 2008-11-22 19:31 UTC (permalink / raw)
  To: emacs-devel

Is it OK if I remove the leading * of all defcustom docstrings that have
one?

  Lute.




^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-22 19:31 Leading * in docstrings of defcustoms Lute Kamstra
@ 2008-11-22 22:00 ` Juanma Barranquero
  2008-11-24  7:52   ` Glenn Morris
  0 siblings, 1 reply; 13+ messages in thread
From: Juanma Barranquero @ 2008-11-22 22:00 UTC (permalink / raw)
  To: Lute Kamstra; +Cc: emacs-devel

On Sat, Nov 22, 2008 at 20:31, Lute Kamstra
<Lute.Kamstra.lists@xs4all.nl> wrote:

> Is it OK if I remove the leading * of all defcustom docstrings that have
> one?

It should be OK for packages that are not independently maintained
outside of Emacs (like org, tramp, etc.).

But such a large scale change is likely to piss off people with many
local changes in their workspaces.

  Juanma




^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-22 22:00 ` Juanma Barranquero
@ 2008-11-24  7:52   ` Glenn Morris
  2008-11-24  8:31     ` Juanma Barranquero
                       ` (2 more replies)
  0 siblings, 3 replies; 13+ messages in thread
From: Glenn Morris @ 2008-11-24  7:52 UTC (permalink / raw)
  To: Juanma Barranquero; +Cc: Lute Kamstra, emacs-devel

"Juanma Barranquero" wrote:

> It should be OK for packages that are not independently maintained
> outside of Emacs (like org, tramp, etc.).

I was going to say, why should that make a difference - they must all
have come up with ways to do "automatic" syncs by now, or gone crazy.
But in light of recent events, maybe not! :)

> But such a large scale change is likely to piss off people with many
> local changes in their workspaces.

Only if it causes conflicts. I doubt there are many people with lots
of uncommitted changes to doc-strings (or close by).

I'd like to see the "*"s removed. And if it were done when 'tis done,
then 'twere well it were done quickly...




^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-24  7:52   ` Glenn Morris
@ 2008-11-24  8:31     ` Juanma Barranquero
  2008-11-24 16:02     ` Stefan Monnier
  2008-11-25  5:50     ` Lute Kamstra
  2 siblings, 0 replies; 13+ messages in thread
From: Juanma Barranquero @ 2008-11-24  8:31 UTC (permalink / raw)
  To: Glenn Morris; +Cc: Lute Kamstra, emacs-devel

On Mon, Nov 24, 2008 at 08:52, Glenn Morris <rgm@gnu.org> wrote:

> I was going to say, why should that make a difference - they must all
> have come up with ways to do "automatic" syncs by now, or gone crazy.
> But in light of recent events, maybe not! :)

No, definitely not. :-)

> Only if it causes conflicts. I doubt there are many people with lots
> of uncommitted changes to doc-strings (or close by).

The problem there is that "Close by" can be anything...

  Juanma




^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-24  7:52   ` Glenn Morris
  2008-11-24  8:31     ` Juanma Barranquero
@ 2008-11-24 16:02     ` Stefan Monnier
  2008-11-24 16:55       ` Drew Adams
  2008-11-24 17:48       ` Stephen J. Turnbull
  2008-11-25  5:50     ` Lute Kamstra
  2 siblings, 2 replies; 13+ messages in thread
From: Stefan Monnier @ 2008-11-24 16:02 UTC (permalink / raw)
  To: Glenn Morris; +Cc: Juanma Barranquero, Lute Kamstra, emacs-devel

>> It should be OK for packages that are not independently maintained
>> outside of Emacs (like org, tramp, etc.).
> I was going to say, why should that make a difference - they must all

IIUC the problem is not just one of syncing (tho it sadly appears it's
also a problem), but that the * does make a difference in older versions
of Emacs and maybe also under XEmacs.


        Stefan




^ permalink raw reply	[flat|nested] 13+ messages in thread

* RE: Leading * in docstrings of defcustoms.
  2008-11-24 16:02     ` Stefan Monnier
@ 2008-11-24 16:55       ` Drew Adams
  2008-11-24 20:36         ` Chong Yidong
  2008-11-24 17:48       ` Stephen J. Turnbull
  1 sibling, 1 reply; 13+ messages in thread
From: Drew Adams @ 2008-11-24 16:55 UTC (permalink / raw)
  To: 'Stefan Monnier', 'Glenn Morris'
  Cc: 'Juanma Barranquero', 'Lute Kamstra', emacs-devel

If you do remove `*' from defcustoms, please also update the manuals
accordingly.

BTW (just curious - no need to divert the thread, but if someone has a quick
answer, great):

Why is it that `*' should be removed from defcustoms? Is it simply because they
don't need it? (If so, that's OK; just wondering if there is some additional
reason.)





^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-24 16:02     ` Stefan Monnier
  2008-11-24 16:55       ` Drew Adams
@ 2008-11-24 17:48       ` Stephen J. Turnbull
  1 sibling, 0 replies; 13+ messages in thread
From: Stephen J. Turnbull @ 2008-11-24 17:48 UTC (permalink / raw)
  To: Stefan Monnier
  Cc: Glenn Morris, emacs-devel, Lute Kamstra, Juanma Barranquero

Stefan Monnier writes:
 > >> It should be OK for packages that are not independently maintained
 > >> outside of Emacs (like org, tramp, etc.).
 > > I was going to say, why should that make a difference - they must all
 > 
 > IIUC the problem is not just one of syncing (tho it sadly appears it's
 > also a problem), but that the * does make a difference in older versions
 > of Emacs and maybe also under XEmacs.

AFAIK usage of the * is very inconsistent in XEmacs.  XEmacs tends not
to make a clear distinction between user variables and internal
variables in any case.  I don't think you need to worry about XEmacs.




^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-24 16:55       ` Drew Adams
@ 2008-11-24 20:36         ` Chong Yidong
  2008-11-24 22:43           ` Drew Adams
  0 siblings, 1 reply; 13+ messages in thread
From: Chong Yidong @ 2008-11-24 20:36 UTC (permalink / raw)
  To: Drew Adams
  Cc: 'Glenn Morris', emacs-devel, 'Stefan Monnier',
	'Lute Kamstra', 'Juanma Barranquero'

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

> If you do remove `*' from defcustoms, please also update the manuals
> accordingly.

They should already be omitted, or strongly deprecated, in the manuals.
For example, the Variable Definitions node in the Lisp manual says

  There is no need to start [the docstring] with a `*', because
  `defcustom' automatically marks `option' as a "user option"

If you find a spot in the manual that still follows the old convention,
please let us know.

> Why is it that `*' should be removed from defcustoms? Is it simply
> because they don't need it?

Yes.




^ permalink raw reply	[flat|nested] 13+ messages in thread

* RE: Leading * in docstrings of defcustoms.
  2008-11-24 20:36         ` Chong Yidong
@ 2008-11-24 22:43           ` Drew Adams
  2008-11-24 23:21             ` Chong Yidong
  0 siblings, 1 reply; 13+ messages in thread
From: Drew Adams @ 2008-11-24 22:43 UTC (permalink / raw)
  To: 'Chong Yidong'
  Cc: 'Glenn Morris', emacs-devel, 'Stefan Monnier',
	'Lute Kamstra', 'Juanma Barranquero'

> They should already be omitted, or strongly deprecated, in 
> the manuals. For example, the Variable Definitions node in
> the Lisp manual says
> 
>   There is no need to start [the docstring] with a `*', because
>   `defcustom' automatically marks `option' as a "user option"
> 
> If you find a spot in the manual that still follows the old 
> convention, please let us know.

Elisp manual nodes:

* Defining Variables

  If the variable is a user option that users would want to set
  interactively, you should use `*' as the first character of
                 ^^^^^^^^^^^^^^^^^^
  DOC-STRING.  This lets users set the variable conveniently using
  the `set-variable' command.  Note that you should nearly always
  use `defcustom' instead of `defvar' to define these variables, so
  that users can use `M-x customize' and related commands to set
  them.  *Note Customization::.

  ...

  User option variables are distinguished from other variables either
  though being declared using `defcustom'(1) or by the first
  character of their `variable-documentation' property.  If the
  property exists and is a string, and its first character is `*',
  then the variable is a user option.  Aliases of user options are
  also user options.

While this "if" is true, and nothing here claims the "only if" case, it's easy
to misread that text to also think the "only if" case applies, that is, that if
a symbol has property `variable-documentation' then `*' is _required_ for a
variable to be a user option.

* Accessing Documentation

  goal-column     Option
  *Semipermanent goal column for vertical motion, as set by ...

  The asterisk `*' as the first character of a variable's doc string,
  as shown above for the `goal-column' variable, means that it is a user
  option; see the description of `defvar' in *Note Defining Variables::.

Again, depending on what is understood by "means", one can read this as saying
that `*' is necessary if you want the variable to be a user option. Especially
considering that `goal-column' is a defcustom, this text should perhaps be
removed or updated.






^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-24 22:43           ` Drew Adams
@ 2008-11-24 23:21             ` Chong Yidong
  0 siblings, 0 replies; 13+ messages in thread
From: Chong Yidong @ 2008-11-24 23:21 UTC (permalink / raw)
  To: Drew Adams
  Cc: 'Glenn Morris', emacs-devel, 'Stefan Monnier',
	'Lute Kamstra', 'Juanma Barranquero'

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

> Elisp manual nodes:
>
> * Defining Variables
>
>   If the variable is a user option that users would want to set
>   interactively, you should use `*' as the first character of
>                  ^^^^^^^^^^^^^^^^^^
>
> While this "if" is true, and nothing here claims the "only if" case,
> it's easy to misread that text

Agreed.  I reworded this paragraph to make it clearer.

> * Accessing Documentation
>
>   goal-column     Option
>   *Semipermanent goal column for vertical motion, as set by ...
>
>   The asterisk `*' as the first character of a variable's doc string,
>   as shown above for the `goal-column' variable, means that it is a
>   user option; see the description of `defvar' in *Note Defining
>   Variables::.
>
> Again, depending on what is understood by "means", one can read this
> as saying that `*' is necessary if you want the variable to be a user
> option.

The goal-column docstring doesn't have the asterisk anymore, anyway.
I've updated the text accordingly.

Thanks for the catch(es).




^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-24  7:52   ` Glenn Morris
  2008-11-24  8:31     ` Juanma Barranquero
  2008-11-24 16:02     ` Stefan Monnier
@ 2008-11-25  5:50     ` Lute Kamstra
  2008-11-28 12:48       ` Lute Kamstra
  2 siblings, 1 reply; 13+ messages in thread
From: Lute Kamstra @ 2008-11-25  5:50 UTC (permalink / raw)
  To: Glenn Morris; +Cc: Juanma Barranquero, emacs-devel

Glenn Morris <rgm@gnu.org> writes:

> "Juanma Barranquero" wrote:
>
>> It should be OK for packages that are not independently maintained
>> outside of Emacs (like org, tramp, etc.).
>
> I was going to say, why should that make a difference - they must all
> have come up with ways to do "automatic" syncs by now, or gone crazy.
> But in light of recent events, maybe not! :)

(Unfortunately, I don't read emacs-devel actively enough to know what
recent events you are referring to to.)

Is there a list of lisp files that are maintained outside of Emacs?  If
not, could someone compile it and put it in admin/?

>> But such a large scale change is likely to piss off people with many
>> local changes in their workspaces.
>
> Only if it causes conflicts. I doubt there are many people with lots
> of uncommitted changes to doc-strings (or close by).
>
> I'd like to see the "*"s removed. And if it were done when 'tis done,
> then 'twere well it were done quickly...

I think any merge conflict involving a removed * is easily resolved by
hand.

  Lute.




^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-25  5:50     ` Lute Kamstra
@ 2008-11-28 12:48       ` Lute Kamstra
  2008-11-28 12:58         ` Juanma Barranquero
  0 siblings, 1 reply; 13+ messages in thread
From: Lute Kamstra @ 2008-11-28 12:48 UTC (permalink / raw)
  To: Glenn Morris; +Cc: Juanma Barranquero, emacs-devel

Lute Kamstra <Lute.Kamstra.lists@xs4all.nl> writes:

[...]

> Is there a list of lisp files that are maintained outside of Emacs?  If
> not, could someone compile it and put it in admin/?

I'll start admin/external-lisp.txt.

[...]

> I think any merge conflict involving a removed * is easily resolved by
> hand.

I've prepared the change below.  Does anyone see problematic files in
that list?  I haven't changed speedbar.el, as I recall that file is
maintained outside Emacs.

  Lute.


Index: lisp/ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/lisp/ChangeLog,v
retrieving revision 1.14875
diff -r1.14875 ChangeLog
0a1,103
> 2008-11-28  Lute Kamstra  <lute@gnu.org>
> 
> 	* align.el:
> 	* allout.el:
> 	* apropos.el:
> 	* arc-mode.el:
> 	* autoinsert.el:
> 	* avoid.el:
> 	* battery.el:
> 	* bookmark.el:
> 	* buff-menu.el:
> 	* calculator.el:
> 	* chistory.el:
> 	* cmuscheme.el:
> 	* comint.el:
> 	* compare-w.el:
> 	* dabbrev.el:
> 	* delim-col.el:
> 	* desktop.el:
> 	* diff-mode.el:
> 	* diff.el:
> 	* dired-aux.el:
> 	* dired-x.el:
> 	* dired.el:
> 	* dos-vars.el:
> 	* ediff-diff.el:
> 	* ediff-help.el:
> 	* ediff-init.el:
> 	* ediff-merg.el:
> 	* ediff-mult.el:
> 	* ediff-ptch.el:
> 	* ediff-vers.el:
> 	* ediff-wind.el:
> 	* ediff.el:
> 	* emerge.el:
> 	* facemenu.el:
> 	* faces.el:
> 	* ffap.el:
> 	* filecache.el:
> 	* find-dired.el:
> 	* font-core.el:
> 	* font-lock.el:
> 	* forms.el:
> 	* fringe.el:
> 	* help-at-pt.el:
> 	* hippie-exp.el:
> 	* ido.el:
> 	* image-file.el:
> 	* imenu.el:
> 	* indent.el:
> 	* info.el:
> 	* isearchb.el:
> 	* iswitchb.el:
> 	* jit-lock.el:
> 	* jka-compr.el:
> 	* log-edit.el:
> 	* lpr.el:
> 	* ls-lisp.el:
> 	* man.el:
> 	* menu-bar.el:
> 	* midnight.el:
> 	* mouse-sel.el:
> 	* mouse.el:
> 	* msb.el:
> 	* outline.el:
> 	* paren.el:
> 	* pcmpl-cvs.el:
> 	* pcmpl-gnu.el:
> 	* pcomplete.el:
> 	* pcvs-info.el:
> 	* pcvs-parse.el:
> 	* printing.el:
> 	* ps-mule.el:
> 	* ps-print.el:
> 	* replace.el:
> 	* ruler-mode.el:
> 	* saveplace.el:
> 	* sb-image.el:
> 	* scroll-bar.el:
> 	* sha1.el:
> 	* shadowfile.el:
> 	* shell.el:
> 	* sort.el:
> 	* strokes.el:
> 	* tempo.el:
> 	* term.el:
> 	* terminal.el:
> 	* time-stamp.el:
> 	* time.el:
> 	* tree-widget.el:
> 	* type-break.el:
> 	* vc-cvs.el:
> 	* vc-hg.el:
> 	* vc-mcvs.el:
> 	* vc-rcs.el:
> 	* vc-sccs.el:
> 	* vc.el:
> 	* view.el:
> 	* w32-vars.el:
> 	* whitespace.el:
> 	* wid-edit.el: Remove leading * from docstrings of defcustoms,
> 	deffaces, defconsts, and defuns.
> 





^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Leading * in docstrings of defcustoms.
  2008-11-28 12:48       ` Lute Kamstra
@ 2008-11-28 12:58         ` Juanma Barranquero
  0 siblings, 0 replies; 13+ messages in thread
From: Juanma Barranquero @ 2008-11-28 12:58 UTC (permalink / raw)
  To: Lute Kamstra; +Cc: Glenn Morris, emacs-devel

On Fri, Nov 28, 2008 at 13:48, Lute Kamstra
<Lute.Kamstra.lists@xs4all.nl> wrote:

> Does anyone see problematic files in
> that list?

>       * calculator.el:

This is maintained at

  http://www.barzilay.org/misc/calculator.el

and I think it's quite up-to-date.

>       * delim-col.el:
>       * printing.el:
>       * ps-mule.el:
>       * ps-print.el:
>       * whitespace.el:

For these, ask Vinicius. I know he maintains some of them outside
Emacs (or used to do so).

  Juanma




^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2008-11-28 12:58 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2008-11-22 19:31 Leading * in docstrings of defcustoms Lute Kamstra
2008-11-22 22:00 ` Juanma Barranquero
2008-11-24  7:52   ` Glenn Morris
2008-11-24  8:31     ` Juanma Barranquero
2008-11-24 16:02     ` Stefan Monnier
2008-11-24 16:55       ` Drew Adams
2008-11-24 20:36         ` Chong Yidong
2008-11-24 22:43           ` Drew Adams
2008-11-24 23:21             ` Chong Yidong
2008-11-24 17:48       ` Stephen J. Turnbull
2008-11-25  5:50     ` Lute Kamstra
2008-11-28 12:48       ` Lute Kamstra
2008-11-28 12:58         ` Juanma Barranquero

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.