From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: ELPA commit freeze Date: Sat, 24 Aug 2013 04:16:28 +0300 Message-ID: <5218096C.5030403@yandex.ru> References: <5211BBC8.40408@yandex.ru> <52133662.1000900@yandex.ru> <5213FA1C.3080700@yandex.ru> <52147393.9070509@yandex.ru> <5215364A.9000605@yandex.ru> <52155933.4080509@yandex.ru> <5215D018.70308@yandex.ru> <52167F22.3020501@yandex.ru> <5216BADA.3080200@yandex.ru> <52174EFD.7070908@yandex.ru> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1377307005 31214 80.91.229.3 (24 Aug 2013 01:16:45 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 24 Aug 2013 01:16:45 +0000 (UTC) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Aug 24 03:16:49 2013 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VD2TA-0006LU-PX for ged-emacs-devel@m.gmane.org; Sat, 24 Aug 2013 03:16:49 +0200 Original-Received: from localhost ([::1]:39303 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VD2TA-0004ts-Ac for ged-emacs-devel@m.gmane.org; Fri, 23 Aug 2013 21:16:48 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54205) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VD2Sz-0004sa-Pz for emacs-devel@gnu.org; Fri, 23 Aug 2013 21:16:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VD2Su-0005z6-RW for emacs-devel@gnu.org; Fri, 23 Aug 2013 21:16:37 -0400 Original-Received: from mail-ee0-x229.google.com ([2a00:1450:4013:c00::229]:61332) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VD2Su-0005z0-Jf for emacs-devel@gnu.org; Fri, 23 Aug 2013 21:16:32 -0400 Original-Received: by mail-ee0-f41.google.com with SMTP id d17so576649eek.14 for ; Fri, 23 Aug 2013 18:16:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:message-id:date:from:user-agent:mime-version:to:cc:subject :references:in-reply-to:content-type:content-transfer-encoding; bh=dVu26DwfMF79GrcA6zz9pxr2Q+9xu5fKAj7BtE7Ueq4=; b=ASaePmkGUtrIRz65K1ERwV2ySe23JtiGjCQNsX1fKFBXB5itW9PMQM6zea9uksTQKm Fiyy9d9ySpKnsLHUH/lS7iuw+OGx6JN3gAMkrJ4A6efd0JPf9Xnn+RivTMYnzF7sYafy LCk/77cvpxIB4aEs7To05KMhagiRraUYVnFbYB9YFIs5QG5TEn/d1fS75pBlULOwc+O3 B5EY4GfdjYbFCZ1/XLyyw0DguoFiO6LUyzJTtiM1nMSiQTt28krLVi6dO9pJbbsmgAGc zSbcp/WmQqAidnlrG3am0zkNHBdch1XBdCJUQJPTxZOuRwiR107iktiI+gKJ/6CGlMTd DK6g== X-Received: by 10.14.210.8 with SMTP id t8mr3229364eeo.39.1377306991913; Fri, 23 Aug 2013 18:16:31 -0700 (PDT) Original-Received: from [192.168.10.2] (62-118-214.netrun.cytanet.com.cy. [62.228.118.214]) by mx.google.com with ESMTPSA id a6sm3320124eei.10.1969.12.31.16.00.00 (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Fri, 23 Aug 2013 18:16:30 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130803 Thunderbird/17.0.8 In-Reply-To: X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:4013:c00::229 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:163000 Archived-At: 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?