[docs] Remove out-of-date docs, improve header standardization. #24456
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
JackBoosY
added
category:documentation
| In the case of Boost, it is unlikely that a user requires all of the 140+ Boost libraries in their project. For the sake of convenience, vcpkg splits Boost into multiple sub-packages broken down to individual libraries. By doing so, users can limit the subset of Boost libraries that they depend on. | ||
|
|
||
| If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package. | ||
| If a user wants to install all of the Boost libraries available in vcpkg, they can do so by installing the `boost` meta-package. |
There was a problem hiding this comment.
How about merge these 2 paragraphs into:
In the case of Boost, it is unlikely that all 140+ Boost libraries are required. vcpkg splits Boost into its individual libraries. For convenience, the boost meta-package can used to install them all.
There was a problem hiding this comment.
See my below comment.
| **What is a meta-package?** | ||
| In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform (like the old OpenSSL port did), to allow for multiple versions to exist in the vcpkg registry at the same time (OpenCV), or to conveniently install/uninstall a catalog of related packages (Boost and Qt). | ||
| **What is a meta-package?** | ||
| In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform or to conveniently install/uninstall a catalog of related packages (Boost and Qt). |
There was a problem hiding this comment.
| In vcpkg we call meta-packages to ports that by themselves don't install anything but that instead forward installation to another port or ports. The reasons for these meta-packages to exist are plenty: to install different versions of a library depending on platform or to conveniently install/uninstall a catalog of related packages (Boost and Qt). | |
| In vcpkg we call ports that don't install anything but forward installation to other port(s) *meta-packages*. Meta-packages: | |
| * allow installation of different versions of a library depending on platform | |
| * conveniently install/uninstall a catalog of related packages (as demonstrated by `boost` and `qt`) |
I'm not sure we should be talking about different "versions" here?
(I suggested the bulleted list because I think 'reasons are plenty' just makes it longer without really adding things. Just say what it's for.)
There was a problem hiding this comment.
See my below comment.
|
|
||
| ### Step 1: Create a new branch | ||
| As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a Git commit in the vcpkg repository's history. Then it stands to reason, that if you want to customize the baseline you should be able to create a new commit with said custom baseline. | ||
| As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the Microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline. |
There was a problem hiding this comment.
| As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the Microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline. | |
| As described in the versioning documentation. The value that goes in `"builtin-baseline"` is a git commit in the microsoft/vcpkg repository's history. If you want to customize the baseline and have control over the vcpkg instance, you can create a new commit with said custom baseline. |
I believe the git organization is canonically lowercase?
There was a problem hiding this comment.
I've lowercased it, but we have an enormous number of mentions that are uppercased; this should be addressed mechanically in a separate PR.
|
|
||
| Let's start by creating a new branch to hold our modified baseline. | ||
| Let's start by creating a new branch to hold our modified baseline. |
There was a problem hiding this comment.
These 2 trailing spaces were forcing a line break between this line and the next one. Was eliminating that the intent?
There was a problem hiding this comment.
No, thanks for catching this. I've added a hard break.
| @@ -1,10 +1,12 @@ | |||
| # Overlay triplets example | |||
|
|
|||
| ## Building dynamic libraries on Linux | |||
| `vcpkg` comes with many useful officially supported configurations in the box, including dynamic and static libraries for Windows as well as static libraries for MacOS and Linux. There are also a large number of community-supported triplets available, such as Emscripten or Android. | |||
There was a problem hiding this comment.
I'm not sure I like this added paragraph; if we're selling triplets the concept IMO that should be in the doc talking about what triplets are rather than repeated in a sample?
There was a problem hiding this comment.
I have reverted changes to this file to better scope this PR.
|
I agree that the existing documentation needs an enormous amount of rewording, but I am trying to scope this PR to:
I would like to avoid adding any more wording changes to this PR. If any existing ones are controversial, I will revert them and addressing them can be delayed until a more involved pass is performed. |
ras0219-msft
force-pushed
the
dev/roschuma/docs
branch
from
6a3fea6 to
aa0db09
Compare
ras0219-msft
force-pushed
the
dev/roschuma/docs
branch
from
aa0db09 to
6a3fea6
Compare
I also trimmed trailing whitespace from docs/examples/modify-baseline-to-pin-old-boost.md since I was making semantic edits anyway.
As part of this PR, I've audited all non-helper documentation for mentions of feature flags and experimental behavior to ensure all behavior is correctly categorized.