From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Boruch Baum Newsgroups: gmane.emacs.devel Subject: Re: ~Make emacs friendlier: package documentation [POC CODE INCLUDED] Date: Sun, 18 Oct 2020 12:20:30 -0400 Message-ID: <20201018162030.h7s4tqch3sprssxu@E15-2016.optimum.net> 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> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="14748"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: NeoMutt/20180716 Cc: Eli Zaretskii , Stefan Monnier , emacs-devel@gnu.org To: Stefan Kangas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Oct 18 18:24:03 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 1kUBTW-0003ix-C1 for ged-emacs-devel@m.gmane-mx.org; Sun, 18 Oct 2020 18:24:02 +0200 Original-Received: from localhost ([::1]:33404 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kUBTV-000296-0f for ged-emacs-devel@m.gmane-mx.org; Sun, 18 Oct 2020 12:24:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:56966) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kUBQJ-0001J4-IB for emacs-devel@gnu.org; Sun, 18 Oct 2020 12:20:43 -0400 Original-Received: from mout.gmx.net ([212.227.17.20]:59555) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kUBQF-0006rv-8W; Sun, 18 Oct 2020 12:20:42 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1603038034; bh=XKkXh16TpD4KT7Jo3ahAQ+HWG3LzJ82V6+3beh6m3cU=; h=X-UI-Sender-Class:Date:From:To:Cc:Subject:References:In-Reply-To; b=DxbCOZRAd1xujmDaaskDP1J4p75P3SgzzcdfUY1RF8N8LTJU1BH/XzYzfxsJ6XyoO 16l5zdjsVab8mEqgp5TlutDf7ZW6LVfPLtEI810pfA8CUlS2+sXAcnWFZCNr4gYgsr UkVyAWRfJ+yoScwyyXZBIg3LEwtzSI6eVVNS/UEM= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Original-Received: from E15-2016.optimum.net ([72.89.170.172]) by mail.gmx.com (mrgmx105 [212.227.17.174]) with ESMTPSA (Nemesis) id 1MbivG-1jsMpj3ODW-00dIG5; Sun, 18 Oct 2020 18:20:34 +0200 Content-Disposition: inline In-Reply-To: X-Provags-ID: V03:K1:nkQwqtUFMklnLivNPFypYAT4O/0PFXxY172uMZnteJBzTEJaGh7 S8DRsRivV9B2rz1CgnyWyEqIfCGCx5CYq4r/CszL7aLkYaLMNwL1bJ2DGJfDBPTogSZ1BfY n/OLtZkEQQ4Pm8pKvPGbjhUF1Lgk3kNXFhdAHqizeKXtBg1cMXIN4uptRYzPjSrd5jOMcTU 3QBB+uvSb31NnQCFOMWVw== X-UI-Out-Filterresults: notjunk:1;V03:K0:Jd17zQaGtZM=:Bqfvw5Mr7m+4FtcferHLR/ g3y643hflRgAvkTi30Q7Zrv/qxPg63S11HEuaLs4wzWNYnET8zJ7sHnGjc3Ab+RwquvFmTuxH 9N299gEAWgFj219ZTlLc7Jlnv4cHnxHFznDTNWjM0HIMW/a4jtfXCoH4lnNa07i2/FMooX/p2 ovzX06fPMuyVg7kbEpTsMjBL8MHCcHxCLF558Q8A9OfDLo+ZJoh36NqOUXiF5IxVKd7WdeqX7 /dnl2W4Q5DhMGkhlQJ93PMwjE9yfjjm+w4sWhy+qCai6COKCGO4ED+DnqCM7w+Ah5/CwxJKqU CyZtmpXdmsp6sPrMsUmx1ibZQN2hbdxrGZgL+ejkYVWtcFXsz1qc5GpRmdDsRNQCa3316TvX4 pQ72YCTwsy2hiL4mgQIaZM51M+VmtFKYE0HUN3QcFexCDhGyzUb1wIWT2jKoPq5KQDZJIEm5l +YGge/UCTgXNjYJhn0GaW36itjoMnfQMkaeyqZvoAsln0MzO2y7IoYgwWbjN7j6PCJMyYn9N8 D/oFBS+4P80/aZIYQ12btIAxQIdVlsOnQ6GIfxKjqwj6iWcTvG8EDqd7QEQLL3i0PLnbP2H7c 1ZiWmu8KsElR1HaxpY4pFWkfaXglODKpPKsoi3AIvLiVF3LKNecLlQqCrCn5drC+594ws+7zn P+Svt6YWLGES+OTFeFfOs3CFjcKw7+lMLN4qCA5LmE+zrxSD+lo8tmPUelv4F1ypG8RaUE+s8 abWVe+RsCV1clk3TlZ7w2/OnmdYfWQzn0r6JBUFupT/j/op07SKG7LIwpBtC9mBwmOTkOCOc Received-SPF: pass client-ip=212.227.17.20; envelope-from=boruch_baum@gmx.com; helo=mout.gmx.net X-detected-operating-system: by eggs.gnu.org: First seen = 2020/10/18 12:20:37 X-ACL-Warn: Detected OS = Linux 3.11 and newer [fuzzy] X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, 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:258045 Archived-At: On 2020-10-18 08:50, Stefan Kangas wrote: > Boruch Baum writes: > > >> IOW what would be the advantage of adding a link in `C-h P` to your > >> system, instead of just replacing `C-h P` with your system? > > > > IMO: Just losing the heading summary, but that code can be integrated = so > > that nothing would be lost. > > Having tested your code, Thanks. For what packages? It's important to know in order to understand the content of your feedback. > 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 'commentary' section that describe-package presents isn't directly from the 'commentary' section in the elisp file (see, for example, yasnippet). > (I guess that part could be collapsed by default in order to not > overwhelm a user with details?) Yes. Good idea. > It would be great if one could also collapse the "Commentary" section. Do-able. > I would also give it a headline "Description:" using the same font as > "Status:". Don't know if that's possible for org-mode headings... > 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). > Bonus points if we can also add a link to the relevant Info manual, > where there is one. That a good idea, but it's independent of whatever ends up happening with my code submission, so it should be an independent bug report or feature request against package 'describe-package'. > BTW, does this all really need to be based on Org-mode? Technically: of course not. Practically: the entire point of the code submission is exploit the great features of org-mode, and the pre-existing format conventions of the emacs coding standard. > Perhaps one could make it look more polished by rolling a custom > solution here, Ugh. Re-invent yet another wheel? > and I'm not exactly sure what using Org-mode buys us in this case. For starters: Navigation, expansion and collapse of sections. > 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. ??? > - The autoload cookies should probably get a better representation than > just being copied in. ??? > - The doc strings should be passed to `substitute-command-keys' before > display. This one I understand, and is an excellent idea. =2D- hkp://keys.gnupg.net CA45 09B5 5351 7C11 A9D1 7286 0036 9E45 1595 8BC0