From: Eli Zaretskii <eliz@gnu.org>
To: Okamsn <okamsn@protonmail.com>
Cc: philipk@posteo.net, emacs-devel@gnu.org
Subject: Re: How to install documentation in sub-directory with Package VC?
Date: Tue, 28 Mar 2023 14:48:26 +0300 [thread overview]
Message-ID: <83fs9p85bp.fsf@gnu.org> (raw)
In-Reply-To: <c9db7e2a-b447-f8b1-d94b-137d7df7b9ff@protonmail.com> (message from Okamsn on Tue, 28 Mar 2023 01:50:04 +0000)
> Date: Tue, 28 Mar 2023 01:50:04 +0000
> From: Okamsn <okamsn@protonmail.com>
> Cc: emacs-devel@gnu.org
>
> I have tried to write a patch doing this (attached).
Thanks.
> +There are two ways for Emacs to learn how and whence to install a
> +package from source. The first way, when supported, is to
> +automatically download the needed information from a package archive
> +(@pxref{Package Archives,,,elisp, The Emacs Lisp Reference Manual}).
> +This is what is done when only specifying the symbol of a package.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Passive voice alert! Could you perhaps rephrase this avoiding the
passive voice?
> +The second way is to specify this information manually in the first
> +argument of @code{package-vc-install}, in the form of
> +@samp{(@var{name} . @var{spec})}. @var{spec} should be a property
This should be @code, not @samp.
> +list using any of the following keys:
> +
> +@itemize @bullet
This should be "@table @code", not @itemize. The result is more
readable. @itemize is for free text, not for systematic description
of several optional features and attributes.
> +@item @code{:branch}
> +The name of the branch to checkout after cloning the directory.
^^^^^^^^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^
Can we make this less Git-specific?
> +@item @code{:lisp-dir}
> +The repository-relative name of the directory to use for loading the
> +Lisp sources, if not the root directory of the repository.
The "if not" part is confusing. I suggest ", which defaults to the
root directory of the repository" instead.
> +@item @code{:main-file}
> +The main file of the project, from which to gather package metadata.
> +If not given, the assumed default is the package name with ".el"
> +appended to it.
I'd drop the "assumed" part. It adds nothing to the description.
> +@item @code{:doc}
> +The repository-relative name of the documentation file from which to
> +build an Info file. This can be a TexInfo file or an Org file.
^^
Two spaces there, please. Also, the spelling is "Texinfo", not
"TexInfo".
> +@item @code{:vc-backend}
> +The VC backend to use for cloning the package. If omitted,
A cross-reference here to the place where VC backends are described
would be good.
> +the process will fall back onto the archive default or onto
> +the value of @code{package-vc-default-backend}.
What does it mean to "fall back onto the archive default"?
> + `:doc' (string)
> + The documentation file from which to build an Info file.
> + This can be a TexInfo file or an Org file.
^^^^^^^
Spelling again.
prev parent reply other threads:[~2023-03-28 11:48 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-03-14 3:13 How to install documentation in sub-directory with Package VC? Okamsn
2023-03-14 15:56 ` Philip Kaludercic
2023-03-15 9:41 ` Philip Kaludercic
2023-03-16 1:37 ` Okamsn
2023-03-16 8:44 ` Philip Kaludercic
2023-03-28 1:50 ` Okamsn
2023-03-28 7:41 ` Philip Kaludercic
2023-04-02 0:41 ` Okamsn
2023-04-02 5:24 ` Eli Zaretskii
2023-04-05 7:30 ` Philip Kaludercic
2023-04-06 3:52 ` Okamsn
2023-04-06 15:42 ` Philip Kaludercic
2023-04-10 13:39 ` Philip Kaludercic
2023-04-12 0:04 ` Okamsn
2023-04-12 7:27 ` Philip Kaludercic
2023-04-12 7:41 ` Eli Zaretskii
2023-04-12 7:48 ` Philip Kaludercic
2023-04-07 21:46 ` Jonas Bernoulli
2023-04-08 8:36 ` Philip Kaludercic
2023-04-09 18:39 ` Jonas Bernoulli
2023-04-09 20:44 ` Lynn Winebarger
2023-04-09 21:55 ` Philip Kaludercic
2023-03-28 11:48 ` Eli Zaretskii [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83fs9p85bp.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=okamsn@protonmail.com \
--cc=philipk@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).