Re: ELPA commit freeze

[Dmitry Gutov]

On 23.08.2013 18:05, Stefan Monnier wrote:
> > > Currently your README.md contains nothing but a pointer to the webpage.
> > > Clearly, it's not that important to include every one of those elements.
> > When you see a pointer, you just follow it. Having a piece of text there
> > would be different.
>
> Ideally, the README would be a copy of the homepage, tho (and the same
> text would be used for ELPA's and MELPA's readme.txt).

I don't know about ideally, but yes, some projects do that.

> So you only
> need to maintain one text, which is then copied to all places.

It doesn't transfer well to Commentary, though.

> > For example, http://elpa.gnu.org/packages/company.html includes the contents
> > of NEWS.md, which looks great.
> > It could similarly combine README.md and Commentary.
>
> OK, that sounds promising, except I don't know how to combine them.
> Could you define clearly "the division of work" between the two?

One of the patterns I've seen and used is have an overview, feature 
enumeration and brief usage section in README.md, but a more detailed or 
a hands-on usage instructions in Commentary. For example, the latter 
more often lists elisp commands defined by the package, its default 
keybindings, customizable options.

Some rough, inexact examples:

https://github.com/capitaomorte/yasnippet
https://github.com/dgutov/robe
https://github.com/pezra/rspec-mode
https://github.com/ScottyB/ac-js2
https://github.com/dgutov/diff-hl

There's a certain advantage to listing Elisp functions and variables in 
an .el files: when opened in Emacs, they're highlighted the usual way 
given proper markup, you can use the `describe-' commands on them easily 
and jump to their definitions. `describe-function' works well enough in 
markdown-mode too, but any bindings customized for emacs-lisp-mode, won't.

> Or maybe we should just concatenate them and let the authors figure
> out how to divide the work between the two?

Either show Overview (aka README.md), Usage and News under separate 
headings, or add a horizontal menu with these items at the top, so that 
the user only sees one of these at the time.

To make it less prescriptive, we can call the second section/tab 
literally Commentary (so authors can work out the separation of 
information themselves), but I don't have any other suggestions for the 
first section name.

> One other issue is that Commentary does not have any markup, and I'd
> like to use markup more actively (e.g. converting into HTML when
> including it in packages/company.html, and rendering it on-the-fly in
> describe-package).

Since Commentary lives in an .el file, I think it should be an extension 
of the current docstring or comment markup. So we have a way to 
highlight separate symbols, maybe also interpret additionally indented 
blocks of text as code. Lists, similarly to markdown. For subheadings, 
standardize on some scheme with extra leading semicolons. What's 
missing? Links, images?