If an item provides TargetPath, preserve it as relative to the PackFolder

Add doc note on TargetPath and how it's used (also with Link), and make sure we don't overwrite the provided one by the user if it's present.

Author: kzu

README.md

@@ -79,6 +79,8 @@ If the item does **not** provide a *PackagePath*, and *Pack* is not *false*, the
 
 a. **PackFolder**: typically one of the [built-in package folders](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Packaging/PackagingConstants.cs#L19), such as *build*, *lib*, etc.
 b. **FrameworkSpecific**: *true*/*false*, determines whether the project's target framework is used when building the final *PackagePath*.
+c. **TargetPath**: optional PackFolder-relative path for the item. If not provided, the relative path of the item in the project (or its *Link* metadata) is used.
+
 
 When an item specifies *FrameworkSpecific=true*, the project's target framework is added to the final package path, such as `lib\netstandard2.0\My.dll`. Since the package folder itself typically determines whether it contains framework-specific files or not, the *FrameworkSpecific* value has sensible defaults so you don't have to specify it unless you wnat to override it. The [default values from NuGetizer.props](src/NuGetizer.Tasks/NuGetizer.props) are:
 

src/NuGetizer.Tasks/NuGetizer.Inference.targets

@@ -114,6 +114,7 @@ Copyright (c) .NET Foundation. All rights reserved.
       <PackagePath />
       <PackFolder />
       <ShouldPack />
+      <TargetPath />
     </InferenceCandidate>
   </ItemDefinitionGroup>
 
@@ -173,10 +174,13 @@ Copyright (c) .NET Foundation. All rights reserved.
       <InferenceCandidate>
         <ShouldPack Condition="('%(Pack)' == 'true' or '%(PackagePath)' != '' or '%(PackFolder)' != '') and '%(Pack)' != 'false'">true</ShouldPack>
       </InferenceCandidate>
+      <!-- No need to re-assign a target path if the item already provides one. We do this because otherwise the built-in AssignTargetPath 
+           task unconditionally re-sets it. See https://github.com/dotnet/msbuild/blob/master/src/Tasks/AssignTargetPath.cs -->
+      <_InferenceCandidateWithTargetPath Include="@(InferenceCandidate)" Condition="'%(ShouldPack)' == 'true' and '%(TargetPath)' != ''" />
     </ItemGroup>
 
     <AssignTargetPath Files="@(InferenceCandidate)" RootFolder="$(MSBuildProjectDirectory)"
-                      Condition="'%(ShouldPack)' == 'true'">
+                      Condition="'%(ShouldPack)' == 'true' and '%(TargetPath)' == ''">
       <Output TaskParameter="AssignedFiles" ItemName="_InferenceCandidateWithTargetPath" />
     </AssignTargetPath>
 

src/NuGetizer.Tests/Scenarios/given_a_library_with_content/content-with-targetpath.txt

@@ -46,6 +46,7 @@
     <Content Include="relative\content-copy.txt" CopyToOutputDirectory="PreserveNewest" />
     <None Include="none-with-packagepath.txt" PackagePath="build\%(Filename)%(Extension)" />
     <Content Include="content-with-packagepath.txt" PackagePath="build\%(Filename)%(Extension)" />
+    <Content Include="content-with-targetpath.txt" Pack="true" TargetPath="relative\docs\%(Filename)%(Extension)" />
     <None Include="non-existent-file.txt" Pack="true" />
   </ItemGroup>
 	<Target Name="RemoveContent" Condition="'$(RemoveContent)' == 'true'" BeforeTargets="GetPackageContents">

src/NuGetizer.Tests/Scenarios/given_a_library_with_content/library_with_content.csproj

@@ -366,6 +366,23 @@ public void content_with_package_path_is_included_even_with_pack_content_false()
             }));
         }
 
+        [Fact]
+        public void content_with_target_path_is_included_relative_to_pack_folder()
+        {
+            var result = Builder.BuildScenario(nameof(given_a_library_with_content), new
+            {
+                PackageId = "ContentPackage",
+                PackContent = "false"
+            });
+
+            result.AssertSuccess(output);
+
+            Assert.Contains(result.Items, item => item.Matches(new
+            {
+                PackagePath = @"contentFiles\any\monoandroid51\relative\docs\content-with-targetpath.txt",
+            }));
+        }
+
         #endregion
 
         #region None scenarios