Hi Philip,

let me try to come up with 2 new patches once I split the README. I will
also add the ignored files to .elpaignore and test it again there.

Roman

On Mon, Apr 29, 2024, 20:24 Philip Kaludercic <philipk@posteo.net> wrote:

> Roman Scherer <roman.scherer@burningswell.com> writes:
>
> > Hi Philip,
> >
> > ok, perfect. Thanks for your help on this!
>
> Can you just tell me what the names of the manual files will be?  Also,
> if possible it would be better if you could track the files to ingore
> inside the repository using a .elpaignore file (I just noticed the
> patches now, so I didn't see what you were proposing until now).
>
> > 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
> >>>
> >
>
> --
>         Philip Kaludercic on peregrine
>