command_name
项目地址: https://gitcode.com/GitHub_Trending/tl/tldr 简短、精炼的命令描述。 最好一行；必要时可两行。 更多信息：https://example.com/command_name/help/page.
- 命令描述1：
command_name options
- 命令描述2：
command_name options
...
### 页面标题规范
页面标题使用一级Markdown标题（#），必须与命令名称完全匹配。文件名必须为小写，而页面标题可以保持原始大小写格式。
### 描述部分详解
描述部分使用引用块格式（>），包含三个关键要素：
1. **简短描述**：用一句话概括命令的主要功能
2. **补充说明**：必要时提供额外信息
3. **参考链接**：指向官方文档或更多信息的链接
| 组成部分 | 语法要求 | 示例 |
|---------|---------|------|
| 主要描述 | 简短精炼，使用祈使语气 | `> Archiving utility.` |
| 补充说明 | 可选，提供额外上下文 | `> Often combined with a compression method.` |
| 参考链接 | 必须包含，使用标准格式 | `> More information: <https://example.com>.` |
### 示例部分规范
示例部分使用无序列表和代码块的组合，每个示例包含描述和对应的命令：
```markdown
- 创建归档文件并写入目标文件：
`tar cf {{path/to/target.tar}} {{path/to/file1 path/to/file2 ...}}`
占位符语法
tldr页面使用双花括号 {{}} 作为占位符，表示需要用户替换的部分：
特殊页面类型
别名页面
对于命令别名，使用专门的别名页面模板：
# alias_name
> This command is an alias of `original_command`.
- View documentation for the original command:
`tldr original_command`
PowerShell命令页面
PowerShell命令有特殊的命名约定：
| 元素 | 规范要求 | 示例 |
|---|---|---|
| 文件名 | 必须小写 | invoke-webrequest.md |
| 页面标题 | 保持原始大小写 | # Invoke-WebRequest |
| 命令示例 | 保持原始大小写 | Invoke-WebRequest -Uri |
消歧页面
当多个命令同名时，使用消歧页面：
# command_name
> `command_name` can refer to multiple commands with the same name.
- View documentation for command_type1:
`tldr command_name.type1`
- View documentation for command_type2:
`tldr command_name.type2`
语法验证和格式化工具
tldr项目提供了专门的lint工具来验证页面格式：
# 安装tldr-lint
npm install --global tldr-lint
# 验证单个页面
tldr-lint path/to/tldr_page.md
# 验证整个目录
tldr-lint pages/common/
最佳实践指南
- 命令示例数量：每个页面最多包含8个命令示例
- 语言风格：所有描述使用祈使语气
- 占位符使用：对可能造成破坏性操作的命令必须使用占位符
- 平台适配：针对不同平台提供相应的命令变体
- 参考完整性：必须包含官方文档链接
通过遵循这些Markdown模板规范和语法规则，贡献者可以创建出格式统一、内容准确、易于理解的tldr页面，为用户提供最佳的命令行工具使用体验。
占位符使用规范和最佳实践示例
在tldr-pages项目中，占位符是Markdown格式规范的核心组成部分，它们为用户提供了清晰、可替换的命令参数示例。占位符使用双花括号{{}}包裹，旨在表示命令中需要用户根据实际情况替换的部分。
占位符基本语法规范
tldr-pages采用统一的占位符语法标准：
# 基本格式
`command {{placeholder}}`
# 多参数示例
`command {{param1}} {{param2}} {{param3}}`
# 可选参数格式
`command {{[-s|--short]}} {{value}}`
占位符类型分类
根据参数的不同性质，tldr-pages定义了多种占位符类型：
| 占位符类型 | 语法格式 | 使用场景 | 示例 |
|---|---|---|---|
| 路径参数 | {{path/to/file}} | 文件或目录路径 | ls {{path/to/directory}} |
| 多文件参数 | {{file1 file2 ...}} | 多个文件参数 | cp {{source.txt dest.txt}} |
| 数值参数 | {{number}} | 数字值参数 | sleep {{5}} |
| 字符串参数 | {{text}} | 文本字符串 | echo {{"Hello World"}} |
| 选项参数 | {{[-o|--option]}} | 命令行选项 | git commit {{[-m|--message]}} |
| 设备参数 | {{/dev/sdXY}} | 块设备名称 | dd {{/dev/sdX}} {{/dev/sdY}} |
最佳实践示例分析
1. 文件路径占位符
# 单文件操作
`cat {{path/to/file.txt}}`
# 目录操作
`ls {{path/to/directory}}`
# 多文件操作
`cp {{source_file.txt destination_file.txt}}`
2. 数值参数占位符
# 时间参数
`sleep {{seconds}}`
# 端口参数
`ssh {{user}}@{{host}} -p {{port}}`
# 进程ID
`kill {{process_id}}`
3. 选项参数占位符
# 短选项和长选项
`git commit {{[-m|--message]}} {{"commit message"}}`
# 必需选项
`tar {{[-c|--create]}} {{[-f|--file]}} {{archive.tar}} {{files}}`
# 可选选项
`grep {{[-i|--ignore-case]}} {{pattern}} {{file}}`
4. 复杂参数组合
# 混合参数类型
`scp {{[-P|--port]}} {{port}} {{user}}@{{host}}:{{remote_path}} {{local_path}}`
# 正则表达式参数
`grep "{{.*pattern.*}}" {{file}}`
# 格式化字符串
`printf "{{%s\n}}" {{"text"}}`
占位符命名规范
为确保一致性和可读性，占位符命名遵循以下规则：
特殊场景处理
1. 危险操作占位符
对于可能造成数据丢失的危险操作，必须使用占位符：
# 危险：直接指定设备
`dd if=/dev/sda of=/dev/sdb`
# 安全：使用占位符
`dd if={{/dev/sdX}} of={{/dev/sdY}}`
2. 转义字符处理
当占位符内容包含特殊字符时：
# 包含花括号的文本
`echo "{{text with {braces}}}"`
# 包含管道符号
`grep "{{pattern\|alternative}}"`
3. 多平台兼容性
考虑不同平台的路径格式：
# Unix路径
`ls {{/home/user/file.txt}}`
# Windows路径
`dir {{C:\Users\user\file.txt}}`
常见错误与修正
以下表格展示了常见的占位符使用错误及其正确写法：
| 错误示例 | 正确写法 | 问题描述 |
|---|---|---|
command path/to/file | command {{path/to/file}} | 缺少占位符标记 |
command {{file}} {{file}} | command {{file1}} {{file2}} | 重复占位符名称 |
command {{-o}} value | command {{[-o|--option]}} value | 选项格式不规范 |
command /dev/sda1 | command {{/dev/sdXY}} | 使用具体设备名 |
验证与测试
使用tldr-lint工具验证占位符规范：
# 安装lint工具
npm install -g tldr-lint
# 验证单个文件
tldr-lint pages/common/command.md
# 验证所有文件
tldr-lint pages/
通过遵循这些占位符使用规范和最佳实践，可以确保tldr-pages的命令示例既清晰易懂又安全可靠，为用户提供高质量的命令行使用指导。
子命令页面创建和引用机制解析
在tldr-pages项目中，子命令页面的创建和引用机制是一个精心设计的系统，它确保了复杂命令行工具（如Git、Docker等）能够以结构化和用户友好的方式呈现。这一机制不仅简化了用户的学习曲线，还为贡献者提供了清晰的贡献指南。
子命令页面的命名规范
tldr-pages采用统一的命名约定来处理子命令页面。当命令行工具使用子命令结构时，每个子命令都需要创建独立的Markdown文件，命名格式为：
主命令-子命令.md
例如，Git的子命令页面命名如下：
这种命名策略的优势在于：
- 清晰的层级关系：文件名直观地反映了命令的层级结构
- 易于检索：用户和贡献者都能快速找到特定子命令的文档
- 自动化处理：tldr客户端能够自动解析这种命名模式
子命令页面的基本结构
每个子命令页面都遵循标准的tldr格式，但专注于特定子命令的功能。以git-commit.md为例：
# git commit
> Record changes to the repository.
> More information: <https://git-scm.com/docs/git-commit>.
- Commit staged changes with a message:
`git commit -m "{{message}}"`
- Commit staged changes and sign with GPG key:
`git commit -S -m "{{message}}"`
- Commit all changes (including unstaged) with a message:
`git commit -a -m "{{message}}"`
- Update the last commit by adding staged changes and changing the message:
`git commit --amend`
- Commit only specific (already staged) files:
`git commit {{path/to/file1}} {{path/to/file2}} -m "{{message}}"`
主命令页面的引用机制
主命令页面（如git.md）承担着重要的导航功能，它通过多种方式引用子命令页面：
1. 描述性引用
在主命令的描述部分明确指出哪些子命令有独立的文档：
# git
> Distributed version control system.
> Some subcommands such as `commit`, `add`, `branch`, `switch`, `push`, etc. have their own usage documentation.
2. 示例式引用
通过具体的tldr命令示例引导用户查看子命令文档：
- View documentation for creating commits:
`tldr git-commit`
- View documentation for managing branches:
`tldr git-branch`
3. See also引用
使用标准的"See also"模板来关联相关命令：
See also: `git-add`, `git-commit`, `git-push`.
引用机制的技术实现
tldr-pages的引用系统基于简单的Markdown语法，但背后有着精心的设计考虑：
| 引用类型 | 语法格式 | 使用场景 | 优势 |
|---|---|---|---|
| 描述性引用 | Some subcommands such as \command`...` | 主命令页面顶部描述 | 提供整体概览 |
| 示例式引用 | tldr command-subcommand | 具体操作示例 | 直接可执行的指导 |
| See also引用 | See also: \command1`, `command2`.` | 页面底部关联 | 建立命令网络 |
子命令页面的创建流程
创建新的子命令页面需要遵循特定的贡献流程：
最佳实践和注意事项
在创建和引用子命令页面时，需要注意以下最佳实践：
- 一致性：确保所有子命令页面的格式和风格保持一致
- 完整性：主命令页面应该引用所有可用的子命令页面
- 准确性：引用链接必须指向实际存在的页面
- 简洁性：避免过度引用，只引用最相关和常用的子命令
实际应用案例
让我们通过一个具体的例子来说明这个机制的实际应用。假设我们要为docker container命令创建子命令页面：
# docker-container
> Manage Docker containers.
> Some subcommands such as `run`, `start`, `stop`, `rm` have their own usage documentation.
> More information: <https://docs.docker.com/engine/reference/commandline/container/>.
- View documentation for running containers:
`tldr docker-container-run`
- View documentation for removing containers:
`tldr docker-container-rm`
- List all containers:
`docker container ls --all`
- Inspect a specific container:
`docker container inspect {{container_name}}`
相应的子命令页面docker-container-run.md：
# docker container run
> Run a command in a new Docker container.
> More information: <https://docs.docker.com/engine/reference/commandline/run/>.
- Run a command in a new container and remove it after exit:
`docker container run --rm {{image_name}} {{command}}`
- Run a container in detached mode and publish ports:
`docker container run -d -p {{host_port}}:{{container_port}} {{image_name}}`
- Run a container with environment variables:
`docker container run -e "{{variable}}={{value}}" {{image_name}}`
- Run a container with mounted volumes:
`docker container run -v {{host_path}}:{{container_path}} {{image_name}}`
这种结构化的方法确保了用户能够轻松地在相关命令之间导航，同时保持了每个页面的专注性和简洁性。
贡献流程和代码审查标准说明
tldr-pages 项目采用严谨而友好的贡献流程，确保每个提交都经过充分审查，同时保持社区的高效协作。本节将详细介绍从提交到合并的完整流程以及代码审查的具体标准。
贡献流程概述
整个贡献流程遵循清晰的步骤，从本地测试到最终合并，每个环节都有明确的要求：
本地测试与验证
在提交PR之前，贡献者必须使用 tldr-lint 工具进行本地语法检查：
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
