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: documentation incorrect for function `define-package'? Date: Fri, 24 Sep 2021 08:01:14 -0700 Message-ID: References: <87bl4iukia.fsf@gmail.com> 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="39826"; mail-complaints-to="usenet@ciao.gmane.io" To: Michelangelo Rodriguez , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Sep 24 17:02:37 2021 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 1mTmii-000A7H-Fu for ged-emacs-devel@m.gmane-mx.org; Fri, 24 Sep 2021 17:02:36 +0200 Original-Received: from localhost ([::1]:48306 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mTmih-0001au-6M for ged-emacs-devel@m.gmane-mx.org; Fri, 24 Sep 2021 11:02:35 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54708) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mTmhW-0000kI-Ll for emacs-devel@gnu.org; Fri, 24 Sep 2021 11:01:22 -0400 Original-Received: from mail-pj1-x1036.google.com ([2607:f8b0:4864:20::1036]:51075) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mTmhR-00085a-D6 for emacs-devel@gnu.org; Fri, 24 Sep 2021 11:01:22 -0400 Original-Received: by mail-pj1-x1036.google.com with SMTP id k23so7194921pji.0 for ; Fri, 24 Sep 2021 08:01:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:in-reply-to:references:mime-version:date:message-id:subject:to; bh=BkvW9569BxlRD16Fu4UNDiDS6LWNQUrXG+eix3ds1CM=; b=bOWIuwHsDaQYxhgo7g6m2lEqMuj4FcTnE1gf6nDba8VwmAD3EPAABgPEorzOK+b9Le QFjsglGttSPfdQCkN1s8lCrB3ba77IRSQCXilKEGJil0o0E94AtiVpmUn1v4LAlcH5rc E1WkRYAki1HrvMg8flxhIyrl+wpKbNvlutHzkLXoQ7ds2XfbnlvKmV0ObH0u4pflvXMC 19VRRDZbveKZRGSvfyv3WiOLctyJ6pb8DG5VCY3n9h+MvwDckgyMggcNWv5+79WP2qTf zYucBHHPI5W5JC8bHHGFjUdqPff9EvX2vfk+Q6xTXMvOF8ffA6ppcprAtnIZXghRq8bB KLXA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:in-reply-to:references:mime-version:date :message-id:subject:to; bh=BkvW9569BxlRD16Fu4UNDiDS6LWNQUrXG+eix3ds1CM=; b=Cw+IaSwm7qGzT4UKA/U4gfYsHvDJ/NTCsfbJoYuwB1dqtb1s3ufUZ8oD8zhWO76rcZ yBSk0gh2jYOuPkWi44ZNPd2zwCnd5L6RA1iCZwJPWvwup7a/aViHbQsCc3QwYVK+VmTo Y++C4FOHvOgBzVhV6ditHkhYL4Ka+hTP6uaTsdYfiRaLifk59iVK8KXsD0b8DC4rxXYh pByb0mkUdkVovqCMGe/Z2cCaHD/aFjGSHGeyYHl8FIW/R+laKLNia4OO32gpLitzq5Z1 0e/O2s/cSh/eO/39DRzQQHpBkPO1oSZH+58U+c4QFqrsN+aCDDvbRMFVAj39E1k0wP8L AlyQ== X-Gm-Message-State: AOAM531wWggbJ0WckTcJlQ/Jo9CL4QtcJOcIjcGSIQ3ulM5OPzMnUWsH yxFNYOwqT8KcOw6xMZdk6S9D0w4lN3NlDkgXjMc= X-Google-Smtp-Source: ABdhPJyb6BKcoJHXdgNef+OGzr3NTdGq8oB6TmSq35Kr/JsgsUxaj2QOmu1GybNmObYBrTiEOYnq+Mcq0KNuwiztGiE= X-Received: by 2002:a17:90a:5583:: with SMTP id c3mr2682077pji.133.1632495675660; Fri, 24 Sep 2021 08:01:15 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Fri, 24 Sep 2021 08:01:14 -0700 In-Reply-To: <87bl4iukia.fsf@gmail.com> Received-SPF: pass client-ip=2607:f8b0:4864:20::1036; envelope-from=stefankangas@gmail.com; helo=mail-pj1-x1036.google.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, 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:275400 Archived-At: Michelangelo Rodriguez writes: > The documentation for `define-package' function says: > EXTRA-PROPERTIES is currently unused. > But, indeed, it's not true. > In order for a multi-package to correctly work, and in particular to > `describe-package' to report correctly information on a multi-package, > it is necessary to specify keywords as :author, :keywords, and so on... > Neither function documentation nor info manual mention that. > Infact, if i specify only library headers containing that information, > describe-package don't report keywords, nor other tags. This is its current definition: (defun define-package ( _name-string _version-string &optional _docstring _requirements &rest _extra-properties) "Define a new package. NAME-STRING is the name of the package, as a string. VERSION-STRING is the version of the package, as a string. DOCSTRING is a short description of the package, a string. REQUIREMENTS is a list of dependencies on other packages. Each requirement is of the form (OTHER-PACKAGE OTHER-VERSION), where OTHER-VERSION is a string. EXTRA-PROPERTIES is currently unused." ;; FIXME: Placeholder! Should we keep it? (error "Don't call me!")) On the one hand, this function is clearly not intended for use. On the other hand, where else do we document the `define-package' list that goes in "foo-pkg.el"? Those definitions look like this, but again this is just data (the "package.el" Commentary section incorrectly says "'PACKAGE-pkg.el' which consists of a *call* to define-package", my emphasis): (define-package "which-key" "20210824.11" "Display available keybindings in popup" '((emacs "24.4")) :commit "4790a14683a2f3e4f72ade197c78e4c0af1cdd4b" :authors '(("Justin Burkett" . "justin@burkett.cc")) :maintainer '("Justin Burkett" . "justin@burkett.cc") :url "https://github.com/justbur/emacs-which-key")