Hi Philip, ok, perfect. Thanks for your help on this! 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 >>