Re: Fetching or installing package dev source from VCS: manual style

[Philip Kaludercic]

Richard Stallman <rms@gnu.org> writes:

> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
> [[[ whether defending the US Constitution against all enemies,     ]]]
> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
> The proposed manual text includes several sentences which use passive
> voice and would be shorter in active voice.  Occasionally the use of
> passive voice is best approach, but usually not, so please try making
> them active and see if that makes the text more readable.
>
> Please don't refer to a maintainer, singular, as "them".
> There are many other ways to write that sentence, and some
> don't use a pronoun at all.

Thank you for the input, how do you like this:

--8<---------------cut here---------------start------------->8---
@node Package from Source
@section Package from Source
@cindex package development source
@cindex package upstream source
@cindex package git source @c "git" is not technically correct

  By default @code{package-install} will download a tarball from a
package archive and install the files therein contained.  Most of the
time this is just what you want.  One exception is when you decide to
hack on the source code of a package, and would like to share these
changes with other users.  In that case you usually want to fetch and
work on the upstream source, so that you can prepare a usable patch.

@findex package-vc-install
  One way to do this is to use @code{package-vc-install}, to fetch the
source code for a package directly from source.  The command will also
automatically ensure that all files are byte-compiled and auto-loaded,
just like with a regular package.  Packages installed this way behave
just like any other package.  You can update them using
@code{package-update} or @code{package-update-all} and delete them
again using @code{package-delete}.  They are even displayed in the
regular package listing.

@findex package-report-bug
@findex package-vc-prepare-patch
  With the source checkout, you might want to reproduce a bug against
the current development head or implement a new feature to scratch an
itch.  If the package metadata indicates how to contact the
maintainer, you can use the command @code{package-report-bug} to
report a bug via Email.  This report will include all the user options
that you have customised.  If you have made a change you wish to share
with the maintainers, first commit your changes then use the command
@code{package-vc-prepare-patch} to share it.  @xref{Preparing Patches}.

@findex package-vc-link-directory
@findex package-vc-refresh
  If you maintain your own packages you might want to use a local
checkout instead of cloning a remote repository.  You can do this by
using @code{package-vc-link-directory}, which creates a symbolic link
from the package directory (@pxref{Package Files}) to your checkout
and initialises the code.  Note that you might have to use
@code{package-vc-refresh} to repeat the initialisation and update the
autoloads.
--8<---------------cut here---------------end--------------->8---