Re: Documentation: Adding playlist files to playlist buffer

[Yoni Rabkin]

Scarlett McAllister <her@scarlettmcallister.com> writes:

> A fair point. I see an entry under basic commands that says:
>
>>  -- Function: emms-play-playlist playlist
>>      A source for the M3u or PLS playlist format from the file PLAYLIST.
>>  -- Function: emms-add-playlist playlist
>>      A source for the M3u or PLS playlist format from the file PLAYLIST.
>
> I agree that it would not be good to duplicate a function's
> entry. However, I'm not sure how I would improve the existing
> documentation for the function. For me, anyways, the improvement comes
> from adding the function to the relevant context, i.e.: the chapter on
> playlists. But perhaps I'm the only one who missed the existing
> function when reading the manual, and so this would be of little
> benefit for others.

I apologize for not being clearer. I reread my own response and would
have been confused by it as well; sorry about that.

I was referring specifically to the duplication of the "@defun ... @end
defun", which would generate duplicate "-- Function: emms-play-playlist
..."  entries.

It still makes perfect sense to reference commands in context. Perhaps
with a "@kbd{M-x emms-play-playlist}", or similar?

> On 2023-03-06 13:18, Yoni Rabkin wrote:
>> Scarlett McAllister <mail@scarlettmcallister.com> writes:
>>
>>> Hello! I have a teeny documentation patch to share. It took me a while
>>> to figure out how to get a saved playlist's contents back into a
>>> buffer. So this small note should hopefully avoid similar time sinks
>>> by other newbies by making mention of the correct function in the
>>> manual!
>>>
>>>> @defun emms-play-playlist file
>>>> Add files from a playlist file to the current playlist buffer.
>>>>
>>>> diff --git a/doc/emms.texinfo b/doc/emms.texinfo
>>>> index da9aee2..9762aea 100644
>>>> --- a/doc/emms.texinfo
>>>> +++ b/doc/emms.texinfo
>>>> @@ -946,6 +946,9 @@ Store the current playlist to FILE as the type
>>>> FORMAT.  The default
>>>>   format is specified by @var{emms-source-playlist-default-format}.
>>>>   @end defun
>>>>
>>>> +@defun emms-play-playlist file
>>>> +Add files from a playlist file to the current playlist buffer.
>> Thank you for this. However, I wouldn't want to introduce duplicate
>> entries for a function in the manual. Would be better perhaps to modify
>> and improve the existing manual entry for `emms-play-playlist'?
>>
>

-- 
   "Cut your own wood and it will warm you twice"