Leading * in docstrings of defcustoms.

Leading * in docstrings of defcustoms.

[Lute Kamstra]

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

  Lute.

Re: Leading * in docstrings of defcustoms.

[Juanma Barranquero]

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

Re: Leading * in docstrings of defcustoms.

[Glenn Morris]

"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...

Re: Leading * in docstrings of defcustoms.

[Juanma Barranquero]

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

Re: Leading * in docstrings of defcustoms.

[Stefan Monnier]

>> 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

RE: Leading * in docstrings of defcustoms.

[Drew Adams]

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.)

Re: Leading * in docstrings of defcustoms.

[Chong Yidong]

"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.

RE: Leading * in docstrings of defcustoms.

[Drew Adams]

> 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.

Re: Leading * in docstrings of defcustoms.

[Chong Yidong]

"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).

Re: Leading * in docstrings of defcustoms.

[Stephen J. Turnbull]

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.

Re: Leading * in docstrings of defcustoms.

[Lute Kamstra]

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.

Re: Leading * in docstrings of defcustoms.

[Lute Kamstra]

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.
> 

Re: Leading * in docstrings of defcustoms.

[Juanma Barranquero]

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