Referencing variables beginning with an asterisk in docstrings broken?

Referencing variables beginning with an asterisk in docstrings broken?

[Nathanael Schweers]

I wanted to include a reference to a global (dynamic) variable in one of
my docstrings.  According to the info page “(elisp) Documentation Tips”
one merely has to reference the variable in question between the
quotation marks ‘ and ’.

As far as I can tell so far, this works, as long as the variable does
not start with an asterisk.  I.e. ‘varname’ works, so does ‘varname*’,
yet not ‘*varname’.  Hence, ‘*varname*’ also does not work.

I’d like to adhere to the Common Lisp convention of naming special
variables in my elisp code, yet if I do so, I cannot seem to reference
them in docstrings.

Is this behaviour a bug?

Best Regards,
Nathanael Schweers
-- 

Referencing variables beginning with an asterisk in docstrings broken?

[Nathanael Schweers]

I wanted to include a reference to a global (dynamic) variable in one of
my docstrings.  According to the info page “(elisp) Documentation Tips”
one merely has to reference the variable in question between the
quotation marks ‘ and ’.

As far as I can tell so far, this works, as long as the variable does
not start with an asterisk.  I.e. ‘varname’ works, so does ‘varname*’,
yet not ‘*varname’.  Hence, ‘*varname*’ also does not work.

I’d like to adhere to the Common Lisp convention of naming special
variables in my elisp code, yet if I do so, I cannot seem to reference
them in docstrings.

Is this behaviour a bug?

Best Regards,
Nathanael Schweers
-- 

RE: Referencing variables beginning with an asterisk in docstrings broken?

[Drew Adams]

> I wanted to include a reference to a global (dynamic) variable in one of
> my docstrings.  According to the info page “(elisp) Documentation Tips”
> one merely has to reference the variable in question between the
> quotation marks ‘ and ’.
> 
> As far as I can tell so far, this works, as long as the variable does
> not start with an asterisk.  I.e. ‘varname’ works, so does ‘varname*’,
> yet not ‘*varname’.  Hence, ‘*varname*’ also does not work.
> 
> I’d like to adhere to the Common Lisp convention of naming special
> variables in my elisp code, yet if I do so, I cannot seem to reference
> them in docstrings.
> 
> Is this behaviour a bug?

Sure sounds like a bug to me.

Re: Referencing variables beginning with an asterisk in docstrings broken?

[Stefan Monnier]

> I’d like to adhere to the Common Lisp convention of naming special
> variables in my elisp code, yet if I do so, I cannot seem to reference
> them in docstrings.
> Is this behaviour a bug?

Probably a bug, but do note that Elisp is not Common-Lisp, so I strongly
recommend you follow the Elisp convention of using a "<pkg>-" prefix
instead of using asterisks for global variables.


        Stefan

Re: Referencing variables beginning with an asterisk in docstrings broken?

[Nathanael Schweers]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I’d like to adhere to the Common Lisp convention of naming special
>> variables in my elisp code, yet if I do so, I cannot seem to reference
>> them in docstrings.
>> Is this behaviour a bug?
>
> Probably a bug, but do note that Elisp is not Common-Lisp, so I strongly
> recommend you follow the Elisp convention of using a "<pkg>-" prefix
> instead of using asterisks for global variables.
>
>
>         Stefan
>
>

I did both.  I also filed a bug, but it seems that this is because of
some heuristic to prevent too many false positives.  I guess I’ll either
change my naming, or just live with it.  Currently I use
*prefix/public-var*, but I guess prefix/*public-var* might be even
better.

Nathanael

-- 

Re: Referencing variables beginning with an asterisk in docstrings broken?

[Stefan Monnier]

> I did both.  I also filed a bug, but it seems that this is because of
> some heuristic to prevent too many false positives.  I guess I’ll either
> change my naming, or just live with it.  Currently I use
> *prefix/public-var*, but I guess prefix/*public-var* might be even
> better.

the prefix/ already says that it's a global/dynamic var, so the
asterisks are just added noise at that point.


        Stefan