From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized Date: Mon, 29 Apr 2024 07:46:02 +0000 Message-ID: <87cyq8mx1h.fsf@posteo.net> References: <87h6fnmb4b.fsf@burningswell.com> <87frv6q5t5.fsf@posteo.net> <87o79ttzma.fsf@burningswell.com> <87r0eon1i1.fsf@posteo.net> <87edao1uli.fsf@burningswell.com> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="31629"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org, ahyatt@gmail.com To: Roman Scherer Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Apr 29 09:47:05 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1s1Lj6-00083M-UX for ged-emacs-devel@m.gmane-mx.org; Mon, 29 Apr 2024 09:47:05 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s1LiS-0001g9-20; Mon, 29 Apr 2024 03:46:24 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s1LiJ-0001XJ-8I for emacs-devel@gnu.org; Mon, 29 Apr 2024 03:46:16 -0400 Original-Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s1LiC-0001P2-St for emacs-devel@gnu.org; Mon, 29 Apr 2024 03:46:14 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 88AAC240101 for ; Mon, 29 Apr 2024 09:46:03 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1714376763; bh=gaiITcKKvr8OuAxx5ZUB+wTUF0uT+RQ5DdRzkXYvXJA=; h=From:To:Cc:Subject:OpenPGP:Date:Message-ID:MIME-Version: Content-Type:From; b=KICMFwUrrYQ6nIplpUnLG84SedLm6Ipg6IqpYa9s+PsX4T+FkyDd5nLR1SMhMKA7s TdcOgcTca92ahyf2Hd5hxO1z4Rvcru+ycdZCsamSYf80E8+ID8i+FfLVOtYSTVhRiX XSEUPHq1xn9OTw0DXCOrkEbkzOh30u7F3PvRyJw4N5mCnuEbU5M4o+H6+Hn68mw3Sr Kv+cMe3i54yyLyACEZxUYpYHP8YNQaykPoNm9rpzGfeEya4ietq8Klh5zOeHXSmlr9 HDBPIITicEdslcZfY9JCXwPmIzpdIRDmds5ynoI7DrHHhV7DVxoYClP9bgMS1oi1PR 1kiiDXHDfl/HA== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4VSb3t3QZvz9rxD; Mon, 29 Apr 2024 09:46:02 +0200 (CEST) In-Reply-To: <87edao1uli.fsf@burningswell.com> (Roman Scherer's message of "Mon, 29 Apr 2024 09:44:25 +0200") OpenPGP: id=7126E1DE2F0CE35C770BED01F2C3CC513DB89F66; url="https://keys.openpgp.org/vks/v1/by-fingerprint/7126E1DE2F0CE35C770BED01F2C3CC513DB89F66"; preference=signencrypt Received-SPF: pass client-ip=185.67.36.66; envelope-from=philipk@posteo.net; helo=mout02.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H4=-0.01, RCVD_IN_MSPIKE_WL=-0.01, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:318320 Archived-At: 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 > -- Philip Kaludercic on peregrine