From: Dmitry Gutov <dgutov@yandex.ru>
To: Stefan Monnier <monnier@IRO.UMontreal.CA>
Cc: emacs-devel@gnu.org
Subject: Re: ELPA commit freeze
Date: Sat, 24 Aug 2013 04:16:28 +0300 [thread overview]
Message-ID: <5218096C.5030403@yandex.ru> (raw)
In-Reply-To: <jwvr4dka26n.fsf-monnier+emacs@gnu.org>
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?
next prev parent reply other threads:[~2013-08-24 1:16 UTC|newest]
Thread overview: 57+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-08-14 1:10 ELPA commit freeze Stefan Monnier
2013-08-14 7:46 ` Andreas Schwab
2013-08-14 14:42 ` Stefan Monnier
2013-08-15 1:12 ` Xue Fuqiao
2013-08-15 4:18 ` Stefan Monnier
2013-08-15 14:51 ` Eli Zaretskii
2013-08-15 15:29 ` Andreas Schwab
2013-08-15 15:44 ` Eli Zaretskii
2013-08-15 16:04 ` Andreas Schwab
2013-08-15 16:37 ` Eli Zaretskii
2013-08-15 16:42 ` Andreas Schwab
2013-08-15 17:06 ` Eli Zaretskii
2013-08-15 17:16 ` Eli Zaretskii
2013-08-20 18:20 ` Steinar Bang
2013-08-20 18:38 ` Eli Zaretskii
2013-08-21 7:06 ` Steinar Bang
2013-08-15 16:44 ` Stefan Monnier
2013-08-15 19:25 ` Glenn Morris
2013-08-15 20:33 ` Stefan Monnier
2013-08-15 20:41 ` Glenn Morris
2013-08-15 21:31 ` Stefan Monnier
2013-08-15 21:50 ` Glenn Morris
2013-08-14 9:56 ` Dmitry Gutov
2013-08-14 14:43 ` Stefan Monnier
2013-08-17 16:34 ` Dmitry Gutov
2013-08-19 2:39 ` Stefan Monnier
2013-08-19 6:31 ` Dmitry Gutov
2013-08-20 5:16 ` Stefan Monnier
2013-08-20 9:26 ` Dmitry Gutov
2013-08-20 9:40 ` Andreas Schwab
2013-08-20 13:42 ` Dmitry Gutov
2013-08-20 14:08 ` Andreas Schwab
2013-08-20 23:12 ` Dmitry Gutov
2013-08-20 14:45 ` Stefan Monnier
2013-08-20 23:22 ` Dmitry Gutov
2013-08-21 4:21 ` Stefan Monnier
2013-08-21 7:53 ` Dmitry Gutov
2013-08-21 19:56 ` Stefan Monnier
2013-08-21 23:38 ` Dmitry Gutov
2013-08-21 4:23 ` Stefan Monnier
2013-08-21 8:00 ` Dmitry Gutov
2013-08-21 20:00 ` Stefan Monnier
2013-08-21 21:51 ` Dmitry Gutov
2013-08-21 23:56 ` Stefan Monnier
2013-08-22 0:20 ` Dmitry Gutov
2013-08-22 1:55 ` Stefan Monnier
2013-08-22 8:47 ` Dmitry Gutov
2013-08-22 20:35 ` Stefan Monnier
2013-08-22 21:14 ` Dmitry Gutov
2013-08-23 0:51 ` Stefan Monnier
2013-08-23 1:28 ` Dmitry Gutov
2013-08-23 4:12 ` Stefan Monnier
2013-08-23 12:01 ` Dmitry Gutov
2013-08-23 15:05 ` Stefan Monnier
2013-08-24 1:16 ` Dmitry Gutov [this message]
-- strict thread matches above, loose matches on Subject: below --
2013-08-23 17:44 Donald Curtis
2013-08-23 23:04 ` Stefan Monnier
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5218096C.5030403@yandex.ru \
--to=dgutov@yandex.ru \
--cc=emacs-devel@gnu.org \
--cc=monnier@IRO.UMontreal.CA \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).