Philip Kaludercic writes: > Roman Scherer 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 writes: >> >>> Roman Scherer writes: >>> >>>> Hi Philip, >>>> >>>> Philip Kaludercic 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 >>>> >>