Auto merge of #14684 - sourcefrog:package-help, r=weihanglo

docs: More information on what is and isn't included by cargo package

<!-- homu-ignore:start -->
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:

* If this is your first contribution, read "Cargo Contribution Guide" first:
  https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to review.
* If your idea is large and needs feedback from the community, read how:
  https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
  https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to generate docs:
  https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its title.
* It's ok to use the CI resources to test your PR, but please don't abuse them.
-->

### What does this PR try to resolve?

Add more detail to `cargo package` explaining what is and isn't included.

This doesn't add the feature requested by #11203 (shipping symlinks) but it does at least make it more clear that it's not supported.

### How should we test and review this PR?

Docs only change.

I wrote this by reading [src/cargo/sources/path.rs](https://github.com/rust-lang/cargo/blob/82c489f1c612096c2dffc48a4091d21af4b8e046/src/cargo/sources/path.rs), in addition to my observations of cargo behavior, so it might be helpful for reviewers to check the new docs against the code.

Author: bors

src/doc/man/cargo-package.md

@@ -32,6 +32,10 @@ stored in the `target/package` directory. This performs the following steps:
     - A `.cargo_vcs_info.json` file is included that contains information
       about the current VCS checkout hash if available, as well as a flag if the
       worktree is dirty.
+    - Symlinks are flattened to their target files.
+    - Files and directories are included or excluded based on rules mentioned in
+      [the `[include]` and `[exclude]` fields](../reference/manifest.html#the-exclude-and-include-fields).
+
 3. Extract the `.crate` file and build it to verify it can build.
     - This will rebuild your package from scratch to ensure that it can be
       built from a pristine state. The `--no-verify` flag can be used to skip

src/doc/man/generated_txt/cargo-package.txt

@@ -14,11 +14,13 @@ DESCRIPTION
        following steps:
 
        1. Load and check the current workspace, performing some basic checks.
+
           o  Path dependencies are not allowed unless they have a version key.
              Cargo will ignore the path key for dependencies in published
              packages. dev-dependencies do not have this restriction.
 
        2. Create the compressed .crate file.
+
           o  The original Cargo.toml file is rewritten and normalized.
 
           o  [patch], [replace], and [workspace] sections are removed from the
@@ -32,7 +34,14 @@ DESCRIPTION
              about the current VCS checkout hash if available, as well as a
              flag if the worktree is dirty.
 
+          o  Symlinks are flattened to their target files.
+
+          o  Files and directories are included or excluded based on rules
+             mentioned in the [include] and [exclude] fields
+             <https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields>.
+
        3. Extract the .crate file and build it to verify it can build.
+
           o  This will rebuild your package from scratch to ensure that it can
              be built from a pristine state. The --no-verify flag can be used
              to skip this step.

src/doc/src/commands/cargo-package.md

@@ -27,6 +27,10 @@ stored in the `target/package` directory. This performs the following steps:
     - A `.cargo_vcs_info.json` file is included that contains information
       about the current VCS checkout hash if available, as well as a flag if the
       worktree is dirty.
+    - Symlinks are flattened to their target files.
+    - Files and directories are included or excluded based on rules mentioned in
+      [the `[include]` and `[exclude]` fields](../reference/manifest.html#the-exclude-and-include-fields).
+
 3. Extract the `.crate` file and build it to verify it can build.
     - This will rebuild your package from scratch to ensure that it can be
       built from a pristine state. The `--no-verify` flag can be used to skip

src/etc/man/cargo-package.1

@@ -45,6 +45,15 @@ packaged lock file if the \fB\-\-locked\fR flag is used.
 about the current VCS checkout hash if available, as well as a flag if the
 worktree is dirty.
 .RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Symlinks are flattened to their target files.
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'Files and directories are included or excluded based on rules mentioned in
+\fIthe \f(BI[include]\fI and \f(BI[exclude]\fI fields\fR <https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-exclude\-and\-include\-fields>\&.
+.RE
 .RE
 .sp
 .RS 4