[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized
From: |
Roman Scherer |
Subject: |
Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized |
Date: |
Mon, 29 Apr 2024 09:48:54 +0200 |
User-agent: |
mu4e 1.12.4; emacs 29.3 |
Hi Philip,
ok, perfect. Thanks for your help on this!
Roman
Philip Kaludercic <philipk@posteo.net> writes:
> Roman Scherer <roman.scherer@burningswell.com> writes:
>
>> Hi Philip,
>>
>> Philip Kaludercic <philipk@posteo.net> writes:
>>
>>>
>>> The different files have different audiences. I'd say:
>>>
>>> - The README is an introduction to anyone who just checked out a
>>> repository (or found it on some Website), and wants to know what it is
>>> about. It should just be a starting point, linking to other resources
>>> (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
>>> possible.
>>>
>>> - The documentation is for people who have installed a package and want
>>> to know the exact details of how something works or is done. It is
>>> not something that would usually interest someone who hasn't
>>> downloaded and installed a package.
>>>
>>> - The package description (C-h P foo RET) is a brief explanation of what
>>> a package does and provides. It should focus on the questions the
>>> user might have when they first encounter the package:
>>>
>>> * If the name is not indicative, what is the package even about.
>>>
>>> * What is the core functionality and how is it used.
>>>
>>> * Who is the target audience.
>>>
>>> * What are the entry points to the package.
>>>
>>> * What differentiates the package from other similar packages.
>>>
>>> or other questions like these. It should NOT include:
>>>
>>> * A table of contents
>>>
>>> * Installation instructions of any kind (there is a install button in
>>> the package description buffer)
>>>
>>> * Extensive details on how to configure the package
>>>
>>> * Screenshots, as these are currently not displayed
>>>
>>> * Changelog information
>>>
>>> and instead try and to keep it short and simple. It is just a sales
>>> pitch, not a lecture.
>>>
>>> Sadly a number of packages just use the same README.org file for all
>>> these things, confusing the separate audiences. If anything, it is
>>> acceptable to mix the first two, but the third should certainly not
>>> result in a 500+ line buffer (as is currently the case with "plz"). The
>>> easiest way to address the last point is just to use the commentary
>>> section in the main file to generate the description of the package,
>>> which we can configure in elpa.git.
>>
>> Ok, thanks for the explanation. I will then split the README and the
>> manual up. I will do this in the next days.
>
> OK, I can add the packages to elpa.git in the meantime.
>
>> I looked a bit around and will probably do something similar to what
>> Protesilaos does in his packages. This one being an example:
>>
>> https://github.com/protesilaos/ef-themes
>
> If I am not mixing something up, I think I recommended something along
> the lines I wrote above to him as well ^^
>
>> Roman
>>
signature.asc
Description: PGP signature
- Add plz-media-type and plz-event-source to GNU ELPA when stabilized, Roman Scherer, 2024/04/27
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized, Philip Kaludercic, 2024/04/27
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized, Roman Scherer, 2024/04/28
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized, Philip Kaludercic, 2024/04/29
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized, Roman Scherer, 2024/04/29
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized, Philip Kaludercic, 2024/04/29
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized,
Roman Scherer <=
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised, Philip Kaludercic, 2024/04/29
- Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilised, Roman Scherer, 2024/04/29