文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载导读本文围绕仓库根目录下的 CLIENT-SPECIFICATION.md 展开系统讲解 tldr-pages 官方客户端Client必须遵循的行为规范——包括标准化命令行参数、页面命名规则、pages目录与多语言翻译目录布局、{{...}}占位符渲染、平台/语言双重解析算法以及离线缓存下载策略。读完本文你将理解一个规范合规的 tldr 客户端应如何实现参数解析、页面查找、语言选择与缓存更新并能结合本仓库的实际页面如 git-checkout.md、docker-inspect.md与配套脚本如 check-pr.sh验证这些规则的落地形态。需要先澄清一个边界这份文档不是页面内容的书写格式规范那是 contributing-guides/style-guide.md 的职责它只规定用户应如何与官方客户端交互即客户端与用户之间的接口契约。文档使用 RFC 2119 中的 MUST / MUST NOT / SHOULD / RECOMMENDED / MAY / OPTIONAL 等关键词表达强制与建议语义当前规范版本为Unreleased。核心术语Page 与 Platform规范首先定义了理解后续所有条款的两个基础概念Page页面tldr-pages 由大量pages组成每个页面描述一个具体命令的用法。Platform平台页面按平台操作系统分组例如windows、linux、osx。其中common是特殊平台存放在多个平台上表现一致的命令页面。平台差异化处理有一条重要规则如果一个命令在多个平台通用、但在某个平台上略有差异则主页面仍存放在common目录同时在差异平台的专属目录放一份针对该平台的副本。规范给出的例子是命令foo在 mac、windows、linux 通用但 windows 上行为不同——主页面放common另在windows放修改后的副本。此外客户端SHOULD支持把common作为平台参数传入即-p common与--platform common以便在命令存在平台专属变体如linux、openbsd下的版本时仍能强制显示通用页面。标准化的命令行接口CLI对于提供 CLI 的客户端规范以表格形式规定了必须支持Required与可选支持的参数。关键约束是一旦支持某个选项就必须同时实现它的所有变体——例如实现-v的同时必须实现--version实现缓存更新的客户端必须同时支持-u和--update。选项是否必需含义-v,--version必需显示客户端自身版本号以及它所实现的规范版本号-p,--platform必需指定执行动作列出或搜索所用的平台含common。若指定须优先检查所选平台而非当前平台-u,--update条件性更新离线页面缓存。若客户端支持缓存则必须实现-l,--list否将当前平台的全部页面列出到标准输出-L,--language否指定返回页面的首选语言覆盖其他语言探测机制-S,--short-options否若设置过滤示例只展示选项的短形式-E,--long-options否若设置过滤示例只展示选项的长形式关于短/长选项显示还有一条默认行为约定当用户既未设置--short-options也未设置--long-options时客户端SHOULD默认只显示长形式两者同时给出时则两种形式都显示具体输出格式见下文页面格式小节。TTY 装饰规则当标准输出是 TTY 时客户端可以额外打印装饰反之如输出被管道重定向则MUST NOT输出任何附加装饰。例如页面列表在非 TTY 下必须每行一个页面名以便grep等标准工具处理。客户端也可以支持规范之外的额外自定义参数与语法。官方示例调用tldr --update tldr --version tldr -l页面名处理空格转连字符、大小写统一第一个不以短横线-开头的参数MUST被当作页面名。页面名允许包含空格与混合大小写客户端需要透明地完成两步规范化空格 → 连字符git checkout变为git-checkout统一转小写eyeD3变为eyed3。tldr 7za tldr eyeD3 # 等价于 tldr eyed3 tldr git checkout # 等价于 tldr git-checkout tldr --platform osx bash这一规则在仓库目录结构中得到直接印证pages/common下存在以连字符命名的页面文件如git-checkout.md、adb-logcat.md、acme.sh-dns.md等而7za.md、2to3.md这类带数字的命令则保持原名。目录结构pages 与多语言翻译目录所有页面的主版本存放在pages目录不直接放在其根下内部按平台分子目录pages/ common/ linux/ windows/ osx/ ...etc.客户端SHOULD支持将macos作为osx的别名。虽然客户端不必自动支持新平台但规范RECOMMENDED支持它们MUST NOT在 tldr-pages 新增平台时崩溃——这要求实现层面采用可动态发现的平台目录扫描而不是硬编码平台列表。页面文件以.md为扩展名存放在对应平台目录下命令名与文件名的映射如下命令名映射后名称文件名7za7za7za.mdgit checkoutgit-checkoutgit-checkout.mdtartartar.md翻译目录pages.locale翻译目录与主pages目录平级命名格式为pages.locale其中locale是 POSIX Locale Name形如language_countrylanguage所选语言最短的 ISO 639 语言代码country所选区域的双字母 ISO 3166-1 国家代码。规范给出的例子中文台湾pages.zh_TW葡萄牙语巴西pages.pt_BR意大利语pages.it这些翻译目录的内部结构与主pages目录完全一致。在本仓库中可以看到大量实例pages.zh/下含android/、common/、linux/、osx/、windows/等子目录其中common已有 957 个页面文件pages.zh_TW/同样具备完整的平台子目录。某语言可能还没有对应目录或某个页面在该语言下尚无翻译——这些都属于正常状态客户端必须容忍。页面格式与占位符语法{{...}} 与 {{[ | ]}}虽然规范的主体是客户端接口但它也明确了页面使用的 Markdown 方言页面以标准 CommonMark 书写唯一的例外是{{、}}以及{{[、]}}非标准占位符语法{{与}}包围示例中可编辑的值{{[与]}}表示选项的短形式/长形式变体两侧由单个|分隔——左侧是短形式右侧是长形式。渲染规则MUST 级别客户端MAY高亮占位符但MUST去掉其外层花括号当选项占位符被设置为只显示短形式或只显示长形式时MUST NOT再对其高亮因为此时已不存在用户选择只显示短/长形式时客户端MUST去掉选项占位符的方括号使用\转义的\{\{与\}\}不应被视为占位符而应显示字面花括号且去掉反斜杠占位符转义仅当两侧花括号都被转义时才生效如\{或\{{中的反斜杠必须显示当命令参数本身包含{}如stash{0}时外层花括号标记占位符内层花括号必须原样显示客户端MUST NOT因 CommonMark 规范范围内的页面格式变化而崩溃。渲染示例规范原文要求页面源码渲染结果ping {{example.com}}ping example.comdocker inspect --format \{\{range.NetworkSettings.Networks\}\}\{\{.IPAddress\}\}\{\{end\}\} {{container}}docker inspect --format {{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}} containermount \\{{computer_name}}\{{share_name}} Z:mount \\computer_name\share_name Z:git stash show --patch {{stash{0}}}git stash show --patch stash{0}git add {{[-A|--all]}}仅短/长形式时渲染为git add -A或git add --all同时请求两者时渲染为git add [-A|--all]这些语法在本仓库页面中均有真实案例短/长选项变体git-checkout.md 使用git checkout {{[-t|--track]}} {{remote_name}}/{{branch_name}}git-stash.md 使用git stash {{[-u|--include-untracked]}}与git stash show {{[-p|--patch]}}双重花括号转义docker-inspect.md 中的 Go 模板参数完整展示了\{\{range.NetworkSettings.Networks\}\}这类转义写法命令自身含花括号git-stash.md 的git stash show --patch {{stash{0}}}体现了外层花括号为占位符、内层保留的规则嵌套占位符windows/mount.md 中的\\{{computer_name}}\{{share_name}}展示了 Windows UNC 路径场景下的转义与嵌套处理。仓库中的 scripts/check-errors.sh 用一组 grep 模式在 CI 中排查占位符与括号书写错误例如检查{{[-A|--all]}}短/长选项是否被误写成{{-[a-zA-Z][a-zA-Z]|-、检查{{是否未闭合、反引号是否成对出现等这相当于对上述渲染规则的反向校验。页面解析算法页面名经过空格→连字符、统一小写两步规范化后客户端需要决策两件事显示哪个语言的页面、显示哪个平台的页面。平台解析解析顺序遵循以下规则客户端MUST默认显示客户端所运行平台的页面例如运行在 Windows 11 上的客户端默认显示windows平台的页面可用用户配置覆盖此默认行为若宿主平台没有该页面MUST回退到特殊common平台若宿主平台与common都没有则SHOULD搜索其他平台并显示那里的页面同时附上警告信息。规范给出的示例Windows 用户请求apt页面解析顺序为windows无→common无→osx无→linux找到其中第 3、4 步顺序可互换。这里要特别提醒由于解析逻辑的存在客户端可能展示不属于宿主平台的页面例如页面只在common中存在而宿主平台没有。因此客户端MUST NOT假设某个命令在宿主平台上一定可执行。规范还RECOMMENDED客户端自动探测pages目录下新增的平台。页面找不到时如果任何平台都找不到该页面客户端RECOMMENDED显示错误信息并附上向tldr-pages/tldr仓库提交新 issue 的链接链接形式如下https://github.com/tldr-pages/tldr/issues/new?titlepage%20request:%20{command_name}其中{command_name}是未找到的命令名。提供 CLI 且能控制退出码的客户端MUST在显示上述信息的同时以非零退出码结束该要求自规范 v1.4 起生效。找到多个平台版本时客户端MAY向用户显示一条提示告知存在多个平台版本的页面。语言解析如果客户端能访问环境变量MUST按下面的算法推导首选语言否则如浏览器环境须基于所处环境的信息如navigator.languages做合理假设。涉及的环境变量LANG用户首选区域形如ll[_CC][.encoding]LANGUAGE区域优先级列表形如l1:l2:...用于在LANG指定的区域不可用时按序回退两者中的C或POSIX值应被忽略。语言决定算法MUST 执行检查LANG的值若未设置跳到第 5 步从LANGUAGE提取优先级列表若未设置初始为空列表将LANG的值追加到优先级列表末尾按优先级列表顺序查找并使用第一个可用语言若所有语言都不可用回退到英语。规范给出的完整示例表LANGLANGUAGE结果优先级czit:cz:deit,cz,de,enczit:de:frit,de,fr,cz,enit未设置it,en未设置it:czen未设置未设置en注意第二行的细节LANGUAGE列表中的语言排在前面LANG的值被追加到末尾因此最终顺序是it, de, fr, cz, en而非cz在前。此外无论通过环境变量确定了何种语言如果页面在用户首选语言下不存在客户端MUST总是尝试回退到英语客户端MAY在找不到首选语言页面时通知用户可附带指向贡献指南翻译章节的链接。规范还RECOMMENDED让语言可配置而不只依赖环境建议通过配置文件乃至命令行选项如-L, --language配置或覆盖语言一旦用户显式指定该选项客户端MUST严格遵守其值MUST NOT以其他语言展示页面否则应以恰当的错误信息失败。LC_MESSAGES环境变量MAY存在若客户端自身做了本地化且该变量存在客户端MUST用它决定界面文本语言与页面语言分开处理没有LC_MESSAGES时则回退用LANG与LANGUAGE决定界面语言。平台优先于语言规范以 IMPORTANT 提示强烈推荐页面查找应优先考虑平台即在检查下一个首选语言之前先在每种语言下按平台查找以保证页面解析有意义且正确。示例在linux上设置LANGit、LANGUAGEit:fr:en查找some-page步骤检查路径结果1pages.it/linux/some-page.md不存在2pages.fr/linux/some-page.md不存在3pages/linux/some-page.md不存在4pages.it/common/some-page.md不存在5pages.fr/common/some-page.md不存在6pages/common/some-page.md找到可以看到算法先在每种语言下遍历linux平台再遍历common平台而不是先遍历完所有语言再切平台。本仓库的目录结构为此提供了天然支撑pages.zh/linux/、pages.zh/common/、pages.zh_TW/linux/、pages.zh_TW/common/等目录并存翻译目录结构含平台子目录与主pages完全一致客户端可机械地按pages.locale/platform/name.md拼接路径探测。缓存机制离线页面归档的下载契约如果合适规范RECOMMENDED客户端实现页面缓存。一旦实现客户端MUST从以下来源下载整个归档https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip按语言拆分的归档格式为https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.{{language-code}}.zip例如tldr-pages.en.zip仅英语归档另有地址https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.zip重要废弃警告CAUTION在规范 2.2 版本之前规范曾要求客户端从https://tldr.sh/assets下载归档该地址在被弃用近两年后已于2026 年 1 月 20 日从该位置移除关联 PR 为 tldr-pages/tldr#20565。仍使用旧地址的客户端将无法再下载页面——这是新实现必须规避的兼容性陷阱。缓存还应遵循用户的语言配置若有避免为不使用的语言浪费磁盘空间客户端MAY定期自动更新缓存。这与-u, --update参数形成闭环客户端支持缓存时--update是强制实现项下载源则必须遵守上述归档地址。规范演进历史Changelog 要点规范的变更记录本身就是客户端生态演进的重要参考核心版本节点如下v2.32025-03-07新增短/长选项{{[ | ]}}规范明确common可作为受支持的平台选项记录旧资产站点移除日期。v2.22024-03-20缓存下载地址改为 GitHub Releases新增三重花括号占位符消歧要求增加旧资产 URL 弃用提示。v2.12023-11-30要求支持占位符转义语法建议自动探测pages目录新增平台。v2.02023-09-10建议支持macos作为osx别名从--list中移除特殊的all平台资产链接移除master分支要求支持长选项建议支持按翻译语言分别缓存归档。v1.52021-03-17要求页面名解析前统一转小写归档链接改用 HTTPS。v1.42020-08-13要求 CLI 客户端在找不到页面时以非零退出码结束。v1.32020-06-11澄清语言解析中回退英语的规则LANG/LANGUAGE对齐 GNU 规范。v1.22019-07-03新增-L, --language推荐选项区域标签从 BCP-47 切换到 POSIX 风格旧版规范废弃明确缓存功能建议。v1.02019-01-23初始发布。可以看到现代 tldr 客户端的关键能力——占位符转义、短/长选项过滤、平台自动探测、按语言缓存、非零退出码——大多是 v1.4 之后陆续以新增规范形式确立的这也解释了为什么新旧客户端在页面渲染上会存在差异。客户端合规实现的仓库配套lint、CI 与模板规范定义了客户端应当如何而仓库内还有一整套工具链保证页面数据如何合规二者共同支撑客户端正确渲染页面格式模板contributing-guides/style-guide.md 定义了每个页面最多 8 条命令示例、# 命令名标题 简介 More information:链接的骨架并要求文件名与标题一致、文件名必须小写。本地 lint可通过npm install --global tldr-lint安装tldr-lint别名tldrl校验单个页面详见 pages/common/tldr-lint.md部分客户端还支持tldr --render path/to/tldr_page.md本地预览渲染效果。仓库级校验脚本package.json 声明了lint-tldr-pages: tldr-lint ./pages与lint-markdown: markdownlint pages*/**/*.md两个 npm scriptscripts/check-pr.sh 在 PR 上检测平台目录出现 common 已有页面的副本、翻译页面缺英文原版、页面命令数与内容相对英文版过期、.md扩展名缺失等异常scripts/check-errors.sh 用 grep 规则扫描占位符、反引号配对、标点、标准流措辞等问题。翻译参数模板contributing-guides/translation-templates/common-arguments.md 提供了path/to/file、package、username等常见占位符在数十种语言下的标准译法是客户端渲染可编辑值时呈现内容的源头之一。对于开发者而言若要从零实现一个合规客户端推荐按以下顺序对照规范自检先实现-v/--version、-p/--platform等必需参数与短长选项再实现页面名的空格→连字符、小写化规范化接着按平台 → common → 其他平台的优先级实现页面查找再叠加LANG/LANGUAGE/-L的语言解析平台优先于语言最后按归档地址实现-u, --update缓存更新并确保页面找不到时非零退出。每一步都能在本仓库的页面文件与 CI 脚本中找到对应的数据侧验证。赞分享文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载相关推荐tldr 别名页Alias Pages多语言模板全解析从规范到自动化生成tldr 别名页Alias Pages多语言模板全解析从规范到自动化生成 当某个命令只是另一个命令的别名如 vi 是 vim 的别名时tldr 并不文档教程知识库Salt Player 本地音乐播放器完整指南10 分钟从下载到离线播放Android Windows 双端Salt Player 本地音乐播放器完整指南10 分钟从下载到离线播放Android Windows 双端 Salt Player椒盐音乐是一款Karukan上下文工程实战10个字符的lctx为什么这么够用Karukan上下文工程实战10个字符的lctx为什么这么够用 Karukan 是一个面向 Linux 与 macOS 的开源日语输入法核心是一台神经网络假人工智能NLP本地部署桌面应用上一篇Marker-PDF 安装问题分析与解决方案下一篇PyWxDump 被移除微信聊天记录解密导出工具下架事件完整说明创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考