文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载本文以 tldr 仓库中的阿拉伯语别名页面 pages.ar/common/npm-list.md 为核心样本完整拆解 tldr 项目中别名页面alias pages的文档设计它如何通过多语言模板与自动化脚本生成、如何被命名校验与 linter 守护以及使用者如何借助它直达原命令npm ls的完整文档。读完本文你将掌握 tldr 别名页面的结构规范、多语言同步流程与底层脚本实现并能够熟练阅读、使用乃至贡献这类页面。一、关联文档速览一个六行的阿拉伯语别名页npm list在 npm 中并不是一个独立功能而是npm ls的别名。tldr 项目为此在 pages.ar/common/npm-list.md 中单独建立了一张阿拉伯语页面全文仅由三部分组成# npm list هذا الأمر هو اسم مستعار لـ npm ls. - إعرض التوثيقات للأمر الأصلي: tldr npm ls逐行解读第一行以#开头的标题必须与文件名npm-list完全一致文件名要求全小写描述行阿拉伯语说明此命令是npm ls的别名并用反引号标出原命令名npm ls示例区唯一的示例是查看原命令的文档命令为tldr npm ls。这张页面自身不承载命令参数它的全部职责是引导用户去查阅原命令页面。这与 tldr 社区协作的命令行速查表的定位直接相关——当一条命令只是另一条命令的别名时不再重复维护一份参数文档而是通过别名页跳转避免内容重复和版本漂移。二、别名页是什么tldr 文档体系中的一类特殊页面2.1 别名页 vs 普通页面的定位差异tldr 仓库在pages/英文及各pages.xx/翻译目录下存放两类页面普通页面如 pages.en/common/npm-ls.md直接讲解命令的用法、参数与示例别名页面alias pages如 pages.en/common/npm-list.md仅说明本命令是某命令的别名并给出跳转命令。以npm ls的英文原页面对照可以看出普通页面承载的信息密度# npm ls Print installed packages to stdout. More information: https://docs.npmjs.com/cli/npm-ls/. - Print all versions of direct dependencies in the current project to stdout: npm {{[ls|list]}} - Print all installed packages including peer dependencies: npm {{[ls|list]}} {{[-a|--all]}} - Print all globally installed packages: npm {{[ls|list]}} {{[-g|--global]}} - Print dependencies with extended information: npm {{[ls|list]}} {{[-l|--long]}} - Print dependencies in parseable format: npm {{[ls|list]}} {{[-p|--parseable]}} - Print dependencies in JSON format: npm {{[ls|list]}} --json而别名页 pages.en/common/npm-list.md 只有# npm list This command is an alias of npm ls. - View documentation for the original command: tldr npm ls2.2{{[ls|list]}}占位符的意义注意原命令页中{{[ls|list]}}这种写法它并非 npm 的参数而是 tldr 的**选项占位符option placeholder**语法表示用户既可以敲npm ls也可以敲npm list。tldr 客户端在渲染时会据此高亮可替换片段并在支持的环境下让用户自行选择展示短选项还是长选项。这也是为什么项目要单独为npm list建别名页——它是 npm 官方认可的命令写法用户在终端里真的会敲npm list但它的文档主体却在npm ls名下。三、多语言模板机制别名页的骨架从哪来为了让 40 多种语言的别名页保持统一结构仓库在 contributing-guides/translation-templates/alias-pages.md 中集中维护了一套按语言分节的模板。每个小节以### ar、### zh这样的语言标签开头紧随其后是markdown代码块中的完整模板。其中ar阿拉伯语模板与本文的npm list页面逐字对应# example هذا الأمر هو اسم مستعار لـ example. - إعرض التوثيقات للأمر الأصلي: tldr example模板中的example是占位符实际生成页面时会被替换为别名命令名如npm list、原命令名如npm ls以及tldr后的跳转命令。阿拉伯语翻译模板与英语模板在语义上一一对应结构元素英语模板en阿拉伯语模板ar标题# example# example别名说明 This command is an alias ofexample. هذا الأمر هو اسم مستعار لـexample.示例描述- View documentation for the original command:- إعرض التوثيقات للأمر الأصلي:示例命令tldr exampletldr example从仓库现状看npm-list.md的别名页几乎在所有语言目录下都有对应的翻译副本如 pages.zh/common/npm-list.md、pages.ja/common/npm-list.md 等 39 个文件这正是模板机制驱动多语言一页多译的直接体现。四、底层实现set-alias-page.py如何生成与同步别名页模板的落地由脚本 scripts/set-alias-page.py 负责。它从 scripts/_common.py 导入通用工具整体工作流可以概括为三步。4.1 读取模板get_templates()_common.py 中的get_templates(root, alias-pages.md)会解析模板文件扫描以###开头的行作为语言标签提取其下markdown代码块内的文本最终产出一个{语言: 模板字符串}字典。脚本主入口处即通过这行代码加载全部语言模板templates get_templates(root, alias-pages.md)4.2 填充占位符generate_alias_page_content()核心替换逻辑scripts/set-alias-page.py把模板中的example依次替换为三个真实值template_command example result template_content.replace(template_command, page_content.title, 1) # 第一个 example - 标题如 npm list result result.replace(template_command, page_content.original_command, 1) # 第二个 example - 原命令如 npm ls result result.replace(template_command, page_content.documentation_command) # 其余 example - tldr 后的命令三个字段的含义通过prompt_alias_page_info()scripts/set-alias-page.py的交互式向导收集标题默认取文件名原命令original command将出现在此命令是某命令的别名描述中文档命令documentation command将出现在tldr ...跳转行默认与原命令相同。以npm list为例即标题npm list、原命令npm ls、文档命令npm ls。4.3 同步与校验--sync与get_alias_command_in_page()脚本支持两种运行方式单页创建/更新python3 scripts/set-alias-page.py -p common/npm-list.md -l ar通过交互向导写入指定语言页面批量同步python3 scripts/set-alias-page.py -S读取英文pages/下全部别名页再同步到各语言目录-S -l ar则只同步阿拉伯语加-n为 dry-run 预览改动加-s可自动git add暂存。同步时get_alias_command_in_page()scripts/set-alias-page.py会反向解析已有页面提取标题、别名描述行中的原命令反引号内容和tldr行中的文档命令并比对去占位后的模板与现有页面的骨架是否一致stripped_translation_template stripped_translation只有不一致时才重写页面。这套机制保证了模板一旦更新各语言别名页可以被批量对齐这也是阿拉伯语npm list页面能长期保持与模板逐字一致的根本原因。五、规范守护命名校验、样式指南与 lint5.1 文件命名与标题一致性scripts/wrong-filename.py 会扫描所有pages*目录下的.md文件校验文件名与标题是否一致它把文件名去掉.md、把标题去掉#分别做归一化-转空格、小写、折叠空白后比较。npm-list.md的标题恰好是npm list归一化后两者完全一致因此能通过校验。同时该脚本支持消歧后缀例外如just.js对just确保特殊命名不误报。5.2 阿拉伯语样式指南中的别名规范contributing-guides/style-guide.ar.md 的الألقاب别名章节对阿拉伯语别名页给出了明确指导当命令可用别名调用如vim可通过vi调用时应创建别名页指回原命令结构同样为标题 别名说明 tldr跳转。该指南还特别覆盖了 PowerShell 别名的三类情况替代 cmd 命令、仅限 PowerShell 的新别名、与外部程序冲突的别名说明别名页的规则是成体系的而非仅限 npm 一例。5.3 lint 检查scripts/test-tldr-lint.sh 说明了对阿拉伯语目录执行npx tldr-lint --ignore TLDR104,TLDR003,TLDR004,TLDR015 pages.ar其中 TLDR104 与占位符括号规范相关阿拉伯语目录会忽略这些规则以适配其翻译语法。此外 scripts/check-errors.sh 还会全局检查反引号配对、感叹号句式、……/—等字符混用等常见错误——别名页中用于标记命令名的反引号数量必须成对这是每个页面含别名页都必须满足的硬性要求。六、实战使用如何消费这张别名页6.1 通过 tldr 客户端查看在任何支持 tldr 协议的客户端CLI、Web 端、编辑器插件等中输入tldr npm list客户端会命中别名页渲染出阿拉伯语说明并提示原命令为npm ls继续执行tldr npm ls即可看到 pages.en/common/npm-ls.md或按语言优先命中对应翻译展示的完整用法。语言选择通常由客户端的--language/-L参数或系统区域设置决定例如tldr -L ar npm ls可强制查看阿拉伯语版本。6.2 结合原命令页掌握npm list的完整能力尽管别名页本身不列参数但通过跳转到的npm ls页面可以完整掌握npm list的等效用法用途命令列出当前项目的直接依赖及全部版本npm list即npm ls列出包括 peer 依赖在内的所有已装包npm list -a/npm list --all列出全局安装的包npm list -g/npm list --global输出扩展信息依赖树详情npm list -l/npm list --long以可解析格式输出npm list -p/npm list --parseable以 JSON 格式输出npm list --json这正是别名页设计哲学的落点文档只维护一份别名页负责指路原命令页负责讲透从而保证npm list与npm ls永远共享同一套最新文档不会出现两份内容漂移。七、总结以 pages.ar/common/npm-list.md 为代表的别名页是 tldr 项目一命令一页、一页一主题原则下的一种精简化特殊页面。它的完整生命周期由仓库内的四类资产共同支撑模板contributing-guides/translation-templates/alias-pages.md 定义各语言骨架生成/同步scripts/set-alias-page.py 负责填充占位符与批量同步规范约束contributing-guides/style-guide.ar.md 与 scripts/wrong-filename.py 约束措辞与命名质量门禁scripts/test-tldr-lint.sh 与 scripts/check-errors.sh 在 CI 与本地双通道把关。读懂这张六行页面你就同时理解了 tldr 的多语言文档体系、占位符模板机制、自动化脚本工作流和质量保障链条——这也是向 tldr 贡献新别名页或翻译时最值得复用的方法论。赞分享文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载相关推荐tldr 别名页面机制解读以阿拉伯语 clojure → clj 页面为例tldr 别名页面机制解读以阿拉伯语 clojure → clj 页面为例 本篇指南以 tldr 仓库中 pages.ar/common/clojure.md文档教程知识库tldr 别名页机制深度解析以阿拉伯语 rehash 页面为例tldr 别名页机制深度解析以阿拉伯语 rehash 页面为例 rehash 是 tldr简明命令速查手册仓库中典型的 别名页alias page 之文档教程知识库tldr 别名页机制解析以 ubuntu-bug 阿拉伯语页面为例tldr 别名页机制解析以 ubuntu bug 阿拉伯语页面为例 本指南以 tldr 仓库中的 pages.ar/linux/ubuntu bug.md h文档教程知识库上一篇Bevy B0005 运行时警告深入解读字体图集随字号增长的代价与正确的平滑缩放方案下一篇终极指南如何用iptv-checker轻松管理你的IPTV播放列表创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考