From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.devel Subject: Re: ~Make emacs friendlier: package documentation [POC CODE INCLUDED] Date: Sun, 18 Oct 2020 10:13:17 -0700 Message-ID: References: <20201015190929.gdvx7j2yukcdcoaw@E15-2016.optimum.net> <83pn5jwav0.fsf@gnu.org> <20201015194132.jdn3e2v62vfvh7ju@E15-2016.optimum.net> <83imbawu6y.fsf@gnu.org> <20201016073432.4bmahi4jna2xxayl@E15-2016.optimum.net> <20201018144345.wgrbsivvzuuohbj5@E15-2016.optimum.net> <20201018162030.h7s4tqch3sprssxu@E15-2016.optimum.net> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="21859"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Eli Zaretskii , Stefan Monnier , emacs-devel@gnu.org To: Boruch Baum Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Oct 18 19:14:07 2020 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 1kUCFy-0005YA-5g for ged-emacs-devel@m.gmane-mx.org; Sun, 18 Oct 2020 19:14:06 +0200 Original-Received: from localhost ([::1]:55724 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kUCFx-0006R0-3w for ged-emacs-devel@m.gmane-mx.org; Sun, 18 Oct 2020 13:14:05 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37246) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kUCFF-000604-La for emacs-devel@gnu.org; Sun, 18 Oct 2020 13:13:21 -0400 Original-Received: from mail-ej1-x62f.google.com ([2a00:1450:4864:20::62f]:42044) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kUCFE-0004GB-0r; Sun, 18 Oct 2020 13:13:21 -0400 Original-Received: by mail-ej1-x62f.google.com with SMTP id h24so10621723ejg.9; Sun, 18 Oct 2020 10:13:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:in-reply-to:references:mime-version:date:message-id:subject:to :cc; bh=VT27f5g03zTG7Hm5SLUiyQiQkRYHmmUu0IJMMfM5iQE=; b=J2cPpFkw9o7b4YHomq9OHPwm664KHboLiaWI5hM+/81qfWqztIRoudkTw+O0k72AsO rGf4fvu5LrMzS3glm2yPJBc9TuJqgC3aaqodq/RDRFUztH7xGnEwZSHcLE584/RF5sxh YCV06hI2jgTbCVyji9zF2lem2EkWTz2YzJIxb6x+kn12BOH7IafxibF7x74XFzmw+FXf 1FZhO5PPFZtB4NRtLPRStHuBiEFzETNgG2ul+6Dc/VuklkwKTqeI/VLzeF672pRSGrUI sJUTzSnIkREJdwouyDlkSAcXiSQh/WZjhIyAFYgEKadADT1zYbn7MPlP7oC19Yrb3aiZ 4fqQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:in-reply-to:references:mime-version:date :message-id:subject:to:cc; bh=VT27f5g03zTG7Hm5SLUiyQiQkRYHmmUu0IJMMfM5iQE=; b=jcR4H9bBwfxPwrmeS5jr6muRApY9oF1IRCf1bvESA7NMGXTCgiF7Hn8A6XPUfPgAol Aq/JeICuJnNoB0ATCMWPx5b0nzM3VtG1QRIyz8Zk/Y5Sb0tXRz+9IUpmgKzudhlVbDcE XXqCuWgkiuu6GBJyk6nWGi2xOewxVGX8lsFih47iDQ+dtI4+9gI5JjwdvsW7hibSWk5B GUbQmGIVUkVP0KGkZd1peM/lHfUyRfGdgvSsE38s7g6w95e85A6beZ+DWDr+gV2J3DSx cQTmv5tvKYPkIyfMkiSNdgM8Wis0cwYdLZaB8Vm9wGVmAL5X8Cc1l2WcS7nlF7A2Ae73 zoDA== X-Gm-Message-State: AOAM5314xXsiX26CtTYvOSxDNDRBEzCVVDtHS+8j7yBfMry2GDrNlZ9k INYIFXv5+7Sfg+Zv8FhfC4nmWlnLzn0C62OTgB8= X-Google-Smtp-Source: ABdhPJyP592aIcRx/NHBT1vLza542DJjHqF1zn7a67WvGRV0Gwo3grw29Vp4GcD+OwIz+9nd1joe9BOuI59yvFamVx4= X-Received: by 2002:a17:906:1957:: with SMTP id b23mr13204511eje.312.1603041198153; Sun, 18 Oct 2020 10:13:18 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sun, 18 Oct 2020 10:13:17 -0700 In-Reply-To: <20201018162030.h7s4tqch3sprssxu@E15-2016.optimum.net> Received-SPF: pass client-ip=2a00:1450:4864:20::62f; envelope-from=stefankangas@gmail.com; helo=mail-ej1-x62f.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 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" Xref: news.gmane.io gmane.emacs.devel:258049 Archived-At: Boruch Baum writes: >> Having tested your code, > > Thanks. For what packages? It's important to know in order to understand > the content of your feedback. I tested it on lisp/time.el. >> I agree that we should keep `C-h P' as-is, but extend it with >> everything from the "** Code:" header and down in your code. > > That would lose a lot of information. There could be many > sections/headings above 'code', and it turns out to seem that even the OK, fair enough, so please modify the above to say "everything after the 'Commentary' section". You could just move the sections around. For example, the license could be moved to the end (if it is even necessary in the GPL case). > 'commentary' section that describe-package presents isn't directly from > the 'commentary' section in the elisp file (see, for example, yasnippet). That's because it comes from the package README file instead. >> We would also need to check that this works also for packages that are >> not installed (they don't need to show the full documentation, I don't >> think, but they should at least not be broken ;-). > > My code submission should work as-is on any elisp file that conforms to > the emacs coding standard format. I've tested it for my other recent > code submission - key-assist.el > > OTOH, the converse is not true. describe-package doesn't expose itself > to any elisp file, only recognized packages. Even some features that we > all think of as packages aren't exposed (eg. dired). Yes, so that's the part that would need looking into. >> Perhaps one could make it look more polished by rolling a custom >> solution here, > > Ugh. Re-invent yet another wheel? Not if we can avoid it, but Org-mode is also not a hammer looking for a nail. >> Three more nits: > > For me to make sense of most of what you write below, I need to know at > the very least on what elisp file you encountered the problem, and > helpfully a pointer of where to find it. > >> - I wouldn't show obsolete aliases. > > ??? Run your code on time.el and see that obsolete aliases are there. >> - The autoload cookies should probably get a better representation than >> just being copied in. > > ??? Run your code on time.el and see that the autoload cookies are copied verbatim above the headings. I think they should better be marked in a different way.