[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: ELPA commit freeze
From: |
Dmitry Gutov |
Subject: |
Re: ELPA commit freeze |
Date: |
Sat, 24 Aug 2013 04:16:28 +0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130803 Thunderbird/17.0.8 |
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?
- Re: ELPA commit freeze, (continued)
- Re: ELPA commit freeze, Dmitry Gutov, 2013/08/21
- Re: ELPA commit freeze, Stefan Monnier, 2013/08/21
- Re: ELPA commit freeze, Dmitry Gutov, 2013/08/22
- Re: ELPA commit freeze, Stefan Monnier, 2013/08/22
- Re: ELPA commit freeze, Dmitry Gutov, 2013/08/22
- Re: ELPA commit freeze, Stefan Monnier, 2013/08/22
- Re: ELPA commit freeze, Dmitry Gutov, 2013/08/22
- Re: ELPA commit freeze, Stefan Monnier, 2013/08/23
- Re: ELPA commit freeze, Dmitry Gutov, 2013/08/23
- Re: ELPA commit freeze, Stefan Monnier, 2013/08/23
- Re: ELPA commit freeze,
Dmitry Gutov <=
Re: ELPA commit freeze, Donald Curtis, 2013/08/23