updates build-tool documentation (#8829)

Path based API was deprecated in Swift 6.0 - this maps to related work
to update it to a URL based mechanism, and matches the output from the
build-tool-plugin generated content.

resolves #8820 
Please merge after #8801 

### Motivation:

Related to the issue
#8820, and
matching the PR #8801, this updates the documentation to reflect
upcoming changes to the initialized template and updates the build tool
documentation to reflect the post-Swift 6.0 URL based API.

### Modifications:

Revised documentation to use template content from #8801 

### Result:

API documentation reflects URL based API, not Path based API

Author: heckj

Sources/PackageManagerDocs/Documentation.docc/Plugins/WritingBuildToolPlugin.md

@@ -123,24 +123,37 @@ struct MyPlugin: BuildToolPlugin {
 
   func createBuildCommands(context: PluginContext, 
                            target: Target) throws -> [Command] {
-    guard let target = target.sourceModule else { return [] }
-    let inputFiles = target.sourceFiles.filter(
-      { $0.path.extension == "dat" }
-    )
-    return try inputFiles.map {
-      let inputFile = $0
-      let inputPath = inputFile.path
-      let outputName = inputPath.stem + ".swift"
-      let outputPath = context.pluginWorkDirectory.appending(outputName)
-      return .buildCommand(
-          displayName: "Generating \(outputName) from \(inputPath.lastComponent)",
-          executable: try context.tool(named: "SomeTool").path,
-          arguments: [ "--verbose", "\(inputPath)", "\(outputPath)" ],
-          inputFiles: [ inputPath, ],
-          outputFiles: [ outputPath ]
-      )
+    // This plugin only runs for package targets that can have source files.
+    guard let sourceFiles = target.sourceModule?.sourceFiles else { return [] }
+
+    // Find the code generator tool to run (replace this with the actual one).
+    let generatorTool = try context.tool(named: "my-code-generator")
+
+    // Construct a build command for each source file with a particular suffix.
+    return sourceFiles.map(\.url).compactMap {
+        createBuildCommand(for: $0, in: context.pluginWorkDirectoryURL, with: generatorTool.url)
     }
   }
+
+  func createBuildCommand(for inputPath: URL,
+                          in outputDirectoryPath: URL,
+                          with generatorToolPath: URL) -> Command? {
+    // Skip any file that doesn't have the extension we're looking for
+    // (replace this with the actual one).
+    guard inputPath.pathExtension == "my-input-suffix" else { return .none }
+
+    // Return a command that will run during the build to generate the output file.
+    let inputName = inputPath.lastPathComponent
+    let outputName = inputPath.deletingPathExtension().lastPathComponent + ".swift"
+    let outputPath = outputDirectoryPath.appendingPathComponent(outputName)
+    return .buildCommand(
+        displayName: "Generating \(outputName) from \(inputName)",
+        executable: generatorToolPath,
+        arguments: ["\(inputPath)", "-o", "\(outputPath)"],
+        inputFiles: [inputPath],
+        outputFiles: [outputPath]
+    )
+  }
 }
 ```
 
@@ -163,9 +176,11 @@ struct MyBuildToolPlugin: BuildToolPlugin {
     // This example configures `sometool` to write to a 
     // "GeneratedFiles" directory in the plugin work directory 
     // (which is unique for each plugin and target).
-    let outputDir = context.pluginWorkDirectory.appending("GeneratedFiles")
-    try FileManager.default.createDirectory(atPath: outputDir.string,
-          withIntermediateDirectories: true)
+    let outputDir = context.pluginWorkDirectoryURL
+        .appendingPathComponent("GeneratedFiles")
+    try FileManager.default.createDirectory(
+        at: outputDir,
+        withIntermediateDirectories: true)
 
     // Return a command to run `sometool` as a prebuild command. 
     // It runs before every build and generates source files 
@@ -217,26 +232,24 @@ In order to write a plugin that works with packages in every environment, and th
 For example:
 
 ```swift
-import PackagePlugin
-
-@main
-struct MyCommandPlugin: CommandPlugin {
-    /// This entry point is called when operating on a Swift package.
-    func performCommand(context: PluginContext,
-                        arguments: [String]) throws {
-        debugPrint(context)
-    }
-}
-
 #if canImport(XcodeProjectPlugin)
 import XcodeProjectPlugin
 
 extension MyCommandPlugin: XcodeCommandPlugin {
-    /// This entry point is called when operating on an Xcode project.
-    func performCommand(context: XcodePluginContext, 
-                        arguments: [String]) throws {
-        debugPrint(context)
+
+  // Entry point for creating build commands for targets in Xcode projects.
+  func createBuildCommands(context: XcodePluginContext,
+                           target: XcodeTarget) throws -> [Command] {
+    // Find the code generator tool to run (replace this with the actual one).
+    let generatorTool = try context.tool(named: "my-code-generator")
+
+    // Construct a build command for each source file with a particular suffix.
+    return target.inputFiles.map(\.url).compactMap {
+        createBuildCommand(for: $0,
+                           in: context.pluginWorkDirectoryURL,
+                           with: generatorTool.url)
     }
+  }
 }
 #endif
 ```