特定平台内容

概述

tldr-pages 项目为各种操作系统和平台上的命令行工具提供简化的文档。命令在语法、选项和行为方面通常因平台而异。为了适应这些差异，tldr-pages 按照特定平台组织内容，同时还维护一个共享的“common”（通用）平台，用于跨平台命令。

来源：CONTRIBUTING.md56-82 CLIENT-SPECIFICATION.md18-28

平台目录结构

所有 tldr 页面都组织在主 pages 目录下的平台特定目录中，以及相应的语言特定目录（例如，pages.fr、pages.zh）。只有当某个平台至少有一个页面时，才会创建该平台的目录。

支持的平台

平台目录	操作系统/环境
`common/`	在多个平台中工作方式相似的命令
`android/`	Android
`freebsd/`	FreeBSD
`linux/`	任何 Linux 发行版
`openbsd/`	OpenBSD
`osx/`	macOS (OS X) - 最终将重命名为 `macos/`
`netbsd/`	NetBSD
`sunos/`	SunOS
`windows/`	Windows

来源：CONTRIBUTING.md56-82

平台分配规则

如果一个命令在两个或多个平台上工作方式相似，则应将其放在 common 目录中。
如果一个命令仅在一个平台上可用，则应将其放在该平台的特定目录中。
如果一个命令在多个平台上可用，但在特定平台上有显著差异，则主页面应放在 common 中，并在特定平台的目录中放置一个定制版本。

例如，如果命令 foo 在 macOS、Windows 和 Linux 上可用，但在 Windows 上的功能不同，那么主页面将存储在 common/foo.md 中，而 Windows 特定版本将放在 windows/foo.md 中。

来源：CLIENT-SPECIFICATION.md18-28 contributing-guides/style-guide.md112-118

页面解析算法

当用户请求特定的命令页面时，tldr 客户端会使用标准化的算法来确定显示哪个平台特定的版本。

来源：CLIENT-SPECIFICATION.md146-185

解析步骤

主机平台优先级：客户端首先检查与主机操作系统对应的平台目录中是否存在页面。
通用平台回退：如果主机平台没有页面，客户端会检查 common 平台。
搜索其他平台：如果页面在主机平台或通用平台中都未找到，客户端会搜索其他平台目录。
带警告显示：当显示非主机平台或通用平台的页面时，客户端应显示警告。

例如，如果 Windows 用户请求关于 apt 命令（主要在 Linux 上使用）的信息

检查 windows/apt.md → 未找到
检查 common/apt.md → 未找到
搜索其他平台，找到 linux/apt.md
显示 linux/apt.md 并显示警告，指出它是用于其他平台的

来源：CLIENT-SPECIFICATION.md146-185

平台特定内容工作流程

创建平台特定页面

在向 tldr-pages 存储库贡献新页面时，贡献者需要根据命令在操作系统上的可用性来确定适当的平台目录。

来源：CONTRIBUTING.md56-82 contributing-guides/style-guide.md112-118

平台特定内容的维护

不同的平台可能有指定的维护者，他们专门负责审查和维护特定操作系统的内容。例如，Linux 页面由 GitHub CODEOWNERS 文件中指定的专用贡献者维护。

来源：.github/CODEOWNERS20 MAINTAINERS.md

平台特定内容的样式指南

平台特定语法

在记录特定于平台或具有平台特定行为的命令时，请遵循以下指南：

路径分隔符：使用平台正确的路径分隔符（类 Unix 系统使用 /，Windows 使用 \）。
驱动器字母：对于 Windows，必要时包含驱动器字母。
特殊目录：使用平台适用的特殊目录引用。

例如，在 Windows 页面中

{{path\to\file_or_directory}}

不应使用

{{path/to/file_or_directory}}

PowerShell 特定规则

PowerShell 命令有自己的格式规则。

文件名必须小写，但页面标题应匹配官方大小写（例如，标题为 Invoke-WebRequest，文件名则为 invoke-webrequest.md）。
在示例中使用正确的 PowerShell 命令大小写（Command-Name 而非 command-name）。
记录 PowerShell 版本之间的兼容性差异。

来源：contributing-guides/style-guide.md88-108 contributing-guides/style-guide.md412-422

平台特定页面示例

带平台变体的通用页面

一些命令在多个平台上可用，但行为差异很大。在这些情况下：

基础版本存储在 common 目录中。
平台特定变体存储在其各自的平台目录中。

在此示例中，cd 命令在 Windows 上的工作方式与类 Unix 系统不同，因此 common/cd.md 中有一个基础版本，而 windows/cd.md 中有一个 Windows 特定版本。