From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eshel Yaron Newsgroups: gmane.emacs.devel Subject: Re: Documentation by function beyond elisp Date: Sat, 11 Mar 2023 21:04:21 +0200 Message-ID: References: <4Rj4EZNhsddTjHzoYuycFzMpjNTJjjwmdDcAgyuMcSFsBePmPBTtlxUENKjf4W1xOVcdDeZIFfHJxD9uRInDURGMdmiIPJ_BB1BvgQ8ylJI=@protonmail.com> <87lek5ynm6.fsf@localhost> <877cvnr2fc.fsf@gmail.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="36972"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: Yuri Khan , Ihor Radchenko , goncholden , "emacs-devel@gnu.org" To: Augusto Stoffel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Mar 11 20:05:05 2023 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 1pb4Wf-0009Nj-NU for ged-emacs-devel@m.gmane-mx.org; Sat, 11 Mar 2023 20:05:05 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pb4W8-0002Bq-B1; Sat, 11 Mar 2023 14:04:32 -0500 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 1pb4W6-0002BR-Oy for emacs-devel@gnu.org; Sat, 11 Mar 2023 14:04:30 -0500 Original-Received: from mail.eshelyaron.com ([107.175.124.16] helo=eshelyaron.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pb4W4-0008UO-VV for emacs-devel@gnu.org; Sat, 11 Mar 2023 14:04:30 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=eshelyaron.com; s=mail; t=1678561467; bh=XQ/++aF+kgzW7vivfyscvJdLFlDfAHsGWivQG5dk3rk=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=IjFe3fSui+r1V/HZ5/Hi1/P2QrrgoS6rZMmx+Rp/bGU33eYR7UR0G8GtuvqkqaAlu /Wxol8oLVCqnwc7/XTEHeDTQ7NofIO9cirVIwG0TXhsVfkDF31FMbnH9sF5Jwm70rZ xSAThLjV0KzkVxj6hqTh6Z8uqaMyztwGO7rpGs9H1ceuJH9AJukclaKxpIRkO7BqH8 An5yaTa1XjoDwtnnoR7chGOEi8O+Y2sz7UuWFpMfnhNnQoYaf1SxT7ycPxzVUAoTbD fhIDUV5YsI1C/bmL7ZRnPrMJhHDOdmlykTQafBQNPluHgJ56fQMk6kr9OuodMh3RdX 3bGakKTGkrTPA== In-Reply-To: <877cvnr2fc.fsf@gmail.com> (Augusto Stoffel's message of "Sat, 11 Mar 2023 11:46:15 +0100") Received-SPF: pass client-ip=107.175.124.16; envelope-from=me@eshelyaron.com; helo=eshelyaron.com 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, SPF_HELO_PASS=-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:304335 Archived-At: Augusto Stoffel writes: > On Fri, 10 Mar 2023 at 16:50, Eshel Yaron wrote: > >> IMO ElDoc and Help and two pretty different features, each with its own >> use and purpose. >> Eglot integrates with ElDoc but not with Help AFAIU, > > Right, the LSP protocol doesn't have an interface for anything like > `C-h o'. You only get information on the symbol at point. Seems so, that strikes me as an unfortunate limitation of the protocol as language servers are surely in a good position to provide this information. >> but language-specific packages can (and should!) integrate with both of >> these facilities. Emacs lets package authors reuse the Help UI pretty >> easily. For example, my package sweeprolog.el (for working with >> SWI-Prolog code) provides both ElDoc integration and a command >> sweeprolog-describe-predicate that works much like describe-predicate, >> it uses the help.el interface to show a proper *Help* buffer with the >> documentation of a given Prolog predicate. > > The generic Emacs way to provide this functionality is the Info symbol > lookup command `C-h S'. I'm not sure I agree that Info and similar manuals solve the same problem as *Help* buffers. During development I think that Help is much more useful, as its aware of the current state of your project and environment. One obvious benefit is the ability to jump to the source code corresponding to what you're getting help for with `s`. > If your language doesn't have an Info manual you may have better luck > with the `devdocs' package (which I mention as a shameless but > pertinent plug). Great stuff :) I actually just installed devdocs a few days ago to access the PostgreSQL docs and it worked very well. > Out of curiosity: apart from the issue of availability of documentation > in different formats, is there any prolog-specific logic in > sweeprolog-describe-predicate? Some, yes. Basically it uses SWI-Prolog's own documentation system to get the current documentation for the given predicate in HTML format, then it uses SHR with some custom shr-external-rendering-functions to create nicely formatted text for the *Help* buffer. That's the gist of it. It also links to the source location of the predicate and lists some properties of the predicate like whether its exported or not.