diff options
| author | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:40:17 -0500 |
|---|---|---|
| committer | Peter Bengtsson <mail@peterbe.com> | 2020-12-08 14:40:17 -0500 |
| commit | 33058f2b292b3a581333bdfb21b8f671898c5060 (patch) | |
| tree | 51c3e392513ec574331b2d3f85c394445ea803c6 /files/zh-cn/mdn | |
| parent | 8b66d724f7caf0157093fb09cfec8fbd0c6ad50a (diff) | |
| download | translated-content-33058f2b292b3a581333bdfb21b8f671898c5060.tar.gz translated-content-33058f2b292b3a581333bdfb21b8f671898c5060.tar.bz2 translated-content-33058f2b292b3a581333bdfb21b8f671898c5060.zip | |
initial commit
Diffstat (limited to 'files/zh-cn/mdn')
58 files changed, 7508 insertions, 0 deletions
diff --git a/files/zh-cn/mdn/about/index.html b/files/zh-cn/mdn/about/index.html new file mode 100644 index 0000000000..912b4e8e75 --- /dev/null +++ b/files/zh-cn/mdn/about/index.html @@ -0,0 +1,111 @@ +--- +title: 关于 MDN +slug: MDN/About +tags: + - MDN + - 合作伙伴 + - 指南 + - 文档 + - 版权 + - 社区 + - 许可 +translation_of: MDN/About +--- +<div>{{MDNSidebar}}</div> + +<p>MDN Web Docs 是一个提供 Web 技术和促进 Web 技术软件的不断发展的学习平台，包括：</p> + +<ul> + <li>Web 标准（例如：<a href="/zh-CN/docs/CSS" title="/zh-CN/docs/CSS">CSS</a>、<a href="/zh-CN/docs/HTML" title="/zh-CN/docs/HTML">HTML</a> 和 <a href="/zh-CN/docs/JavaScript" title="/zh-CN/docs/JavaScript">JavaScript</a>）</li> + <li><a href="/zh-CN/docs/">开放 Web 应用开发</a></li> + <li><a href="/zh-CN/docs/Add-ons">Firefox 附加组件开发</a></li> +</ul> + +<h2 id="我们的使命">我们的使命</h2> + +<p>MDN 的使命很简单：为开发人员提供在开放的 Web 网络上轻松构建项目所必需的信息。如果它是一种暴露于 Web 网络上的开放技术，我们希望将其记录下来。</p> + +<p>此外，我们还提供有关 <a href="/zh-CN/docs/Mozilla">Mozilla 产品</a> 以及如何<a href="/zh-CN/docs/Mozilla">构建和贡献 Mozilla 项目</a>的文档。</p> + +<p>如果你不确定 MDN 是否应涵盖特定主题，请阅读：<a href="/zh-CN/docs/MDN/Contribute/Content/Rules_Of_MDN_Documenting">这是否属于 MDN ？</a></p> + +<h2 id="如何帮助我们">如何帮助我们</h2> + +<p>想要帮助 MDN ，你并不需要编写代码的能力！你可以通过很多其他的途径帮助我们，包括复查文章来保证文章的可读性，添加示例代码等。实际上，帮助我们的方法有很多，我们还专门建立了一个<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Getting_started">入门指南</a>来帮你上手，它可以根据你的兴趣和你的空闲时间推荐合适的任务！</p> + +<p>你也可以在个人博客或网站中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Promote">添加 MDN 链接</a>来帮助我们推广。</p> + +<h2 id="MDN_社区">MDN 社区</h2> + +<p>我们的社区遍及全球！我们拥有来自世界各地、使用不同语言的了不起的贡献者。<span class="short_text" id="result_box" lang="zh-CN"><span>如果您想了解更多我们的信息，或者想以任何方式帮助 MDN ，请查看我们的邮件列表或 IRC 聊天频道！</span></span></p> + +<h2 id="版权和许可">版权和许可</h2> + +<p>MDN 文档来自于包括 Mozilla 基金会内部与外部编辑者的贡献。除非另有说明，文档基于<a href="http://creativecommons.org/licenses/by-sa/2.5/">署名 - 相同方式共享许可</a>（CC-BY-SA）V2.5及以上版本发布。请在包括链接至特定文档页面的内容来源在内，以“Mozilla 贡献者”名义署名。例如，在为本文署名时，你需要这样写：</p> + +<pre class="notranslate">“ <a href="https://developer.mozilla.org/zh-CN/docs/MDN/About$history">Mozilla贡献者</a>基于<a href="http://creativecommons.org/licenses/by-sa/2.5/">CC-BY-SA 2.5</a>协议发布的<a href="https://developer.mozilla.org/zh-CN/docs/MDN/About">关于MDN</a>. ”</pre> + +<p>注意，在示例中，“Mozzilla 贡献者”链接了引用页面的历史版本。请浏览<a href="https://wiki.creativecommons.org/Marking/Users">Best practices for attribution</a>以获得进一步的解释。</p> + +<div class="note"> +<p><strong>注意:</strong> 请浏览 <a href="/zh-CN/docs/MDN_content_on_WebPlatform.org" title="/zh-CN/docs/MDN_content_on_WebPlatform.org">MDN content on WebPlatform.org</a> 获取在上述网站使用和署名 MDN 内容的信息。</p> +</div> + +<p>在2010年8月20日之前添加到 wiki 中的示例代码通过<a class="external external-icon" href="http://www.opensource.org/licenses/mit-license.php" title="http://www.opensource.org/licenses/mit-license.php">MIT license</a>发布，你应该向MIT模板中添加相应的属性信息："© <最后修订时间> <发布者姓名>"。</p> + +<p>在2010年8月20日之后添加到wiki中的示例代码属于 <a class="external external-icon" href="http://creativecommons.org/publicdomain/zero/1.0/" title="http://wiki.creativecommons.org/Public_domain">public domain</a>. 版权声明是不必要的，如果你需要，可以使用以下内容："Any copyright is dedicated to the Public Domain. http://creativecommons.org/publicdomain/zero/1.0/".</p> + +<p>如果你需要对该 wiki 作出贡献，你必须在Attribution-ShareAlike license (或者在你编辑的页面已经制定的其他版权许可)下发布你的文档，在 <a href="http://creativecommons.org/publicdomain/zero/1.0/" title="http://creativecommons.org/publicdomain/zero/1.0/">Creative Commons CC-0</a> (a Public Domain dedication)下发布你的示例代码。将内容添加到这个 wiki 表明你同意在相应的许可之下发布你贡献的内容。</p> + +<p>一些历史内容是在不同于以上的版权许可之下发布的，这些已在页面底部通过<a href="https://developer.mozilla.org/Archive/Meta_docs/Examples/Alternate_License_Block">其他版权许可</a>的方式进行了标注。</p> + +<div class="warning"> +<p><strong>重要说明:</strong> 任何新建的页面都不可以使用其他版权许可。</p> +</div> + +<p>贡献的内容的版权在作者未授予他人之前归原作者所有。</p> + +<p>对于此处讨论的话题有任何问题，请联系 <a class="external external-icon" href="mailto:eshepherd@mozilla.com" rel="nofollow" title="mailto:eshepherd@mozilla.com">Eric Shepherd</a>。</p> + +<hr> +<p>Mozilla 基金会的商标、标识、服务标志以及网站的设计、外观不包含在基于知识共享许可的范围内。从某种意义上说，它们是内容的创造者（如图标和图形设计），而这些内容并不在上述许可范畴内发布。 如果你也希望这样发布文档，或者你对这些许可条款还有任何的疑问，你可以联系 Mozilla 基金会以获得更多的帮助： <a class="external text" href="mailto:licensing@mozilla.org" rel="nofollow" title="mailto:licensing@mozilla.org">licensing@mozilla.org</a>.</p> + +<h2 id="下载整站内容">下载整站内容</h2> + +<p>你可以下载 <a href="https://mdn-downloads.s3-us-west-2.amazonaws.com/developer.mozilla.org.tar.gz">MDN 的镜像文件</a>(2017年2月，总共2.1GB)</p> + +<h3 id="单独页面">单独页面</h3> + +<p>你可以通过在页面URL后添加<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Kuma/API#Document_parameters">文档参数</a>来制定需要的格式，获取MDN上每个单页的内容。</p> + +<h3 id="第三方工具">第三方工具</h3> + +<p>你可以使用第三方工具访问 MDN 的内容，例如 <a href="http://kapeli.com/dash">Dash</a> (适用于 Mac OS) 和 <a href="http://zealdocs.org/">Zeal</a> (适用于 Linux 和 Windows)。</p> + +<h2 id="向_MDN_报告错误">向 MDN 报告错误</h2> + +<p>在使用MDN的过程中，你将不时遇到问题。不论是网站基础设施的问题或者你查看的文档的错误，你都可以自己修改或报告错误。前者是更推荐的，但有时候后者可能更适合于你，那当然也是可行的。</p> + +<h3 id="文档错误">文档错误</h3> + +<p>显然，由于 MDN 是一个 wiki ，因而最佳的解决你遇到的问题的方法是自己动手解决。然而有时候，你也许不知道如何解决或者因为其他重要的事无法脱身，那么此时你需要将问题记录下来，以便于之后方便其他人查看。</p> + +<p>你只需要在 <a href="https://bugzilla.mozilla.org/form.doc">documentation request bug</a> 登陆后提交一个错误表单来报告错误，之后的工作将由Mozilla处理。我们的文档请求表单便捷易用,它会收集解决问题所需的必要信息。</p> + +<p>当然，我们的编辑社区是十分繁忙的，因而有时候最快的确认文档问题是否解决的方案是自己动手修正。参见<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Creating_and_editing_pages">创建与编辑页面</a>以了解更多信息。</p> + +<h3 id="站点错误反馈或新特性请求">站点错误反馈或新特性请求</h3> + +<p><a href="https://developer.mozilla.org/zh-CN/docs/Project:MDN/Kuma" title="/zh-CN/docs/Project:MDN/Kuma">Kuma</a> 是 Mozilla 开发的用于驱动 MDN 的平台，目前仍处在持续开发的进程中。我们的开发者，以及大量的志愿者，正在不断的对这个平台作出改进。如果你在使用网站时发现了错误，或者遇到的问题，或者有新的可以让这个软件更加完美的想法建议，可以使用 <a href="https://bugzilla.mozilla.org/form.mdn" title="https://bugzilla.mozilla.org/form.mdn">Kuma bug form</a> 进行反馈。</p> + +<h2 id="MDN历史">MDN历史</h2> + +<p>Mozilla 开发者网络（亦称作 Mozilla 开发者中心（MDC）或 Devmo）在2005年年初启动。那时 <a class="external" href="http://www.mozillafoundation.org">Mozilla 基金会</a> 从 AOL 获得了许可协议，得以使用原创的 <a href="/Project:cn/DevEdge" title="Project:en/DevEdge">DevEdge</a> 内容。DevEdge 内容的引入具有抛砖引玉之效，因此在那不久在社区志愿者的努力下它被迁移到了这个更易于更新与维护的 wiki 。</p> + +<p>此后，这个项目不断发展，现在已经成为所有与关于 Mozilla 项目和开放网络技术的文档的核心一环。在2010年，该项目更名为Mozilla开发者网络（Mozilla Developer Network）。2011年，又添加了供web开发者分享与展示代码的 <a class="external" href="http://developer.mozilla.org/zh-CN/demos" title="https://developer.mozilla.org/zh-CN/demos/">Demo Studio</a> 与提供教程的 <a class="external" href="http://developer.mozilla.org/zh-CN/learn" title="https://developer.mozilla.org/zh-CN/learn">Learning</a> 页面。（MDC 现在表示了"MDN文档中心（MDN Doc Center）"）现在，Mozilla开发者网络正向着成为供Web设计师、应用开发者、以及拓展、主题制作者们时常参考的资源的方向发展。</p> + +<p>更多关于 Mozilla 的后世前身可在我们的<a href="/zh-CN/docs/MDN_at_ten">十周年纪念庆</a>页面查看,其中还有参与者发表的 Ta 对 Mozilla 的评价。</p> + +<h2 id="关于_Mozilla">关于 Mozilla</h2> + +<p>想要了解是什么在驱动着我们，是什么使我们与众不同，请访问<a href="http://www.mozilla.org/zh-CN/mission/">使命</a>页面。在那里你能了解更多关于我们的信息，不论你想知道如何成为 Mozilla 的一员，或者仅仅想知道如何找到我们。</p> diff --git a/files/zh-cn/mdn/community/conversations/index.html b/files/zh-cn/mdn/community/conversations/index.html new file mode 100644 index 0000000000..e37d40486e --- /dev/null +++ b/files/zh-cn/mdn/community/conversations/index.html @@ -0,0 +1,59 @@ +--- +title: MDN 社区对话 +slug: MDN/Community/Conversations +tags: + - 不完善的 + - 后期还需要改善 + - 社区相关 + - 经过一次润色的 +translation_of: MDN/Community/Conversations +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN的“工作”在MDN网站开展，但“社区”也通过（异步）讨论以及（同步）在线聊天和会议开展。</p> + +<h2 id="异步讨论"><span class="short_text" id="result_box" lang="zh-CN"><span>异步讨论</span></span></h2> + +<p><span id="result_box" lang="zh-CN"><span>为了分享信息并进行持续的讨论，<a href="https://discourse.mozilla-community.org/c/mdn">MDN在Mozilla话语论坛中有自己的类别（“MDN”）</a>。</span> <span>将此类别用于与MDN相关的所有主题，包括文档内容的创建，翻译和维护;</span> <span>MDN平台开发;</span> <span>并进行规划，目标设定和进度跟踪。</span></span></p> + +<ul> + <li><span id="result_box" lang="zh-CN"><span>要加入Mozilla的话语，请参阅<a href="https://discourse.mozilla-community.org/t/signing-up-and-logging-in/16017">注册并登录</a>;</span> <span>如果您有Mozilla LDAP帐户，则可以使用该帐户，而不是“使用电子邮件登录”。</span></span></li> + <li><span class="short_text" id="result_box" lang="zh-CN"><span>要订阅MDN类别，请参阅<a href="https://discourse.mozilla-community.org/t/subscribing-to-categories-and-topics/16024">订阅类别和主题</a>。</span></span></li> + <li><span id="result_box" lang="zh-CN"><span>（可选）如果您希望主要通过电子邮件与话语进行交互，请参阅<a href="https://discourse.mozilla-community.org/t/mailman-mode/15279">为自己设置邮件列表体验</a>。</span> <span>您可以通过发送电子邮件至：<a href="mailto://mdn@mozilla-community.org">mdn@mozilla-community.org</a>，开始话语讨论。</span> <span>如果您通过电子邮件使用话语，您可以通过回复您收到的通知电子邮件来回复邮件。</span> <span>如果您想在回覆内插入意见，请在您的内联块之前和之后放置两个回车，以便话语解析正确。</span></span></li> +</ul> + +<h2 id="历史档案"><span class="short_text" id="result_box" lang="zh-CN"><span>历史档案</span></span></h2> + +<p><span id="result_box" lang="zh-CN"><span>在2017年6月之前，MDN相关的讨论发生在与Google群组关联并归档的邮件列表中。</span> <span>如果您想搜索这些过去的讨论，您可以查看与旧邮件列表相对应的Google网上论坛。</span> <span>（</span></span>是的，我们知道这些名字是重叠和混淆。历史的偶然性。对此我们感到很抱歉。<span lang="zh-CN"><span>）</span></span></p> + +<dl> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdc">mozilla.dev.mdc</a></dt> + <dd><span class="short_text" id="result_box" lang="zh-CN"><span>此列表用于讨论MDN上的文档内容。</span></span></dd> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdn">mozilla.dev.mdn</a></dt> + <dd><span class="short_text" id="result_box" lang="zh-CN"><span>此列表涉及MDN底层Kuma平台的开发工作。</span></span></dd> + <dt><a href="https://groups.google.com/forum/#!forum/mozilla.dev.mdn">mozilla.mdn</a></dt> + <dd><span class="short_text" id="result_box" lang="zh-CN"><span>这个论坛是针对高层次的规划和优先级讨论，MDN网站和其他相关举措。</span></span></dd> +</dl> + + + +<h2 id="同步聊天">同步聊天</h2> + +<p>Mozilla实时的讨论平台是<a href="https://matrix.org">Matrix</a>，Mozilla自己拥有使用这个通讯协议的<a href="https://chat.mozilla.org/">服务器</a>。网页中即可加入讨论。</p> + +<p><a href="https://chat.mozilla.org/#/room/#mdn:mozilla.org">MDN Web文档聊天室</a>是为讨论MDN内容的主要频道。我们探讨编写、内容编排等内容。我们也会进行“茶水间”讨论（摸鱼），这是我们的社群保持联系，或者仅仅用来消遣的方式。通常在北美和欧洲的工作日，这间聊天室最为活跃。</p> + +<p>你或许会想了解一下怎么使用<a href="https://wiki.mozilla.org/Matrix">Mozilla的Matrix</a>，然后呢，如果你真的很喜欢它的话，那么可以安个独立的Matrix应用，例如<a href="https://about.riot.im/">Riot.im</a>。</p> + +<h3 id="那么IRC呢？">那么IRC呢？</h3> + +<p>多年来，Mozilla用互联网中继聊天（IRC）来进行实时讨论。到了2020年初，Matrix已经把IRC淘汰了。你可能会在很多地方看到有人提到IRC的频道，包括MDN上。你可以帮忙更新MDN上你看到的IRC频道的链接，为指向对应Matrix聊天室的链接。如果你不确定这个话题对应的Matrix聊天室是哪间，那么可以来<a href="https://chat.mozilla.org/#/room/#general:mozilla.org">General</a>聊天室询问。不再活跃的项目和话题可能也不会有Matrix聊天室，如果是这样的话，把链接删掉即可。</p> + +<h2 id="参加我们的会议（和其他活动）">参加我们的会议（和其他活动）</h2> + +<p><br> + MDN团队会举行一些面向MDN社区的定期会议。查看 Mozilla维基上的<a href="https://wiki.mozilla.org/MDN/Meetings">MDN Meetings</a> 页面获取关于日程、议程和笔记的细节，以及如何参加的信息。</p> + +<p>查看<a href="https://www.google.com/calendar/embed?src=mozilla.com_2d35383434313235392d323530%40resource.calendar.google.com">MDN Events calendar</a>上的这些和其他会议、当地聚会和其他项目。在 <a href="https://wiki.mozilla.org/MDN/Meetings">MDN Meetings wiki page</a>上有定期会议</p> + +<p>如果你看到一个在Vidyo videoconferencing系统的“mdn”频道举行的会议，你可以在<a href="https://v.mozilla.com/flex.html?roomdirect.html&key=gMM1xZxpQgqiQFNkUR3eBuHgxg">网上加入谈话</a>。</p> diff --git a/files/zh-cn/mdn/community/doc_sprints/index.html b/files/zh-cn/mdn/community/doc_sprints/index.html new file mode 100644 index 0000000000..ca1da4be91 --- /dev/null +++ b/files/zh-cn/mdn/community/doc_sprints/index.html @@ -0,0 +1,123 @@ +--- +title: Doc sprints +slug: MDN/Community/Doc_sprints +tags: + - NeedsUpdate +translation_of: MDN/Community/Doc_sprints +--- +<div>{{MDNSidebar}}</div> + +<p>{{ draft() }}</p> + +<div class="note"> +<p><strong>Note: </strong>MDN社区在2010 - 2013年期间经常举办文档迭代。 从2014年开始，这些事件的范围扩大到“<a href="https://blog.mozilla.org/community/2015/04/17/a-highly-productive-hack-on-mdn-weekend-in-berlin/">Hack on MDN</a>”事件，其中包括代码窃取以及文档项目。 下面的大部分建议同样适用于 "Hack" sprints和documentation sprints。</p> +</div> + +<p><span class="seoSummary">这是组织</span>documentation sprint<span class="seoSummary">的指南。 它包含来自组织</span>doc sprints<span class="seoSummary">的人的建议和提示，以帮助您更好的组织文档。 本指南还借鉴了<a href="http://write.flossmanuals.net/book-sprints/introduction/">FLOSS手册书籍</a>的书籍。</span></p> + +<h2 id="什么是_doc_sprint">什么是 doc sprint?</h2> + +<p>doc sprint 是一段时间，一群人像你一样可爱的人，合作撰写关于给定主题或相关主题的文档。</p> + +<h2 id="sprints_的分类">sprints 的分类</h2> + +<p>sprints可以是线上的，也可以是线下的，也可以线上线下一起进行。对于线上sprints而言，每个人都可以在不同的地区参与，只需要通过中间渠道进行沟通。对于线下sprints，参加者在sprints期间聚集在同一地区，以便他们可以面对面进行交流。线下sprints需要更多的后勤规划，确保会议地点，可以容纳所有参与者，并且在sprints期间需要提供食物与安置参与者。</p> + +<p>另一种分类sprints的方式是通过专题聚焦。例如sprint可能关注特定的主题，比如：Web开发，或翻译特定语言。</p> + +<h2 id="计划一次_sprint">计划一次 sprint</h2> + +<h3 id="设定目标">设定目标</h3> + +<p>明确这次 sprint的目标, 包括内容和社区效应。 这能够帮助你更好地计划低层次的细节。</p> + +<ul> + <li>你想要记录一个特定的主题区域吗?</li> + <li>你想要创建一种特定类型的文档或者资源吗? 比如说，教程，代码示例，或者特定语言的翻译。</li> + <li>你想要吸引更多人加入到MDN，做出贡献吗？</li> + <li>你想要增进社区成员的凝聚力吗?</li> +</ul> + +<h3 id="决定类型和范围">决定类型和范围</h3> + +<p>基于你的目标, 确定 sprint的类型 (线上的，也可以是线下的，或者是线上线下一起进行) 和范围 (这是参与者会关注的)。</p> + +<p>比如说，你想要吸引新的社区成员，你可以选择本地的线下sprint, 因为不需要长途旅行, 而且参加者还可以见面. 如果您想要专注于特定的主题领域，其中内容贡献者是地理上分离的，而且早就彼此认识，那么一个线上sprint就很合适。</p> + +<h3 id="选择日期和时间">选择日期和时间</h3> + +<p>对于需要长途交通的线下sprint， 我们已经发现了三天 (比如说两天周末和一天工作日) 就足够做到很多重要的工作。也不会占用大家日常生活的很多时间。对于公开，本地，线下的sprint，大部分人只能够付出一天的时间. 对于线上的sprint, 我们通常进行两天: 一个工作日外加周末的一天。 As an alternative example, in the past there has been mini-sprint for writing and translating docs, every Wednesday evening in the Mozilla Paris office; it was primarily in-person for locals, but also got remote participation from Montreal (where it was at lunch time).</p> + +<p>Attaching a sprint to the end of a conference that everyone attended worked well; trying to run a sprint <em>during</em> a conference that everyone attended did not work so well. Make sure that participants know about the sprint when they make their conference plans, so that they allow extra days for the sprint.</p> + +<p>Consider the time zones that virtual participants are in; be sure that you allow enough working time in each time zone, and have some overlap when multiple zones (such as Europe and Americas, or Americas and Asia) are awake. However, it's just reality that no one time is good for everyone everywhere.</p> + +<p>For virtual sprints, the dates can be set as little as 2-3 weeks in advance. For in-person sprints, you need to decide further in advance, in order to allow time for people to decide and make travel arrangements.</p> + +<h3 id="Promote_the_sprint">Promote the sprint</h3> + +<p>You can make the sprint open, and invite the world, but you should have a few key people that you know for sure will participate. Work with them when selecting dates, to ensure that they are available during the chosen dates. If the sprint is not open, then you need only extend invitations; make sure that each invitation is personal, explaining why that person has been specificallly invited.</p> + +<p>For public sprints, identify existing groups that have an interest in the topic, for example: local Web developer meetup groups for a local in-person sprint. Send an announcement through whatever channel is appropriate for that group. Be sure to provide a link to a web page with more details, and include a call-to-action for people to sign up for the sprint. <a href="https://www.eventbrite.com/" title="https://www.eventbrite.com/">Eventbrite </a>and <a href="http://lanyrd.com" title="http://lanyrd.com">Lanyrd</a> are two services that support sign-ups. For Mozilla developer events, we have found that about half the people who sign up actually show up.</p> + +<p>Use the social media channels that are appropriate to reach your target attendees. We have found that for Web developers, this means Twitter, followed by Google Plus, more than Facebook or LinkedIn. However, popular channels can vary geographically (such as Orkut in Brazil). Reach out to a few well-connected people who have a large following among your target audience, and ask them to re-share your posts.</p> + +<h3 id="Logistics_for_in-person_sprints">Logistics for in-person sprints</h3> + +<p>Logistics for in-person sprints are greater for longer sprints and those where sprinters travel to attend. A short or locals-only sprint need relatively little logistical support.</p> + +<h4 id="Budget_and_funding">Budget and funding</h4> + +<p>You need to figure out how much the event is going to cost, and where the money is going to come from.</p> + +<p>Costs to consider in your budget include:</p> + +<ul> + <li>Travel</li> + <li>Lodging</li> + <li>Food</li> + <li>Meeting space</li> +</ul> + +<p>Some of these costs can be self-funded by participants, meaning that they pay for their own costs. There are a variety of ways to save money, which are mentioned in the following sections.</p> + +<p>It may be possible to get sponsorship from Mozilla to fund some of the costs of your event. It helps to have a clear focus for your event, and a specific plan and budget. If there is a <a href="https://reps.mozilla.org/people/#/">Mozilla Rep</a> in your area, work with them to request budget and swag through the Reps program. Otherwise, you can submit a <a href="https://bugzilla.mozilla.org/form.dev-engagement-event">developer events request</a> in Bugzilla.</p> + +<dl> + <dt>Venue</dt> + <dd>There are lots of options for meeting space. If you are in a city with a Mozilla office, you can use the community space in that office. Elsewhere, options include meeting rooms in libraries, churches, coffee shops, or businesses where you have contacts. Many cities now have coworking spaces that rent their conference rooms for a reasonable fee.</dd> + <dt>Resources</dt> + <dd>Be sure that your venue has good chairs and tables, and reliable power and Internet access. Sitting all day on a bad chair is not just uncomfortable; it can lead to injury. Make sure that the number of sprinters and their computers and devices does not overwhelm the power supply and available Internet bandwidth. Be generous (but not dangerous) with extension cords, and if necessary, international plug adapters. A projector for shared viewing can be very helpful. Whiteboards and sticky notes are great for brainstorming and planning.</dd> + <dt>Travel</dt> + <dd>Travel is relevant only if the sprinters do not all live close to the sprint venue. The usual strategies for saving on travel apply, and are not specific to doc sprints.</dd> + <dt>Accommodations</dt> + <dd>Where sprinters stay should not be inconveniently far from the meeting venue. It can be cheaper (and possibly more fun) to split the cost of a vacation house or flat, rather than paying for individual hotel rooms. If you have a mix of visitors and (willing) locals, the visitors can stay in the homes of local community members.</dd> + <dt>Food</dt> + <dd>Sprinters need to eat! Make arrangements for food during the sprint, and inform sprinters if certain meals will not be arranged. If the group is staying in a home, you can save money by buying and cooking food rather than going out to eat. Even if food is self-funded, it can reduce hassle to pitch into a common fund for food, rather than splitting every restaurant bill. If your venue allows, have snacks (some healthy and some not) available between meals.</dd> + <dt>Fun</dt> + <dd>Make time for non-writing social activities. These can be informal, like going for a hike together, or more formal, like a tourist excursion. Going out for beer (at the end of the day, of course) is usually a winner. On the other hand, don't plan every hour of every day. Everybody needs some down time, especially introverts.</dd> +</dl> + +<h2 id="During_the_sprint">During the sprint</h2> + +<h3 id="Planning_the_work">Planning the work</h3> + +<p> </p> + +<h3 id="Tracking_tasks">Tracking tasks</h3> + +<p>Have a way to track what tasks need to be worked on, who is doing what, and what has been completed. For MDN doc sprints, we use a wiki page for advance planning, and an etherpad for tracking work during the sprint.</p> + +<p>Often, people want to help but don't know where to start, and deciding among many options takes too much mental effort. For any given participant, give them a couple of possible tasks ("you could do A, or B"); this simplifies their choice, without making them feel like they're being bossed around.</p> + +<h3 id="Collaborating">Collaborating</h3> + +<p>One of the benefits of in-person sprints is that people can work together in ways that they might not be able to when they're not in the same place, for example, by working out ideas together on a whiteboard or by brainstorming with sticky notes. Still, there are opportunities for collaboration and camaraderie in any type of sprint. Chatting via IRC is essential for virtual sprints, and still very helpful for in-person sprints (for example, for sharing links). For a greater sense of "virtual presence", consider using a video conferencing service, such as Google Hangout.</p> + +<p>As an organizer, look for common interests among the participants and for ways that they can work together.</p> + +<h3 id="Celebrating_accomplishments">Celebrating accomplishments</h3> + +<p>Be sure to take time to celebrate accomplishments at the end of the sprint. This gives participants a better feeling than when the sprint just ends without any summary. If possible, have people "demo" what they have done, even if it is just showing a new article page.</p> + +<p>Also, share the sprint accomplishments via a blog post, to celebrate publicly as well. This is important for any kind of sprint, but especially for virtual sprints, where the participants might not all be online at the official end of the sprint for a wrap-up session.</p> diff --git a/files/zh-cn/mdn/community/index.html b/files/zh-cn/mdn/community/index.html new file mode 100644 index 0000000000..19e3e729ce --- /dev/null +++ b/files/zh-cn/mdn/community/index.html @@ -0,0 +1,53 @@ +--- +title: 加入 MDN 社区 +slug: MDN/Community +tags: + - MDN Meta + - 引导 + - 社区 +translation_of: MDN/Community +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<div class="summary"> +<p>MDN（Mozilla Developer Network）不仅仅是一个维基，而且是一个为使用开放 Web 技术的开发者而打造的社区。在这儿，开发者为了使 MDN 更加出色而共同努力。</p> +</div> + +<p>我们非常乐意您能给 MDN 贡献一份力量。当然我们更加希望您能加入 MDN 社区。只需简单的三步，即可加入我们：</p> + +<ol> + <li><a href="/zh-cn/docs/MDN/Contribute/Howto/Create_an_MDN_account">创建 MDN 账户</a></li> + <li><a href="/zh-cn/docs/MDN/Community/Conversations">参与交流</a></li> + <li><a href="/zh-cn/docs/MDN/Community/Whats_happening">关注正发生的一切</a></li> +</ol> + +<h2 id="社区是怎么运作的">社区是怎么运作的</h2> + +<p>下列文章详细地介绍了 MDN 社区。</p> + +<div class="row topicpage-table"> +<div class="section"> +<dl> + <dt class="landingPageList"><a href="/zh-cn/docs/MDN/Community/Roles">社区参与者</a></dt> + <dd class="landingPageList">MDN 社区有许多负责任的参与者。</dd> + <dt class="landingPageList"><a href="/zh-cn/docs/MDN/Community/Doc_sprints">文档迭代</a></dt> + <dd class="landingPageList">这是一个有关组织文档迭代的指导。它包含组织过文档迭代的开发者的建议和技巧，这个指导的目的是为了帮助您更好地组织文档。</dd> + <dt class="landingPageList"><a href="/zh-cn/docs/MDN/Community/Whats_happening">关注正发生的一切</a></dt> + <dd class="landingPageList">MDN 是由 <a class="external" href="https://wiki.mozilla.org/MDN">Mozilla 开发者网络社区</a> 发起的。这里有一些有关我们正在做的事物信息。</dd> +</dl> + +<dl> +</dl> +</div> + +<div class="section"> +<dl> + <dt class="landingPageList"><a href="/en-US/docs/MDN/Community/Conversations">MDN 社区对话</a></dt> + <dd class="landingPageList">MDN 上的工作在 MDN 社区网站上进行。但社区也提供讨论，在线交流和线下会议等多种对话方式。</dd> + <dt class="landingPageList"><a href="/en-US/docs/MDN/Community/Working_in_community">社区工作</a></dt> + <dd class="landingPageList">了解如何作为 MDN 社区的一部分来为 MDN 文档作贡献是本文的主题。本文给出了一些技巧来帮助您和其他开发者、开发团队来进行更有效的交流。</dd> +</dl> +</div> +</div> diff --git a/files/zh-cn/mdn/community/whats_happening/index.html b/files/zh-cn/mdn/community/whats_happening/index.html new file mode 100644 index 0000000000..abdb8b5215 --- /dev/null +++ b/files/zh-cn/mdn/community/whats_happening/index.html @@ -0,0 +1,42 @@ +--- +title: 跟随正在发生的事情 +slug: MDN/Community/Whats_happening +tags: + - MDN Meta + - 初学者 + - 指南 + - 社区 +translation_of: MDN/Community/Whats_happening +--- +<div>{{MDNSidebar}}</div> + +<p>MDN是由 <a href="https://wiki.mozilla.org/MDN">Mozilla开发者网络社区</a>带给你的。这里是关于我们正在做之事的共享信息的一些途径。</p> + +<h2 id="博客">博客</h2> + +<dl> + <dt><a href="https://hacks.mozilla.org/" title="https://hacks.mozilla.org/">Mozilla Hacks</a></dt> + <dd>Web和Mozilla技术和功能的新闻深度报道。</dd> + <dt><a href="https://blog.mozilla.org/community/category/developer-engagement/">Engaging Developers</a></dt> + <dd>促进社区参与Mozilla MDN活动和讨论。</dd> +</dl> + +<h2 id="信息流">信息流</h2> + +<ul> + <li><a href="http://twitter.com/MozDevNet">@MozDevNet</a>: 有趣的网页，教程，指南，提交要求，重大更新，以及其他有关Mozilla开发网络的消息。</li> + <li><a href="https://twitter.com/mozhacks" title="https://twitter.com/mozhacks">@MozHacks</a>: 关于新Web技术，很棒的HTML5应用程序和Firefox功能的推特。</li> + <li><a href="http://www.youtube.com/user/mozhacks" title="http://www.youtube.com/user/mozhacks">Mozilla Hacks (YouTube)</a></li> +</ul> + +<h2 id="状态栏和仪表盘">状态栏和仪表盘</h2> + +<p>查看 <a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Doc_status">文档状态</a> 页面，以了解整个MDN内容的动态。您将能够看到哪些文章需要书写或更新，哪些主题需要最大的帮助以及更多。</p> + +<h2 id="MDN会议">MDN会议</h2> + +<p>有一些跟踪和各种MDN相关的项目和进程共享进步定期会议，这些都描述了<a href="https://wiki.mozilla.org/MDN/Meetings">MDN会议的维基页面。</a></p> + +<p>想要了解最新动态，MDN社区会议是最佳渠道。MDN社区会议一般在美国太平洋时间周三上午10点举办（UTC-0800 十月——三月, UTC-0700 三月——十月）。会议每两周举办一次，会议采用 <a href="irc://irc.mozilla.org/mdn" title="irc://irc.mozilla.org/devmo">#mdn</a> <a href="http://wiki.mozilla.org/IRC" title="http://wiki.mozilla.org/IRC">IRC</a> 的方式举行。想要了解会议日程及往期会议记录，请查阅 <a href="https://wiki.mozilla.org/MDN/Meetings/Community" title="https://wiki.mozilla.org/MDN/Community_meetings">MDN 社区会议</a> 维基页面。</p> + +<p><a class="external text" href="https://www.google.com/calendar/embed?src=mozilla.com_2d35383434313235392d323530%40resource.calendar.google.com" rel="nofollow">公共 MDN活动 </a> 日历包括MDN社区会议，文件分享，其他MDN相关活动。如果您在我们的Vidyo视频会议系统中遇到正在“mdn”频道中举办的会议，那么您可以 从<a href="https://v.mozilla.com/flex.html?roomdirect.html&key=gMM1xZxpQgqiQFNkUR3eBuHgxg">从网站上加入会议对话</a>。</p> diff --git a/files/zh-cn/mdn/community/在社区工作/index.html b/files/zh-cn/mdn/community/在社区工作/index.html new file mode 100644 index 0000000000..e8cce689d8 --- /dev/null +++ b/files/zh-cn/mdn/community/在社区工作/index.html @@ -0,0 +1,101 @@ +--- +title: 社区工作 +slug: MDN/Community/在社区工作 +tags: + - 指南 + - 社区 +translation_of: MDN/Community/Working_in_community +--- +<div>{{MDNSidebar}}</div> + +<p>在任何重大规模上为MDN文档作出贡献的主要部分是知道如何作为MDN社区的一部分工作。本文提供的技巧可帮助您充分利用与其他作者和开发团队的互动。</p> + +<h2 id="一般礼仪准则">一般礼仪准则</h2> + +<p>以下是在Mozilla社区工作时的一些通用指导原则。</p> + +<ul> + <li> 要有礼貌！即使意见不一致，我们都有相同的使命：网络的改善。 </li> + <li>问，不要求。当你礼貌地请求帮助而不是要求帮助时，人们更有可能会对他们有帮助和回应。尽管文档工作很重要，而且我们的开发团队知道它，但是如果不尊重它们，人类的本能往往会导致人们磨损和困难。 </li> + <li>平衡您对信息的需求和文档的紧迫性以及您讨论中的其他人必须致力于帮助您的时间。如果马上不是绝对必要的话，不要一直推动越来越多的细节，以至于让参与谈话的其他人变得疯狂。 </li> + <li>请记住，您的请求需要宝贵的时间从您联系的人，所以一定要充分利用他们的时间。 </li> + <li>体谅文化差异。 Mozilla是一个跨国和多元文化的团队，因此当与某个文化与自己或不同的人交谈时，务必在沟通时牢记这一点。 </li> + <li>开始一个新的谈话，而不是劫持现有的谈话。不要将你的问题注入无关的对话中，因为你需要与之交谈的人正在关注它。虽然对您很方便，但这可能会刺激您想要与之交谈的人，并导致不理想的结果。 </li> + <li>避免 {{interwiki("wikipedia", "bikeshedding")}}。不要让你的热情变得恼人的琐事。它使对话变得繁琐而不重要。</li> +</ul> + +<h2 id="委婉">委婉</h2> + +<p>与他人沟通时要时刻保持委婉和恭敬。</p> + +<h3 id="礼貌地指出错误">礼貌地指出错误</h3> + +<p>如果您在联系某人的目的是要求他们采取不同的做法，或者指出他们所犯的错误（特别是他们反复犯错的话），请以正面评论开始您的信息。这可以减轻打击，这可以说，它表明你试图帮助，而不是让你成为坏人。 例如，如果一个新的贡献者创建了大量没有标签的页面，并且您想要指出这个问题，那么您给他们的消息可能看起来像这样（您需要为每个个案更改的内容加下划线):</p> + +<blockquote> +<p>嗨，<u>MrBigglesworth</u>，我一直注意到你对<u>Wormhole API文档</u>的贡献，并且能够得到你的帮助真是太棒了！我特别喜欢<u>你通过可读性平衡细节水平的方式</u>。尽管如此，如果您<u>在页面中添加正确的标签</u>，您可以使这些文章更好，更有用。</p> + +<p><u>详细信息，请参阅MDN标记指南 (https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Tag) 。</u></p> +</blockquote> + +<h2 id="分享知识">分享知识</h2> + +<p>在您参与MDN项目时，了解发生了什么以及与我们社区的其他成员进行互动很有用。通过与我们社区中的其他人交谈，您可以获得并分享想法，状态更新等。我们还拥有工具和信息资源，可以帮助您了解由谁来完成的工作。</p> + +<h3 id="沟通渠道">沟通渠道</h3> + +<p>您可以通过多种方式与社区成员（开发人员或作者）进行交流，每种方式都有自己特定的礼仪规则。</p> + +<h4 id="Bugzilla">Bugzilla</h4> + +<p>在编写文档以涵盖由于Bugzilla中的错误而实施的更改时，您经常会与涉及这些错误的人员进行交互。请务必始终牢记Bugzilla礼仪指南！</p> + +<h4 id="电子邮件">电子邮件</h4> + +<p>有时候，如果你有他们的电子邮件地址，你和一个或多个其他人之间的私人电子邮件交换就是要走的路。</p> + +<div class="note"> +<p>注意：一般来说，如果有人在您要记录的技术文档上发布了他们的电子邮件地址，已经亲自给您发送了他们的电子邮件地址，或者通常有一个众所周知的电子邮件地址，则电子邮件是可接受的“第一次联系人”做法。如果你需要挖掘它，你可能应该首先尝试获得IRC或邮件列表的许可，除非你已经用尽了所有其他尝试取得联系的努力。</p> +</div> + +<h3 id="Content_status_tools">Content status tools</h3> + +<p>We have several useful tools that provide information about the status of documentation content.</p> + +<dl> + <dt><a href="/dashboards/revisions">Revision dashboard</a></dt> + <dd>The revision dashboard provides a fantastic tool to review changes made to MDN content. You can see recent history, choose a range of time to view, and filter based on things like locale, contributor's name, and topic. Once you're looking at a set of revisions, you can view the changes made in each revision, quickly open the page, see a full history, or even revert the changes (if you have those privileges).</dd> + <dt><a href="https://developer.mozilla.org/en-US/docs/MDN/Doc_status/Overview">Documentation status overview</a></dt> + <dd>Our <a href="https://developer.mozilla.org/en-US/docs/MDN/Doc_status/Overview">documentation status overview</a> page provides a list of all the areas of MDN that have been configured for status tracking, with information about how many pages therein need different types of work done. Click through to a particular topic area to see detailed lists of content that needs work, such as pages that have no tags, or are tagged with indicators that certain types of work need to be done. You can even see lists of pages that haven't been updated in a long time and may be out of date, as well as a list of bugs that have been flagged as impacting the documentation in that area.</dd> + <dt><a href="/en-US/docs/MDN/Plans">Documentation project plans</a></dt> + <dd>We have a number of writing projects that are in the planning stages, or are large and ongoing, for which we have written planning documents to help us keep track of what we need to get done.</dd> + <dt><a href="https://tree.taiga.io/project/viya-mdn-durable-team">MDN Taiga</a></dt> + <dd>The MDN staff writers use a tool called Taiga to manage current and future documentation projects. You can take a look to see what we're doing and how it's going, and you can see what projects we'd like to see happen soon. Some of those will be taken on by staff writers, but you should feel free to take one over if you like! For more information about the agile processes followed by the MDN team, see our <a href="https://wiki.mozilla.org/Engagement/MDN_Durable_Team/Processes">Process page on the Mozilla wiki</a>.</dd> +</dl> + +<h2 id="The_development_community">The development community</h2> + +<p>Possibly the most important relationships to develop and maintain, as a member of the MDN writing community, are those you develop and sustain with the developers. They create the software we're developing, but they're also the most useful source of information we have. It's crucial that we maintain good relations with developers—the more they like you, the more likely they are to answer your questions quickly, accurately, and thoroughly!</p> + +<p>In addition, you represent the MDN writing community. Please help ensure we keep our excellent working relationship with the dev team by making every interaction they have with the writing team be a good one.</p> + +<p>On a related note, a great way to find the right person to talk to is to look at the <a href="https://wiki.mozilla.org/Modules">module owners lists</a>.</p> + +<h2 id="The_writing_community">The writing community</h2> + +<p>The writing community is a large one. While the number of extremely frequent, or large-scale contributors is relatively small, there are many dozens or hundreds of people who contribute at least now and then. Fortunately, these are by and large awesome people with a genuine love of the Web, Mozilla, and/or documentation, and interacting with them is almost always pretty easy.</p> + +<p>See the article <a href="/en-US/docs/MDN/Community" title="/en-US/docs/Project:MDN/Contributing/Join_the_community">Join the community</a> for more information about the MDN community.</p> + +<p>The most frequent place you'll directly interact with other writers is in the {{IRCLink("mdn")}} channel on IRC. This channel is specifically reserved for discussing documentation. For IRC-specific etiquette tips, see the Mozilla Support article "<a href="https://quality.mozilla.org/docs/misc/getting-started-with-irc/" title="https://quality.mozilla.org/docs/misc/getting-started-with-irc/">Getting Started with IRC</a>." You'll also have discussions with us on the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a>. In general, IRC tends to be used for quick, more in-person-like discussions, while the discussion forum is typically used for longer-duration conversation.</p> + +<p>By keeping in mind the {{anch("General etiquette guidelines")}}, you'll find that usually things go very smoothly.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Project:MDN/Contributing" title="/en-US/docs/Project:MDN/Contributing">Contributing to MDN</a></li> + <li><a href="/en-US/docs/Project:MDN/Contributing/Join_the_community" title="/en-US/docs/Project:MDN/Contributing/Join_the_community">MDN community</a></li> + <li><a href="http://matt.might.net/articles/how-to-email/" title="http://matt.might.net/articles/how-to-email/">How to send and reply to email</a></li> + <li><a href="http://blog.gerv.net/2012/10/how-to-be-a-mozillia/">How to be a Mozillian</a></li> +</ul> diff --git a/files/zh-cn/mdn/community/角色/index.html b/files/zh-cn/mdn/community/角色/index.html new file mode 100644 index 0000000000..e9ceeacc0b --- /dev/null +++ b/files/zh-cn/mdn/community/角色/index.html @@ -0,0 +1,12 @@ +--- +title: 社区的角色 +slug: MDN/Community/角色 +tags: + - Community + - Landing + - MDN Meta +translation_of: MDN/Community/Roles +--- +<div>{{MDNSidebar}}</div><p>在MDN社区中有多种类型的角色，每个角色都有明确的职责。</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/zh-cn/mdn/contribute/feedback/index.html b/files/zh-cn/mdn/contribute/feedback/index.html new file mode 100644 index 0000000000..1eb0e71883 --- /dev/null +++ b/files/zh-cn/mdn/contribute/feedback/index.html @@ -0,0 +1,46 @@ +--- +title: 发送有关MDN Web Docs的反馈 +slug: MDN/Contribute/Feedback +tags: + - 公用 +--- +<div>{{MDNSidebar}}</div> + +<p>欢迎来到 Mozilla 开发者网络！如果你现在遇到了一些问题，或者想要给我们提一些建议，那么你来对地方了。在事实上，向我们提供反馈会使你更接近 Mozilla 社区中的一员，我们提前祝贺你。</p> + +<p>你可以使用本文下方提到的方式来发表你自己的看法。</p> + +<h2 id="更新文档">更新文档</h2> + +<p>首先，如果你发现某篇文档存在问题，首先应该尝试自己能否修正它。你只需登录，然后点击蓝色的"编辑"按钮打开编辑器，就可以编辑那份文档了。这里的所有文档都是以 wiki 为形式，它们是由一些 Mozilla 员工和志愿者共同维护的，你不用担心犯错，你在编辑文档时的用语也并非必须完全正确。如果你弄错什么，我们会发现和修复它，完全ok！</p> + +<p>想要了解更多有关如何贡献 MDN 文档的知识，请查看：</p> + +<ul> + <li><a href="/zh-CN/docs/Project:Getting_started" title="/zh-CN/docs/Project:Getting_started">开始行动</a></li> + <li><a href="/zh-CN/docs/Project:How_to_Help" title="/zh-CN/docs/Project:How_to_Help">我该如何提供帮助</a></li> + <li><a href="/zh-CN/docs/Project:MDN_editing_interface" title="/zh-CN/docs/Project:MDN_editing_interface">MDN编辑接口</a></li> +</ul> + +<h2 id="加入讨论组">加入讨论组</h2> + +<p>我们使用互联网中继聊天（IRC）系统来讨论关于 MDN 的所有事情。你可以加入我们！根据你感兴趣的领域不同，我们有几个频道可供你选择：</p> + +<dl> + <dt><a href="irc://irc.mozilla.org/mdndev" title="/zh-CN/docs/">开发者文档内容(#devmo)</a></dt> + <dd>#devmo 频道用来讨论与实际的文档内容有关的话题。如果你有和某篇文档相关的问题，想察看某些方面的文档，或者想自己写一些新的文档，都可以来这里与我们交流。</dd> + <dt><a href="irc://irc.mozilla.org/mdn" title="irc://irc.mozilla.org/mdn">MDN网站(#mdn)</a></dt> + <dd>这个频道讨论关于 MDN 的任何事情。如果你不确定应该去哪个频道寻求帮助，或者不知道你具体遇到了哪个方面的问题，可以在这里提问。</dd> + <dt><a href="irc://irc.mozilla.org/mdndev" title="irc://irc.mozilla.org/mdndev">文档站点开发(#mdndev)</a></dt> + <dd>#mdndev 频道是我们讨论 MDN 网站所使用的这个 wiki 系统（名为 kuma）的地方。如果网站本身的功能遇到了问题，或者你有一些好点子能让这个系统变得更好，那么就加入我们的讨论吧。</dd> +</dl> + +<h2 id="报告一个问题">报告一个问题</h2> + +<h3 id="文档问题">文档问题</h3> + +<p>如果你在某个文档中发现了任何的错误，但又无法自己修复，那么你就可以<a href="https://bugzilla.mozilla.org/enter_bug.cgi?alias=&assigned_to=nobody%40mozilla.org&blocked=&bug_file_loc=http%3A%2F%2F&bug_severity=normal&bug_status=NEW&comment=&component=General&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&defined_groups=1&dependson=&description=&flag_type-4=X&flag_type-607=X&flag_type-791=X&flag_type-800=X&form_name=enter_bug&keywords=&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=--&product=Developer%20Documentation&qa_contact=&rep_platform=All&requestee_type-4=&requestee_type-607=&requestee_type-791=&requestee_type-800=&short_desc=&status_whiteboard=&target_milestone=---&version=unspecified" title="https://bugzilla.mozilla.org/enter_bug.cgi?alias=&assigned_to=nobody%40mozilla.org&blocked=&bug_file_loc=http%3A%2F%2F&bug_severity=normal&bug_status=NEW&comment=&component=General&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&defined_groups=1&dependson=&description=&flag_type-4=X&flag_type-607=X&flag_type-791=X&flag_type-800=X&form_name=enter_bug&keywords=&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=--&product=Developer%20Documentation&qa_contact=&rep_platform=All&requestee_type-4=&requestee_type-607=&requestee_type-791=&requestee_type-800=&short_desc=&status_whiteboard=&target_milestone=---&version=unspecified">把这个问题报告给我们</a>！谢谢</p> + +<h3 id="网站问题">网站问题</h3> + +<p>如果你遇到了一些 MDN 网站本身的问题，或者有一些能改进MDN系统的好点子，可以到 Mozilla 的 Bugzilla 系统上<a href="https://bugzilla.mozilla.org/enter_bug.cgi?alias=&assigned_to=nobody%40mozilla.org&blocked=&bug_file_loc=http%3A%2F%2F&bug_severity=normal&bug_status=NEW&comment=&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&defined_groups=1&dependson=&description=&flag_type-4=X&flag_type-607=X&flag_type-791=X&flag_type-800=X&form_name=enter_bug&keywords=&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=--&product=Mozilla%20Developer%20Network&qa_contact=website%40mdn.bugs&rep_platform=All&requestee_type-4=&requestee_type-607=&requestee_type-791=&requestee_type-800=&short_desc=&status_whiteboard=&target_milestone=---&version=unspecified" title="https://bugzilla.mozilla.org/enter_bug.cgi?alias=&assigned_to=nobody%40mozilla.org&blocked=&bug_file_loc=http%3A%2F%2F&bug_severity=normal&bug_status=NEW&comment=&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&defined_groups=1&dependson=&description=&flag_type-4=X&flag_type-607=X&flag_type-791=X&flag_type-800=X&form_name=enter_bug&keywords=&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=--&product=Mozilla%20Developer%20Network&qa_contact=website%40mdn.bugs&rep_platform=All&requestee_type-4=&requestee_type-607=&requestee_type-791=&requestee_type-800=&short_desc=&status_whiteboard=&target_milestone=---&version=unspecified">提交一个请求</a>。 </p> diff --git a/files/zh-cn/mdn/contribute/getting_started/index.html b/files/zh-cn/mdn/contribute/getting_started/index.html new file mode 100644 index 0000000000..76ae0b45db --- /dev/null +++ b/files/zh-cn/mdn/contribute/getting_started/index.html @@ -0,0 +1,129 @@ +--- +title: 初识 MDN +slug: MDN/Contribute/Getting_started +tags: + - MDN元数据 + - MDN入门 + - 入门 + - 初学者 +translation_of: MDN/Contribute/Getting_started +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p id="What_is_MDN.3F"><span class="seoSummary">我们是一个由开发者和作者组成的开源社区，目的是为了建设一个更美好的网络，不论品牌、浏览器或平台。任何人都可以参与，每个人的贡献都会让我们更强大。我们可以一起继续推动 Web 创新服务于更广泛的利益。我们和你一起在这里开始。</span></p> + +<p>MDN 的每一个部分（文档，演示，和网站本身）都是由一个开放的开发者社区创建的。任何人都可以贡献自己的力量，请加入我们吧！</p> + +<h2 id="简单三步参与_MDN">简单三步参与 MDN</h2> + +<p>MDN（<em>Mozilla Developer Network</em>）是一个 wiki，这意味着<strong>任何人</strong>都可以向其添加和编辑内容。你不一定非得是一个程序员，或了解许多涉及技术方面的知识，才能参与进来。这里有很多任务，从简单的（如校对和纠正拼写）到复杂的（如撰写 API 文档），都等待着我们去完成。</p> + +<p>做贡献很容易，也没有什么风险。即使你犯了一个错误，别人也能很容易更正它。即使你不知道该做什么，或者你的语法不是很好，别担心！我们有一个团队，这个团队的工作就是使 MDN 的内容尽善尽美。总会有人来再看一眼，确保你的文档是整洁且符合标准的。所以，请在此分享你的知识，发挥你的所长，在大家的共同努力下，MDN 只会越来越好。</p> + +<h3 id="步骤_1：创建一个_MDN_账号">步骤 1：创建一个 MDN 账号</h3> + +<p>在开始给 MDN 贡献自己的知识前，你需要有一个 MDN 帐号。详细信息请参阅<a href="/zh-CN/docs/MDN/Contribute/Howto/Create_an_MDN_account">如何创建一个帐户</a>。</p> + +<h3 id="步骤_2：选择一个任务">步骤 2：选择一个任务</h3> + +<p>现在你已经登录，在{{anch("可选的任务类型", "下面的列表")}}里阅读有关不同任务的描述，并决定哪一个任务是最吸引你的。你可以选择任何你喜欢的任务并开始贡献你的知识。</p> + +<h3 id="步骤_3：做任务">步骤 3：做任务</h3> + +<p>一旦你决定了想做什么任务，找一个具体的页面、示例代码等等就开动吧，尽管去做！</p> + +<p>别担心做得是否完美，其他的 MDN 贡献者会来帮助修复那些错漏。如果你想尝试一下在 MDN 上编辑内容的感觉，或想在“真的做”一些事情之前实验一下，你可以在<a href="/en-US/docs/Sandbox">沙盒</a>页面上练练手。如果你有疑问，请到<a href="/zh-CN/docs/MDN/Community">交流社区</a>页面获取邮件列表和在线聊天频道，在那里你可以找到答案。</p> + +<p>完成任务之后，若恰巧时间空闲，你可以选择另一个项任务，或者看看下面<a href="#其它你可以在MDN上做的事情">其它你可以在 MDN 上做的事情</a>。</p> + +<h2 id="可选的任务类型">可选的任务类型</h2> + +<p>基于你的技能和兴趣，你有很多方法可以帮助到 MDN。尽管一些任务可能是艰巨的，但同时我们也有很多相对简单的任务。很多只需要五分钟（或更少！）。通过做任务和阅读它的简短描述，你会发现每一种类型的任务通常都是需要近似的时间的。</p> + +<h3 id="选项_1：我喜欢文字">选项 1：我喜欢文字</h3> + +<p>你可以帮我们审核或编辑现有的文档，并对它们应用正确的标签。</p> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Set_the_summary_for_a_page">设置一个页面的摘要</a>（5 - 15 分钟）</li> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Do_an_editorial_review">编辑评论</a>（5 - 30 分钟）</li> + <li><a href="/zh-CN/docs/MDN/User_guide/Writing#Editing_an_existing_page">使用新的信息更新现有的文章</a>（5 分钟 - 1 小时）</li> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary">在术语表里新增一个条目</a>（15 分钟 - 1 小时）</li> + <li><a href="/zh-CN/docs/MDN/User_guide/Writing#Adding_a_new_page">为新的技术或 API 写一篇文章</a>（30 分钟 - 2 小时）</li> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web">写一篇文章，帮助人们了解 Web</a>（1 - 3 小时）</li> +</ul> + +<div class="note"> +<p><strong>注意：</strong>在你审查已有的文章或者编写新的文章之前，最好先看一下我们的<a href="/zh-CN/docs/Project:MDN/Style_guide">风格指南</a>，这有助于保证大家写出的文章的风格是一致的。</p> +</div> + +<h3 id="选项_2：我喜欢代码">选项 2：我喜欢代码</h3> + +<p>我们需要更多的代码示例！你也可以帮助构建我们的网站平台 —— <a href="https://developer.mozilla.org/zh-CN/docs/MDN/Kuma">Kuma</a>！</p> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Convert_code_samples_to_be_live">将示例代码转换为“实时的”</a>（30 分钟）</li> + <li><a href="https://kuma.readthedocs.io/en/latest/installation.html">建立一个 Kuma 的编程环境</a>（1 小时）</li> + <li><a href="https://github.com/mozilla/kuma#readme">发送你的代码补丁到 Kuma 的代码库</a>（1 小时）</li> + <li><a href="https://wiki.mozilla.org/Webdev/GetInvolved/developer.mozilla.org">提交新的 Demo</a>（1 小时）</li> +</ul> + +<h3 id="选项_3：我喜欢文字和代码">选项 3：我喜欢文字和代码</h3> + +<p>我们有需要的技术和语言技能的任务，像写新文章，审查技术的准确性，或改编文档等。</p> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Tag_JavaScript_pages">给 JavaScript 页面添加标签</a> （5 分钟）</li> + <li><a href="/zh-CN/docs/MDN/Promote">在你自己的网站上推广 MDN</a>（5 分钟）</li> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Do_a_technical_review">技术评论</a>（30 分钟）</li> + <li><a href="/zh-CN/docs/MDN/Contribute/Contribute_to_docs_that_are_currently_needed">写一篇关于你感兴趣的话题的文章</a>（1 小时及以上）</li> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/学习_交互_在线_起步_开始">创建互动练习以帮助人们了解 Web</a>（1 小时及以上）</li> + <li>从<a href="http://www.joshmatthews.net/bugsahoy/?mdn=1"> Bug Ahoy 的 MDN 目录</a>中<a href="/en-US/docs/MDN/Contribute/Howto/Resolve_a_mentored_developer_doc_request">修复一个文档 bug</a> （1 小时及以上）</li> +</ul> + +<h3 id="选项_4：我想翻译_MDN">选项 4：我想翻译 MDN</h3> + +<p>所有的本地化与翻译工作是由我们优秀的MDN社区志愿者做的。</p> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Localize/Translating_pages">翻译页面</a>（2小时）（<a href="/zh-CN/docs/MDN/Doc_status/l10nPriority">查看优先级</a>）</li> + <li>连接其它在<a href="/zh-CN/docs/MDN/Contribute/Localize/Localization_projects">本地化项目</a>里列出的本地化人员名单（30分钟）</li> +</ul> + +<h3 id="选项_5_我发现了一些错误的信息，但我不知道该怎样修复它">选项 5: 我发现了一些错误的信息，但我不知道该怎样修复它</h3> + +<p>你可以在 <a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Mozilla%20Developer%20Network">Bugzilla 上提交 </a><a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Mozilla%20Developer%20Network">bug</a>。（5分钟）</p> + +<table class="standard-table"> + <tbody> + <tr> + <td><strong>Bugzilla</strong>字段</td> + <td>内容</td> + </tr> + <tr> + <td>产品</td> + <td><a href="https://bugzilla.mozilla.org/enter_bug.cgi?product=Developer+Documentation">开发者文档 </a></td> + </tr> + <tr> + <td>组件</td> + <td>选择一个适合其主题的范围。当你不确定或者没有找到合适的主题时，可以选择“General”</td> + </tr> + <tr> + <td>URL</td> + <td>你发现问题的页面</td> + </tr> + <tr> + <td>描述</td> + <td>请尽你所能的去描述这个问题，并且谈谈在何处能找到正确的解决方案。这一内容既可以是其他人（交谈中涉及到的），也可以是网页链接</td> + </tr> + </tbody> +</table> + +<h2 id="其它可以在_MDN_上做的事情">其它可以在 MDN 上做的事情</h2> + +<ul> + <li><a href="/zh-CN/docs/Project:en/Project:Community">加入 MDN 社区</a>。</li> + <li><a href="/zh-CN/profile">填写你的个人资料</a>以便其他人能更了解你。</li> + <li>了解更多关于如何<a href="/zh-CN/docs/MDN/Contribute">贡献 MDN</a>。</li> + <li><a href="/zh-CN/docs/MDN/Getting_started/Using_MDN_in_education">使用 MDN 进行学习</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/convert_code_samples_to_be_live/index.html b/files/zh-cn/mdn/contribute/howto/convert_code_samples_to_be_live/index.html new file mode 100644 index 0000000000..243f6b29a7 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/convert_code_samples_to_be_live/index.html @@ -0,0 +1,30 @@ +--- +title: 如何将代码示例转换成“实时的” +slug: MDN/Contribute/Howto/Convert_code_samples_to_be_live +translation_of: MDN/Contribute/Howto/Convert_code_samples_to_be_live +--- +<div>{{MDNSidebar}}</div><p class="summary">MDN 拥有一套 "<a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">live sample</a>" 系统，在那里页面上展示的代码示例将被直接使用，以显示该示例的输出结果。然而，许多现有文章的代码示例还没有使用这套系统，它们需要被转换。</p> + +<p><span class="seoSummary">实样让你可以看到示例输出的样子，让文档生动有益。这篇指南涵盖如何获取现有示例并添加上“实时的”功能性。</span></p> + +<dl> + <dt>哪里需要完成它？</dt> + <dd>标记有 <a href="/en-US/docs/tag/NeedsLiveSample">NeedsLiveSample</a> 的文章。</dd> + <dt><strong>做这项任务你需要知道哪些？</strong></dt> + <dd> + <ul> + <li>基于代码示例，对 HTML, CSS 和/或 JavaScript 的理解。</li> + <li>能够在 MDN 文章中使用 <a href="/en-US/docs/MDN/Contribute/Tools/KumaScript">KumaScript</a> 宏。</li> + </ul> + </dd> + <dd><strong>做这项任务的步骤是什么？</strong></dd> + <dd> + <ol> + <li>从标记 <a href="/en-US/docs/tag/NeedsLiveSample">NeedsLiveSample</a> 的文章列表中选取一篇文章，这篇文章里的代码示例是你熟悉的。</li> + <li>转换代码示例为“实例的”。</li> + <li>删除之前用于显示示例输出结果的任何代码或图像。</li> + </ol> + </dd> +</dl> + +<p>关于创建和编辑实样的更多信息，见 <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Using the live sample system</a></p> diff --git a/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html b/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html new file mode 100644 index 0000000000..256d61b897 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html @@ -0,0 +1,44 @@ +--- +title: 如何创建 MDN 账号 +slug: MDN/Contribute/Howto/Create_an_MDN_account +tags: + - MDN + - 创建账户 + - 初学者指南 + - 新手上路 +translation_of: MDN/Contribute/Howto/Create_an_MDN_account +--- +<div>{{MDNSidebar}}</div> + +<p> <span class="seoSummary">要对MDN的内容进行任何更改，你需要一个<strong>MDN</strong>账户。别担心，如果你只是打算阅读或搜索MDN，就不需要一个账户！这个指南 将帮助你建立MDN账户。</span></p> + +<div class="pull-aside"> +<div class="moreinfo"> +<p><strong>为什么MDN需要我的电子邮件地址？</strong></p> + +<p>你的电子邮件地址用于帐户恢复；必要时，MDN管理员会通过它来联系您，讨论你的账户或在网站上的活动。</p> + +<p>此外，你可以选择订阅通知（例如，<a href="/zh-CN/docs/MDN/Contribute/Howto/Watch_a_page">当特定的页面被更改</a>）和消息（例如，如果你选择加入我们的beta测试团队，你可能会收到关于待测试新功能的邮件）。</p> + +<p>你的电子邮件地址永远不会显示在MDN，并只会按照我们的<a href="https://www.mozilla.org/privacy/websites/">隐私政策</a>使用。</p> + +<div class="note">如果你通过Github登录到MDN，并且你的Github账号使用了“noreply”的电子邮件地址，你将<em>不会</em>收到任何来自MDN的信息（包括你从页面订阅的通知）。</div> +</div> +</div> + +<ol> + <li>在每个MDN页面的顶部都有一个<strong>登录</strong>按钮。将鼠标指向它（如果你在移动设备上使用，轻触即可），以显示支持的登录到MDN的认证服务列表。</li> + <li>选择一项服务以登录。目前，我们只支持使用Github登录。值得注意的是如果你选择GitHub，你的MDN公开资料页上将显示一个链接，其指向你的GitHub个人资料页。</li> + <li>按照Github的提示，将你的GitHub帐户绑定到MDN。</li> + <li>从认证服务页面返回到MDN之后，MDN会提示你输入用户名和电子邮件地址。<em>你的用户名会公开显示，以便展示你做过的工作。请不要将你的电子邮件地址作为用户名</em>。</li> + <li>点击<strong>创建我的MDN个人资料</strong>。</li> + <li>如果你在步骤4中指定的电子邮件地址与认证服务所使用的不同，请检查<em>这个</em>邮箱，并点击我们发送的确认邮件中的链接。</li> +</ol> + +<p>一切就绪！你已经拥有一个MDN帐户，并可以立即编辑页面！</p> + +<p>你可以在任何MDN页面的顶部点击你的名字以查看账号的公开资料。从那里，你可以点击<strong>编辑</strong>按钮修改或更新你的个人资料。</p> + +<div class="note"> +<p>注：新用户名不能包含空格或“@”字符。请记住，你的用户名将会公开显示，以标识你做过的工作！</p> +</div> diff --git a/files/zh-cn/mdn/contribute/howto/create_and_edit_pages/index.html b/files/zh-cn/mdn/contribute/howto/create_and_edit_pages/index.html new file mode 100644 index 0000000000..57f573339d --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/create_and_edit_pages/index.html @@ -0,0 +1,186 @@ +--- +title: 如何创建及编辑页面 +slug: MDN/Contribute/Howto/Create_and_edit_pages +tags: + - 指南 + - 新手 + - 简介 +translation_of: MDN/Contribute/Howto/Create_and_edit_pages +--- +<h2 id="测试页面">测试页面</h2> + +<p><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Community">需要帮助？</a> • <a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Editor">编者指南</a> • <a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Content/Style_guide">风格指南</a></p> + +<p>如何编辑一个页面: </p> + +<ol> + <li>登陆 MDN Web Docs 账号，若未注册请注册。</li> + <li>如果你在只读版本的 MDN Web Docs（https://developer.mozilla.org），点击点击页面右上角的 <strong>Edit in wiki（在 wiki 编辑）</strong>按钮。这将带你进入可编辑的，wiki 版本的网页（https://wiki.developer.mozilla.org），但是这并没有真正地打开可编辑的界面。</li> + <li>请点击 wiki 页面文章标题旁的 <strong>编辑</strong> 按钮<strong>。</strong></li> + <li>页面会重新加载具有规定格式的编辑页面，你可以直接在页面上新增或者删除内容。</li> + <li>你可以新增段落，删除文本，插入标题，并且执行更多涉及编写和编辑的功能。</li> +</ol> + +<p>通过查看<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor">MDN Editor guide</a>里的<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics">Editor UI elements</a>获得更多关于MDN内置编辑器的信息。</p> + +<h3 id="预览修改">预览修改</h3> + +<p>查看你修改的内容：</p> + +<ul> + <li>点击文章标题上方的"<strong>Preview</strong>"（<strong>预览</strong>）按钮（在编辑模式下）。</li> + <li>这会在新窗口或新标签页中打开一个修改过的预览页。</li> + <li>每次点击按钮，预览页都会刷新到最新的状态。</li> +</ul> + +<p>注意！预览页面并<strong>不会</strong>保存你的修改内容，所以你在关闭编辑的页面前必须保存你的修改。</p> + +<h3 id="版本注释">版本注释</h3> + +<p>当预览修改之后，你需要保存你的修改版本。在<strong>保存</strong>之前，查看页面文章下方的版本注释栏，留下一些注释信息来告诉其它贡献者你为什么要去修改它。例如，你可能新增加了一个章节，或修改了一些文字来使得术语表述的更加一致，亦或重构了一个段落使其语言更加易于理解，或者就是删除了一些冗余信息。</p> + +<h3 id="目录">目录</h3> + +<p>一篇文章的“在本文中”部分是自动生成的页面上标题的链接列表。这些链接的措词可以通过编辑标题进行编辑。也可以通过选择“编辑页面标题和属性”和改变“TOC”下拉列表的值，从而删除目录，或减少链接数量。</p> + +<h3 id="标签">标签</h3> + +<p>你可以新增或删除编辑区域下面的一些描述页面内容或者功能的标签。查看 <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Tagging">如何正确标记页面</a> 来了解如何为页面添加合适的标签。</p> + +<h3 id="需要复核？">需要复核？</h3> + +<p>保存之前，为了确保信息的准确性，你可以勾选技术复核（针对代码，API，或技术），编辑复核（针对文章，语法，和内容），或模板复核（针对KumaScript code）的选择框，来让专家或有经验的贡献者复核你的编辑信息。</p> + +<h3 id="附件">附件</h3> + +<p>如果你想<strong>附加某个文件</strong>到一个现有的页面中来添加插图或作进一步说明的话，你可以在页面底部输入。当你上传图片时，请确保使用图片优化工具进行优化，以便我们的图片足够小，方便下载。这样便提高了页面加载速度，提升MDN的整体性能。有可能有你钟爱的工具，如果没有的话，我们推荐一款容易上手的Web工具：<a href="https://tinypng.com/">TinyPNG</a>。</p> + +<h3 id="保存，放弃更改，继续编辑">保存，放弃更改，继续编辑</h3> + +<p>当你完成编辑，并确认过预览界面，你可以点击标题右边或者文章底部的的绿色按钮<strong>“发布修改”</strong>来发布你的文章和注释。如果你想要继续编辑，可以选择点击按钮<strong>“发布并继续编辑”</strong>来保证在保存编辑的同时不离开编辑模式。</p> + +<p>如果你改变主意，你也可以点击页面右侧的红色按钮<strong>“放弃”</strong>来放弃你的编辑，注意放弃更改是不可撤销返回的。</p> + +<p>在版本注释区域点击 <strong>Enter 键</strong>和点击按钮<strong>“发布并继续编辑”</strong>具有相同的效果。</p> + +<div class="blockIndicator note"> +<p><strong>注意：</strong>当你尝试保存你编辑好的页面时发现你的编辑被视为无效操作而被拒绝了，若你编辑好的内容又确实是适合MDN的，此时你可以向<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/mdn-admins@mozilla.com">MDN管理团队</a>发送邮件来获得帮助。</p> +</div> + +<h2 id="获取新建页面的许可">获取新建页面的许可</h2> + +<p>出于对安全的考虑，最近创建的MDN账号是没有权限新建页面的。如果你尝试这样做，你将看到一个页面引导你如何创建新页面。有以下两种可选的方式：</p> + +<ul> + <li><strong>请别人帮你创建。</strong>为此，请您提供一份<a href="https://bugzilla.mozilla.org/enter_bug.cgi?bug_file_loc=http%3A%2F%2F&bug_ignored=0&bug_severity=normal&bug_status=NEW&cf_fx_iteration=---&cf_fx_points=---&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&flag_type-4=X&flag_type-607=X&flag_type-800=X&flag_type-803=X&form_name=enter_bug&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=Unspecified&priority=--&product=Developer%20Documentation&rep_platform=Unspecified&short_desc=Create%20page%3A%20&status_whiteboard=create-page&target_milestone=---&version=unspecified">用于提出 bug 的申请书</a>，并且以 "Create page: <页面标题>" 为主题。如果您知道该页面应该放在 MDN 中的什么位置，请确保填写好一个 URL 来描述该位置。您还应该注明您为何需要创建该页面。</li> + <li><strong>申请页面创建权限。</strong>如果您申请了页面创建权限且得到了授权，您将可以根据下述的指南自行创建新页面。为了请求该权限，请您将申请书通过电子邮件<a href="mailto:mdn-admins@mozilla.org">发送给 MDN 管理团队</a>。请确保申请书的内容涵盖了您的用户名，以及为什么您有能力创建一个新页面（比方说：您正在编制一份新的 API 文档，该文档涉及许多新页面，又或者您想添加一些新条目到术语表）。您还应该曾经为该网站的内容作出过许多有益贡献，并且成为贡献者应该已经有一段时日了（至于这段时日有多久，这并没有一个固定期限，因为还需要同时考虑其他的因素）。</li> +</ul> + +<h2 id="新建一个页面">新建一个页面</h2> + +<p>当你拥有创建新页面的权限之后，你就可以开始创建页面了。</p> + +<p>找不到在哪里新建一个页面？<strong>别担心！</strong>你可以在任何地方新建一个页面，我们会找到它并把它归档或者合并到最合适的类别下。你也不用过多担心它不够完美，我们有热心的志愿者来帮你打理，让你的文章保持干净美观。 </p> + +<p>下面是一些新建页面的方法：</p> + +<ul> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Missing_page_link">已有网页上的“缺失页面”链接</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#New_page_without_link">不需要链接的新页面</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Subpage_of_an_existing_page">在现有页面下新增子页面</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Clone_of_an_existing_page">克隆已存在的页面</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$revision/1425373#Link_from_an_existing_page">从已存在页面创建链接</a></li> +</ul> + +<h3 id="“缺失页面”链接">“缺失页面”链接</h3> + +<p>和许多维基站点一样，在 MDN 也有可能创建一个链接，它指向一个尚不存在的页面。例如：一个作者可能创建了一个清单页面，该页面涵盖了某个API的所有成员，而这些成员对应的页面还没创建好。在 MDN，指向到缺失页面的链接通常显示为红色。</p> + +<p>从“缺失页面”链接创建对应的页面需要：</p> + +<ol> + <li>确认已登录进 MDN，并且拥有新建页面的权限。（若未登录就点击“缺失页面”链接，会得到一个404（找不到页面）的错误。）</li> + <li>点击“缺失页面”链接。如果你拥有页面创建权限，<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor">MDN编辑器界面</a>会自动打开，准备好让你创建缺失的页面。</li> + <li>编写页面内容，然后保存。</li> +</ol> + +<h3 id="不需要链接的新页面">不需要链接的新页面</h3> + +<p>想要创建一个没有链接到其他页面的新页面时，你需要在你的浏览器中键入一个包含新页面名字段的URL。例如，如果你键入以下URL并回车：</p> + +<pre class="notranslate"><code>https://developer.mozilla.org/en-US/docs/FooBar</code></pre> + +<p>MDN将创建一个标题为“FooBar”的新页面并且打开编辑器让你能够为新添加的页面添加内容。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在的页面</a>的小节来学习如何使用编辑器模式。</p> + +<p>要创建一个没有链接到其他页面的新页面需要：</p> + +<ol> + <li>确保您已经登陆MDN，并且拥有创建新页面的权限。</li> + <li>在您的浏览器中输入以下URL并回车。</li> +</ol> + +<pre class="notranslate"><code>https://developer.mozilla.org/en-US/docs/new</code></pre> + +<p>此时，MDN 创建新页面时有一个地方专门用来填写标题，打开编辑器后您就可以添加内容到这个新页面。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在的页面</a>的小节来学习如何使用编辑器模式。</p> + +<h3 id="已存在页面的子页面">已存在页面的子页面</h3> + +<p>在页面层次结构中的现有页面以下创建页面，需要：</p> + +<ol> + <li>在“父”页面，点击<strong>高级</strong>菜单（工具栏中的齿轮按钮），然后点击“<strong>新建子页面</strong>”。</li> + <li>打开编辑器视图以创建新文档。</li> + <li>在标题栏键入文档<strong>标题</strong>。</li> + <li>需要的话，更改 <strong>Slug</strong> 字段（例如，若标题太长而你又想用较短的URL）。该字段由编辑器自动填充，替换掉标题处的空白下划线并且只更改文档对应的URL的最后一部分。</li> + <li>在 <strong>TOC</strong> 字段，选择你想自动显示在页面目录中的标题级别，或者如果一个都不需要的话可以选择”无目录“。</li> + <li>在编辑框中编写页面内容，然后保存您的修改。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在页面</a>的小节来学习如何使用编辑器模式。</li> +</ol> + +<h3 id="克隆一个已存在的页面">克隆一个已存在的页面</h3> + +<p>如果你想应用一个已经存在的页面的版式，你可以“克隆”这个页面并且修改其内容。</p> + +<ol> + <li>在原页面中，点击<strong>高级</strong>菜单（工具栏中的齿轮按钮），然后点击“<strong>克隆此文章</strong>”，一个编辑器视图就会被打开来创建新文档。</li> + <li>更换一个合适的标题，当你在更改<strong>标题</strong>时，<strong>Slug </strong>字段会自动更新。</li> + <li> + <p>如果需要，更改 <strong>Slug</strong> 字段部分的路径，然后把新的文档放入文件夹的另一处（在大多数情况下这是没有必要的，因为克隆的页面与原始页面拥有相似的内容，因此克隆的页面应该与原始页面安排在相近的位置）。</p> + </li> + <li> + <p>在<strong>TOC</strong>字段中，选择你想让其显示在目录中的标题等级，或者选择“没有目录（No table of contents）”如果页面不需要的话。</p> + </li> + <li> + <p>在编辑面板输入页面的内容并保存您的修改。请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在页面</a>的小节来学习如何使用编辑器模式。</p> + </li> +</ol> + +<h3 id="从现有页面链接到新页面">从现有页面链接到新页面</h3> + +<p>你可以在一个现有页面创建一个链接，然后点击这个链接来创建一个新页面：</p> + +<ol> + <li>在现有页面上任意但合理的位置输入新页面的名字</li> + <li>将名字设置为高亮显示并在编辑工具栏点击<strong>链接图标<a href="https://developer.mozilla.org/files/3810/link-icon.png"><img alt="" src="https://developer.mozilla.org/files/3810/link-icon.png"></a></strong>（也可能是简洁的锁链状）。“<strong>更新链接</strong>”对话框打开，高亮的文字会被显示在“<strong>链接文本</strong>”框中。 </li> + <li>"/en-US/docs/" 会被默认添加到URL的开头。在 "/en-US/docs/" 后输入此页面的名字。当然，链接文字和新页面的标题也可以不一样。</li> + <li>点击“确认”来创建和插入这个链接。</li> +</ol> + +<p>如果这个页面不存在，这个链接将会用红色显示。如果这个页面存在，这个链接将会用蓝色显示。如果你想创建一个新的页面，但是你想创建页面的标题被占用了，请考虑是否更应该去编辑和改进这个已经存在的页面。如果您认为创建一个新页面更有必要，可以选择一个不同的标题并创建它。请参考<a href="https://developer.mozilla.org/Project:cn/Page_Naming_Guide">页面命名指南</a>获得指导。</p> + +<p>为了给您新建的页面添加内容，点击您刚刚创建的红色的链接（在保存并且关闭编辑器之后）。新的页面将进入编辑模式使您能够开始编写内容，请参考本文中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Create_and_edit_pages$edit#Editing_an_existing_page">编辑一个已存在的页面</a>的小节来学习如何使用编辑器模式。</p> + +<h2 id="刷新页面内容">刷新页面内容</h2> + +<p>由于性能上原因，MDN对KumaScript 宏指令和将一个页面嵌入另一个页面中的支持有时候会稍微被页面缓存所妨碍。页面由它们的数据源编译，并且输出会被缓存起来用来将来的页面请求。从那时起，在该页面的任何宏指令（模板）或者嵌入（使用宏<code><a href="https://developer.mozilla.org/en-US/docs/Template:Page">Page</a></code> ）将不会展现由于宏，宏的输出，或者嵌入的原本内容所引起的变化。</p> + +<ul> + <li>当想要手动刷新一个页面时，您可以在浏览器中强制刷新。MDN能够识别这个动作并且触发一个页面的重新编译，拉取一个更新过的宏输出并且传输页面内容。</li> + <li>您也可以配置页面定期的自动重新编译。除非您期望页面需要经常性的更新，否则不应这样做。参考<a href="https://developer.mozilla.org/Project:cn/Page_Regeneration">页面重新生成</a>获取更多信息。</li> +</ul> + +<h2 id="更多参考">更多参考</h2> + +<ul> + <li><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor">MDN 编辑器指南</a></li> + <li><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Content/Style_guide">MDN 编辑风格指南</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html b/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html new file mode 100644 index 0000000000..83945186c5 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html @@ -0,0 +1,57 @@ +--- +title: 如何进行技术审查 +slug: MDN/Contribute/Howto/Do_a_technical_review +tags: + - MDN Meta + - 复核 + - 如何做 + - 指南 + - 文档 +translation_of: MDN/Contribute/Howto/Do_a_technical_review +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">技术复核包括审查一篇文章的技术准确性和完整性，并在必要的时候予以纠正。 如果<span id="result_box" lang="zh-CN"><span>一篇文章</span></span>的作者需要其他人来对文章进行技术复核的话，就需要在编辑时勾选”技术复核“选项。<span id="result_box" lang="zh-CN"><span>通常情况下，作者会联系特定的工程师来执行技术审查，</span></span>但是任何具有此领域专业技能的人都可以完成技术复核。</p> + +<p><span id="result_box" lang="zh-CN"><span>本文介绍如何进行技术复核</span></span><span lang="zh-CN"><span>，从而帮助确保MDN的内容的正确性。</span></span></p> + +<h4 id="任务是什么？">任务是什么？</h4> + +<p> <span id="result_box" lang="zh-CN"><span>审查和纠正文章的技术准确性和完整性。</span></span></p> + +<h4 id="什么地方需要技术审核？">什么地方需要技术审核？</h4> + +<p> 在被标记为需要<a href="https://wiki.developer.mozilla.org/zh-CN/docs/needs-review/technical">技术审核</a>的特定文章中。</p> + +<h4 id="开始做任务前你需要了解什么？">开始做任务前你需要了解什么？</h4> + +<ul> + <li>在此篇文章技术领域的专业知识。如果你在阅读这篇文章的时候没有学到任何新知识，那么你就是这篇文章技术领域的专家。</li> + <li><span class="short_text" id="result_box" lang="zh-CN"><span>如何在MDN上编辑wiki文章</span></span></li> +</ul> + +<h4 id="完成任务的步骤是什么？">完成任务的步骤是什么？</h4> + +<ol> + <li>选取一篇需要复查的文章： + <ol> + <li>前往 <a href="https://wiki.developer.mozilla.org/zh-CN/docs/needs-review/technical">technical reviews</a> 页面。这里列出了所有需要技术复核的文章。</li> + <li>选择一个你非常熟悉的领域的页面。</li> + <li>点击该页面。</li> + </ol> + </li> + <li>在阅读这篇文章的时候注意文章里的所有技术细节：这篇文章的内容正确吗？是否缺少了一些细节？如果你觉得这篇文章不适合你，那么请毫不犹豫地换一篇文章。</li> + <li>如果没有错误，你不需要重新编辑来把这篇文章标识为”已复核“，你只需要找到左边导航栏最下方的”快速复核“框。黄色背景的框里列出了所有等待复核的请求，像这样：<img alt="" src="https://mdn.mozillademos.org/files/13016/SidebarTechReviewRequested.png" style="height: 93px; width: 321px;"></li> + <li>去掉需要技术复核前面的勾，然后点保存。</li> + <li>如果你发现了需要被修正的错误，你可以在编辑器里修改这篇文章的审核请求状态。以下是操作步骤： + <ol> + <li>点击页面顶部的编辑按钮，进入 <a href="https://developer.mozilla.org/zh-CN/docs/Project:MDN/%E8%B4%A1%E7%8C%AE/Editor_guide">MDN editor</a> 页面，来编辑该页面。</li> + <li>更正不正确的技术信息，还可以添加文章遗漏的任何重要信息。</li> + <li>在文章的底部输入修改注释。这个注释简要地描述你的修改工作，比如“完成技术审查。”如果你更正了某些信息，将它们写进你的注释，比如“技术审查以及修复参数的相关描述。”这将帮助其他贡献者和网站编辑人员知道你修改的部分以及原因。如果你认为文章中有些不必要被审查的部分，也可以在注释中提出来。</li> + <li>取消勾选“需要审查”下面的“技术”选项框了吗？它就在页面的审查注释区域。</li> + <li>点击发布按钮。</li> + </ol> + </li> +</ol> + +<p>祝贺你，你已经完成了你的第一篇技术复核，<span id="result_box" lang="zh-CN"><span>感谢您的帮助！</span></span></p> diff --git a/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html b/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html new file mode 100644 index 0000000000..48396dcd33 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html @@ -0,0 +1,55 @@ +--- +title: 如何进行编辑审核 +slug: MDN/Contribute/Howto/Do_an_editorial_review +tags: + - 指导 + - 文档 + - 编辑审核 +translation_of: MDN/Contribute/Howto/Do_an_editorial_review +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p class="summary"><strong>编辑审核</strong>的工作由修改文中排版错误，拼写、语法、用法等文本错误构成。并不是所有贡献者都是语言专家，但有了他们的共同努力，他们把那些需要编辑以及校对的文章转化为了极其有用的文章；这些都是在编辑审核的工作中完成的。</p> + +<p><span class="seoSummary">这篇文章描述了如何进行编辑审核，从而帮助实现 MDN 的内容精确。</span></p> + +<dl> + <dt>任务是什么？</dt> + <dd>编辑并审核那些被标记为需要编辑审核的文章。</dd> + <dt>应该在何处处理它？</dt> + <dd>在特定的文章中会有标记有需要编辑审核的地方。</dd> + <dt>开始做任务前你需要了解什么？</dt> + <dd>你需要有好的中文语法和词汇技能。文章复核是要确保语法、用词都是正确的并且有意义，同时遵循 <a href="/zh-CN/docs/MDN/Contribute/Content/Style_guide">MDN 样式指南</a>。</dd> + <dt>完成任务的步骤是什么？</dt> + <dd> + <ol> + <li>选择一篇文章来审核： + <ol> + <li>访问<a href="/zh-CN/docs/needs-review/editorial">需要复核的文章列表</a>。它陈列了所有请求编辑审核的页面。</li> + <li>点击文章链接进入页面。<br> + <strong>注意：</strong>这个列表是自动生成的，但更新并不频繁，所以列表中的一些文章是不再需要编辑审核的。如果你选择的文章<em>没有</em>显示“这篇文章需要复核”，跳过这一篇文章，再选择其他的文章。</li> + </ol> + </li> + <li id="core-steps">仔细阅读文章，特别注意其中可能出现的排版、错字、语法或者词语使用错误。如果你觉得这篇文章不适合你，随时可以换一篇其它文章。</li> + <li>如果文章中没有任何错误，你不需要进入编辑页面再把它标记为“已审核”。在页面的左侧边栏处可以找到“快速复核”对话框：<br> + <img alt="文法复核边栏屏幕截图" src="https://mdn.mozillademos.org/files/13164/editorial%20review%5Bzh-CN%5D.JPG" style="height: 99px; width: 284px;"></li> + <li>取消 <strong>文法</strong> 的勾选之后点击 <strong>保存</strong> 。</li> + <li>如果你发现了需要改正的错误： + <ol> + <li>点击右上角蓝色的 <code><strong>编辑</strong></code> 按钮；它将带你进入 <a href="/zh-CN/docs/Project:MDN/Contributing/Editor_guide">MDN 编辑器</a>。</li> + <li>更正所有你看到的的排版、错字、语法或者词语使用错误。你并不需要将所有问题都一次性改好，不过当完成整篇文章的时候你还觉得不确定是否完美，一定要保留文法复核的请求。</li> + <li>在文本底部输入一段<strong>修订注释</strong>；比如 <em>“文法符合：更改了排版，语法和用词错误。” </em>这有助于其他编辑者和网站管理员知道你更改了什么以及为什么做出更改。</li> + <li>在 <strong>需要复核吗？</strong> 下面取消 <strong>文法</strong> 的选择。这一项位于页面的 <strong>版本备注</strong> 当中。<br> + <img alt="文法复核编辑模式屏幕截图" src="https://mdn.mozillademos.org/files/13166/editorial%20review%20edit-mode%5Bzh-CN%5D.JPG" style="height: 246px; width: 259px;"></li> + <li>点击 <strong>发布</strong> 按钮。</li> + </ol> + </li> + </ol> + + <div class="note"> + <p>你所做出的更改在保存后不一定立即可见，页面保存和处理过程可能出现一些延迟。</p> + </div> + </dd> +</dl> diff --git a/files/zh-cn/mdn/contribute/howto/index.html b/files/zh-cn/mdn/contribute/howto/index.html new file mode 100644 index 0000000000..c63b358e37 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/index.html @@ -0,0 +1,16 @@ +--- +title: MDN 使用指南 +slug: MDN/Contribute/Howto +tags: + - Documentation + - Landing + - MDN + - TopicStub +translation_of: MDN/Contribute/Howto +--- +<p><% //插入当前页面的子页面的定义列表，每个 //页面的标题为</p> + +<dl> + <dt>术语，其 SEO 摘要为</dt> + <dd>术语。的 //如果可能，列表以两列视图显示。 // //参数： //没有 var html = 等待模板 （[子页与摘要] ); //现在，我们有了HTML中的整个列表。让我们通过它，并尝试用力把它分成两列。 %> <%-等待模板（"MakeColumnsForDL"，[html]）%></dd> +</dl> diff --git a/files/zh-cn/mdn/contribute/howto/link_a_github_account/index.html b/files/zh-cn/mdn/contribute/howto/link_a_github_account/index.html new file mode 100644 index 0000000000..5be8c9fe23 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/link_a_github_account/index.html @@ -0,0 +1,89 @@ +--- +title: 如何在您的MDN账户中关联一个GitHub账户 +slug: MDN/Contribute/Howto/Link_a_GitHub_account +tags: + - MDN + - 文档 +translation_of: Archive/MDN/Howto_Link_a_Github_account +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<div class="note"> +<p><strong>Note: </strong>Support for Persona logins on MDN was disabled on November 1, 2016. The method for adding a Github account to your profile therefore no longer works. If you didn't add a GitHub login to your MDN account before we disabled Persona logins, please <strong>file an <a class="external external-icon" href="https://mzl.la/accounthelp">"Account Help" bug</a> </strong>on Bugzilla. For further reading about the end of life of Persona, see: <a href="https://wiki.mozilla.org/Identity/Persona_Shutdown_Guidelines_for_Reliers">Persona shutdown guidelines</a>.</p> +</div> + + +<p><span class="seoSummary">由于Mozilla的 <a href="https://login.persona.org/">Persona</a> 身份认证系统将会于2016年11月30日起关闭，所有希望为MDN做贡献的用户都需要用其他手段来登录到 MDN。当前，我们支持的唯一选择就是 GitHub，所以您需要在截止日期过后使用 <a href="https://github.com/">GitHub</a> 账户登入并编辑 MDN。这篇文章讲述了如何将 GitHub 身份认证添加到您的MDN账户中。</span></p> + +<div class="warning"> +<p>您必须在2016年11月30日前完成此操作，否则您将再也无法登录 MDN！</p> +</div> + +<h2 id="概述">概述</h2> + +<p>将GitHub身份认证添加到您的账户中并不难。下面我们将进一步讨论细节，但首先，先看一下步骤概述：</p> + +<ol> + <li><a href="/zh-CN/docs/MDN/Signing_in">登录您的 MDN 账户</a></li> + <li>转到 <a href="https://developer.mozilla.org/en-US/users/account/connections">账户关联</a> 页面</li> + <li>添加 GitHub 身份认证。</li> +</ol> + +<h2 id="详细指南">详细指南</h2> + +<p>下面是一个手把手的教程，教您如何完成您需要知道的事情。</p> + +<h3 id="登入您的_MDN_账户">登入您的 MDN 账户</h3> + +<ol> + <li>在任意MDN页面的顶端，将鼠标悬浮于或点击登录框。它会显示可用的身份认证方式：<strong>Persona</strong> 或 <strong>GitHub </strong>。<br> + <img alt="Sign in box on MDN, showing Persona and Github." src="https://mdn.mozillademos.org/files/13426/Mozilla_Developer_Network_-__Private_Browsing_.png" style="border-style: solid; border-width: 1px; height: 140px; width: 425px;"></li> + <li>选择 <strong>Persona </strong>，然后用您常用的登录凭据登入。</li> +</ol> + +<h3 id="转到账户关联页面">转到账户关联页面</h3> + +<p>有两种方法转到账户关联页面。</p> + +<p>一种方法就是点击下面的链接。</p> + + +<p>还有一种方法就是完成下列步骤：</p> + +<ol> + <li>在任意 MDN 的页面顶端单击您的用户名（就是您未登录时登入框的位置）。这将带您到您的资料页面。</li> + <li>点击“齿轮”菜单，然后单击 <strong>Account connections </strong>（账户关联）。<br> + <img alt='Gear menu in profile, showing the "Account connections" option' src="https://mdn.mozillademos.org/files/13428/SheppyWork___MDN_-__Private_Browsing_.png" style="height: 217px; width: 219px;"></li> +</ol> + +<h3 id="添加_GitHub_身份认证">添加 GitHub 身份认证</h3> + +<p>您现在位于"Account connections"（账户关联）页面，它罗列了您已连接到您的 MDN 个人资料的外部账户。如果 GitHub 账户已经列出，那么恭喜你！您已经完成了！但为了测试一下您是否牢记您的密码，可以登出 MDN，再使用您的 GitHub 身份凭证登入。</p> + +<p>如果 Github 没有列出，请看看页面底部的已连接账户列表。您可以看到<strong>连接一个新的账号</strong>小节，这里列出了您可以与您的 MDN 个人资料建立连接的账户。如下图：</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/13430/Account_Connections___MDN_-__Private_Browsing_.png" style="height: 79px; width: 476px;"></p> + +<p>要想添加 GitHub：</p> + +<ol> + <li>点击 <strong>连接 Github</strong>。MDN 将会向 Github 请求权限连接这两个账户。如果您还未登录 Github，登录页面将会显示出来：<br> + <img alt="Screenshot of GitHub sign in window." src="https://mdn.mozillademos.org/files/13444/GitHub_Sign_In.png" style="height: 447px; width: 356px;"></li> + <li>如果您为您的 Github 账户开通了两步验证，您须要输入您的验证码：<br> + <img alt="Screenshot of GitHub's Two-factor authentication window." src="https://mdn.mozillademos.org/files/13460/GitHub_-_Where_software_is_built.png" style="height: 448px; width: 361px;"></li> + <li>现在您登录您的 Github 账户了。您可以进行授权，以连接 Github 与 MDN 账户（除非您曾经因某些原因授权过）。此页面如下图：<br> + <img alt='Screenshot of GitHub "Authorize application" window.' src="https://mdn.mozillademos.org/files/13456/Authorize_Mozilla_Developer_Network.png" style="height: 420px; width: 766px;"><br> + 点击绿色的 <strong>Authorize application</strong>（授权应用） 按钮授予您的 MDN 账户访问您的 Github 账户的权限。当您的 Github 账户成功与 MDN 账户建立连接时，您将看到这一信息：<br> + <img alt="Account successfully created." src="https://mdn.mozillademos.org/files/13454/Edit_Your_Profile___MDN.png" style="height: 57px; width: 646px;"></li> +</ol> + +<p>现在您不仅可用 GitHub 登录 MDN，还已经使用 GitHub 身份认证登入了！您已经准备好应对 Persona 关闭了。如有必要，您应该确定已经更新了安装的所有密码管理器。</p> + +<h2 id="相关链接">相关链接</h2> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Howto/Create_an_MDN_account">如何创建一个MDN账户</a></li> + <li><a href="/zh-CN/docs/MDN/Getting_started">初入MDN</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html b/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html new file mode 100644 index 0000000000..bf90ff0262 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html @@ -0,0 +1,59 @@ +--- +title: 如何为页面编写概要 +slug: MDN/Contribute/Howto/Set_the_summary_for_a_page +tags: + - 指南 +translation_of: MDN/Contribute/Howto/Set_the_summary_for_a_page +--- +<div>{{MDNSidebar}}</div> + +<p>您可以在MDN的每一个页面上定义概要，它可以在很多方面起到作用，如包含在搜索引擎的搜索结果中，或者在其他MDN页面如热门话题页或者工具提示页。它应该概括的描述该页面的所有内容，并且当在其他页面显示时，不包含页面内容的无关部分。</p> + +<div class="blockIndicator warning"> +<p><strong>一个概要可以被明确的定在在一个页面中。如果概要没有被明确的定义，通常会使用该页面内容的第一句话作为概要，而它往往不是该页面最精确的描述。</strong></p> +</div> + +<table class="full-width-table"> + <tbody> + <tr> + <td><strong>任务是什么？</strong></td> + <td>标记应被用作其在其他情况下摘要页面中的文本;这项任务可能包括在需要写相应的文本。</td> + </tr> + <tr> + <td><strong>哪些地方需要它？</strong></td> + <td>在缺乏一个总结或总结不太好的页面。</td> + </tr> + <tr> + <td><strong>完成任务需要什么？</strong></td> + <td>能够使用MDN编辑器的能力;良好的英语写作能力;对网页的主题足够熟悉，以便于能写一个很好的总结。</td> + </tr> + <tr> + <td><strong>怎样完成任务？</strong></td> + <td> + <ol> + <li>选择一个页面来设置总结: + <ol> + <li>在<a href="/zh-CN/docs/MDN/Doc_status">MDN documentation status</a> 页面上的section中, 点击你所了解的话题。<img alt="" src="https://mdn.mozillademos.org/files/8681/sections.png"></li> + <li>在主题的文档状态页面，单击汇总表中的页头。这需要你在该主题区段的所有网页的索引;它示出了在左侧列中的页面的链接，以及在右栏中的标签和摘要。<img alt="" src="https://mdn.mozillademos.org/files/8675/pages.png"></li> + <li>挑选缺少一个总结页面，或者说有一个较差的总结的页面。<img alt="" src="https://mdn.mozillademos.org/files/8677/summary.png"></li> + </ol> + </li> + </ol> + + <div class="blockIndicator warning"> + <p>点击链接进入该页面。</p> + </div> + + <ol> + <li>单击编辑在MDN编辑器中打开该页面。</li> + <li>找一两句话，作为一个总结。如果需要，可以编辑现有的内容来创建或修改的句子来做一个很好的总结。</li> + <li>选择要使用的摘要文本。</li> + <li>在样式插件的编辑器工具栏，选择搜索引擎优化摘要。 (In the page source, this creates a {{HTMLElement("span")}} element with <code>class="seoSummary"</code> around the selected text.)<img alt="" src="https://mdn.mozillademos.org/files/8679/styles.png"></li> + <li>保存你的更改，并附上类似“设置页面总结”的修改意见。修改意见是可选的，但我们鼓励你添加一个。这样便于其他人了解变更的情况。</li> + </ol> + </td> + </tr> + </tbody> +</table> + +<p>完成这样的一份任务后，你就是MDN的一员。</p> diff --git a/files/zh-cn/mdn/contribute/howto/tag/index.html b/files/zh-cn/mdn/contribute/howto/tag/index.html new file mode 100644 index 0000000000..67415b88f1 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/tag/index.html @@ -0,0 +1,536 @@ +--- +title: 如何合理的标记页面 +slug: MDN/Contribute/Howto/Tag +tags: + - MDN 元 + - 初学者 + - 如何 + - 指南 + - 教程 +translation_of: MDN/Contribute/Howto/Tag +--- +<div>{{MDNSidebar}}</div> + +<p><strong>文章标签</strong>是一个让游客接触到有用内容的重要方式。每一个页面通常都应该有几个标签来保持其内容的组织性。 <span class="seoSummary">这一页解释了标记页面的最好方法，以使我们的读者可以找到信息和让我们的页面保持组织有序。</span></p> + +<p>对于编辑标签的用户界面的帮助, 请看我们的编辑者指南里的<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics#The_tags_box">标记部分</a>。</p> + +<p>请根据下面所解释的来合理的使用标签。 如果你没有这么做, 我们的自动化工具将不能正确的生成内容列表，着陆页面和文章的交叉链接。</p> + +<h2 id="MDN如何使用标签">MDN如何使用标签</h2> + +<p>MDN有这么几种方法来使用标签：</p> + +<dl> + <dt>文档分类：</dt> + <dd>这个文档是什么类型的？是一篇参考？一篇教程？还是一篇着陆页？我们的游客可以使用这些标签来过滤搜索，所以它们真的很重要！</dd> + <dt>主题识别</dt> + <dd>这篇文章是关于什么的？关于API？DOM？图形？重申一遍，这些标签很重要，因为它们可以用来过滤搜索。</dd> + <dt>技术现状</dt> + <dd>这门技术的现状是什么？它是非标准的？过时的还是已经被弃用了的？还是处于实验性的？</dd> + <dt>技术水平</dt> + <dd>教程和指南，这篇文章中涵盖的内容有多先进？</dd> + <dt>文档元数据</dt> + <dd>写作社区使用标签来跟踪哪些页面需要什么样的工作。</dd> +</dl> + +<h2 id="标签类型指南">标签类型指南</h2> + +<p>这里是关于标签类型的快速指南和它们可能用到的值。</p> + +<h3 id="文档类别">文档类别</h3> + +<p>当你使用这些类别中的一个来标记文章的时候, 你帮助了自动化工具更准确的生成着陆页面，内容表，和更多。我们新的搜索系统也可以使用这些来让我们的游客更好的根据他们的意愿来定位参考和指南。</p> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>我们使用以下类别名称作为标准标记术语：</span></p> +</div> +</div> + +<dl> + <dt><code>{{Tag("Intro")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>这篇文章提供了一个有关主题的介绍材料。</span><span>最理想的是每一个技术领域应该只能有一个“Intro”标签。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Featured")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>这篇文章是至关重要的，将在登陆页面上显示在突出的位置上。</span><span>有节制地使用这个标签（每个文件区不要超过三个）。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Reference")}}</code></dt> + <dd>这篇文章包含API、元素、属性、等的参考资料。</dd> + <dt><code>{{Tag("Landing")}}</code></dt> + <dd>这是一个着陆页面。</dd> + <dt><code>{{Tag("Guide")}}</code></dt> + <dd>这篇文章是一个告诉如何做或者指南的页面。</dd> + <dt><code>{{Tag("Example")}}</code></dt> + <dd>这是代码示例页面，或者有代码示例（那是有用的代码实例，而不是一行“语法例子”）。</dd> +</dl> + +<h3 id="主题">主题</h3> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>通过确定文章的主题区域，您可以帮助产生更好的搜索结果（以及着陆页和导航）。</span></p> +</div> +</div> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>虽然在这里有一些灵活的空间可以识别新的主题领域，但我们试着将自己限制在API和技术的名字</span><span>上，一些有用的例子：</span></p> +</div> +</div> + +<ul> + <li><code>{{Tag("HTML")}}</code></li> + <li><code>{{Tag("CSS")}}</code></li> + <li><code>{{Tag("JavaScript")}}</code> (注意大写字母 “S”！)</li> + <li><code>{{Tag("Document")}}</code></li> + <li><code>{{Tag("DOM")}}</code></li> + <li><code>{{Tag("API")}}</code> 对于每一个接口，方法和属性。</li> + <li><code>{{Tag("Method")}}</code> 对于API的每一个方法。</li> + <li><code>{{Tag("Property")}}</code> 对于API的每一个属性。</li> + <li><code>{{Tag("Graphics")}}</code></li> + <li><code>{{Tag("Firefox OS")}}</code></li> + <li><code>{{Tag("Gecko")}}</code></li> + <li><code>{{Tag("XUL")}}</code></li> + <li><code>{{Tag("XPCOM")}}</code></li> + <li><code>{{Tag("SVG")}}</code></li> + <li><code>{{Tag("WebGL")}}</code></li> + <li><code>{{Tag("Element")}}</code></li> + <li><code>{{Tag("Node")}}</code></li> + <li><code>{{Tag("Tools")}}</code></li> + <li><code>{{Tag("Web")}}</code></li> +</ul> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output">一般而言，您的主题标识标签应该是一个接口的名称，和相关的页面（如<a href="/en-US/docs/Web/API/Node" title="/en-US/docs/Web/API/Node">Node</a>，它的各种属性和方法有很多页），或一个整体的技术类型的名称。<span>你可以对图形、WebGL和WebGL设置页面标签，而不仅是一个关于</span>{{HTMLElement("canvas")}} <span>与HTML、元素，Canvas，和图形。</span></p> + +<h4 class="ordinary-output target-output" id="Mozilla_特定内容"><span>Mozilla 特定内容</span></h4> + +<p><span>这些标签只用于Mozilla特定内容:</span></p> + +<ul> + <li>{{Tag("Mozilla")}}</li> + <li>{{Tag("Firefox")}}</li> + <li><code>{{Tag("Firefox OS")}}</code></li> + <li><code>{{Tag("Gecko")}}</code></li> + <li><code>{{Tag("XUL")}}</code></li> + <li><code>{{Tag("XPCOM")}}</code></li> +</ul> + + + +<h3 id="API_标识">API 标识</h3> + +<p>在API引用中, 每篇文章都应该标明它覆盖了哪部分API:</p> + +<dl> + <dt>{{tag("Interface")}}</dt> + <dd>一个接口的主要文章应该有这样的标签. 例如, {{DOMxRef("RTCPeerConnection")}}.</dd> + <dt>{{tag("Constructor")}}</dt> + <dd>每个接口最多可以有一个页面标记为“构造函数”（接口的构造函数）。页面应该有和接口一样的名字，如{{DOMxRef("RTCPeerConnection.RTCPeerConnection()","RTCPeerConnection()")}}.</dd> + <dt>{{tag("Property")}}</dt> + <dd>每一篇描述接口内特定属性的文章都需要这样的标记。以{{DOMxRef("RTCPeerConnection.connectionState")}}, 为例。</dd> + <dt>{{tag("Method")}}</dt> + <dd>每一篇记录接口方法的文章都需要这样的标记。以 {{DOMxRef("RTCPeerConnection.createOffer()")}}为例。</dd> +</dl> + +<p>此外，引用页面需要在其标记中包含接口、属性和方法名称。一些例子如下：</p> + +<dl> + <dt>接口 {{DOMxRef("RTCPeerConnection")}}</dt> + <dd>包含标签 "RTCPeerConnection" 以及其他相关标记 （"Interface"，"WebRTC"，"WebRTC API"，"API"，"Reference"等）。</dd> + <dt>方法{{DOMxRef("RTCPeerConnection.createOffer()")}}</dt> + <dd>包括标记 "RTCPeerConnection"和 "createOffer" (注意标记名中没有括号！) 以及其他相关标记，包括 "WebRTC"，"WebRTC API"，"API"，"Reference"等。考虑包含像 "Offer"和 "SDP"这些内容，它们在这里也是相关的。</dd> + <dt>属性{{DOMxRef("RTCPeerConnection.iceConnectionState")}}</dt> + <dd>包括标记"RTCPeerConnection"和"iceConnectionState"以及其他相关标记，包括 "WebRTC"，"WebRTC API"，"API"和"Reference"。也需要考虑包括 "ICE"。</dd> +</dl> + + + +<ul> +</ul> +</div> +</div> + +<h3 id="技术状况">技术状况</h3> + +<p>为了帮助读者了解可行的技术是怎样的，<span class="high-light-bg">我们使用标签来标记页面的技术规范的状态。</span><span class="high-light-bg">这并不像实际解释规格是什么，以及技术在规范过程中出现了多少（这正是规格表的用途）</span><span>，但它有助于读者判断，乍一看之下，使用在文章中描述的技术是否是一个好主意。</span></p> + +<p>这些标记是一些可能的值：</p> + +<dl> + <dt><code>{{Tag("Non-standard")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>表示页面中描述的技术或应用接口不是标准的一部分，但是在任何实现浏览器中都是稳定的。</span><span>如果你不使用这个标签，你的读者会认为这是标准的技术。</span><span>页面上的兼容性表应该说明该技术或API的支持。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Deprecated")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>网页上的技术或API被标记为过时的规范，并有可能最终被删除，但一般仍可用在当前版本的浏览器。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Obsolete")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>该技术或API已被认为已经过时，并已经在所有或大多数当前浏览器中被删除（或正在积极被删除）。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Experimental")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>技术不是规范，而是一个实验性的技术或API，可能会或可能不会成为标准的一部分。它可能</span>在浏览器的实现上被改变。</p> + </div> + </div> + </dd> + <dt><code>{{Tag("Needs Privileges")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>该接口要求访问该设备在该设备上运行的权限。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Certified Only")}}</code></dt> + <dd>该API仅适用于认证码。</dd> +</dl> + +<p>这些标签没有理由离开你文章中的 <a href="/en-US/docs/Project:Compatibility_tables" title="/en-US/docs/Project:Compatibility_tables">兼容性表</a> ！</p> + +<h3 id="技术水平">技术水平</h3> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>指南或教程的技术水平标签类型（那是，被标记的指南）帮助用户来基于他们的熟悉程度来选择教程，这里有三个值：</span></p> +</div> +</div> + +<dl> + <dt><code>{{Tag("Beginner")}}</code></dt> + <dd>介绍读者到一个从未使用过的技术或仅仅是一种熟悉的技术。</dd> + <dt><code>{{Tag("Intermediate")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>已经开始使用该技术的用户的文章，但不是专家。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("Advanced")}}</code></dt> + <dd>关于拓展技术和读者能力的文章。</dd> +</dl> + +<h3 id="文档元数据">文档元数据</h3> + +<div class="output-mod ordinary-wrap"> +<div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> +<p class="ordinary-output target-output"><span>写作社区要求根据特定类型的工作来使用标签标记文章。</span><span>以下是我们最常用的一个列表：</span></p> +</div> +</div> + +<dl> + <dt><code>{{Tag("Draft")}}</code></dt> + <dd>文章不完整，至少在理论上仍在积极更新（尽管它也有可能被遗忘）。在进行更改之前，请尝试与最新的贡献者进行检查，以避免潜在的内容冲突。</dd> + <dt><code>{{Tag("NeedsCompatTable")}}</code></dt> + <dd>文章需要一个表来指定跨浏览器特性的兼容性，有关促进浏览器兼容性的指南参见<a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">此处</a>。</dd> +</dl> + +<dl> + <dt><code>{{Tag("NeedsContent")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>文章是一个存根，或者是缺乏其他信息。</span><span>这个标签意味着有人应该审查的内容，并添加更多的细节和/或完成写作的文章。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("NeedsExample")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>文章需要一个或多个例子来帮助说明文章的要点。</span><span>这些例子应该使用</span><a href="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples" title="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples">实时示例系统</a>.</p> + </div> + </div> + </dd> + <dt><code>{{Tag("NeedsLiveSamples")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>本文有一个或多个实例，需要使用</span> <a href="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples" title="/en-US/docs/Project:MDN/Contributing/How_to_help/Code_samples">在线样本系统</a>更新。</p> + </div> + </div> + </dd> + <dt><code>{{Tag("NeedsUpdate")}}</code></dt> + <dd>内容过时，需要更新。</dd> + <dt><code>{{Tag("l10n:exclude")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>内容是不真正值得本地化，不会出现在本地化状态页。</span></p> + </div> + </div> + </dd> + <dt><code>{{Tag("l10n:priority")}}</code></dt> + <dd> + <div class="output-mod ordinary-wrap"> + <div class="output-bd" dir="ltr" style="padding-bottom: 0px;"> + <p class="ordinary-output target-output"><span>内容重要，应该被MDN标记为优先翻译。</span><span>在本地化状态页上显示了一个额外的优先级表。</span></p> + </div> + </div> + </dd> +</dl> + +<h3 id="Web_Literacy_Map">Web Literacy Map</h3> + +<p>The <a href="https://webmaker.org" rel="external">WebMaker</a> project, through the <a href="https://webmaker.org/literacy" rel="external">Web Literacy Map</a>, has defined skills needed to optimally read, write, and participate on the Web. We use Web literacy skills as tags on MDN to help our users find the resources that best suit their needs:</p> + +<dl> + <dt>{{Tag("Navigation")}}</dt> + <dd>文章包含关于在web上如何搜索的信息。</dd> + <dt>{{Tag("WebMechanics")}}</dt> + <dd>内容有关于web如何组织和如何工作的信息。</dd> + <dt>{{Tag("Search")}}</dt> + <dd>文章解释了如何在web上寻找信息、人和资源。</dd> + <dt>{{Tag("Credibility")}}</dt> + <dd>文章中的信息帮助读者理解怎样批判性的评估他们在web上找到的信息。</dd> + <dt>{{Tag("Security")}}</dt> + <dd>文章提供有关如何保持系统、身份和内容安全的信息。</dd> + <dt>{{Tag("Composing")}}</dt> + <dd>文档解释如何创建和curate web上的内容。</dd> + <dt>{{Tag("Remixing")}}</dt> + <dd>文章讲授如何修改existing的网络资源来创建新的东西。</dd> + <dt>{{Tag("Design")}}</dt> + <dd>文档解释如何提高视觉和其他用户体验。</dd> + <dt>{{Tag("Accessibility")}}</dt> + <dd>文档描述如何用universally-recognizable的方式交流。</dd> + <dt>{{Tag("CodingScripting")}}</dt> + <dd>如何在网络上写代码和（或）创造交互式的用户体验。</dd> + <dt>{{Tag("Infrastructure")}}</dt> + <dd>文档解释Internet's technical stack是如何工作的。</dd> + <dt>{{Tag("Sharing")}}</dt> + <dd>文章内容包含与他人一起创造资源的方式。</dd> + <dt>{{Tag("Collaborating")}}</dt> + <dd>文档提供关于如何与他人一同工作的信息。</dd> + <dt>{{Tag("Community")}}</dt> + <dd>文章详细说明如何参与网络社区并理解他们如何工作。</dd> + <dt>{{Tag("Privacy")}}</dt> + <dd>材料帮助检查在网络上分享数据的后果。</dd> + <dt>{{Tag("OpenPractices")}}</dt> + <dd>文章provid=deshow帮助保持人人可以连接网络。</dd> +</dl> + +<h2 id="把它们放到一起">把它们放到一起</h2> + +<p>就可以从几种标签种类中搜索你标记的网页，例如</p> + +<dl> + <dt>A tutorial about WebGL for beginners</dt> + <dd><code>WebGL</code>, <code>Graphics</code>, <code>Guide</code>, <code>Beginner</code></dd> + <dt>Reference page for {{HTMLElement("canvas")}}</dt> + <dd><code>Canvas</code>, <code>HTML</code>, <code>Element</code>, <code>Graphics,</code> <code>Reference</code></dd> + <dt>A landing page for Firefox OS developer tools</dt> + <dd><code>Tools</code>, <code>Firefox OS</code>, <code>Landing</code></dd> +</dl> + +<h2 id="标签和搜索过滤">标签和搜索过滤</h2> + +<p>只有我们正确地标记网页，搜索过滤才能正确工作。这是一个搜索过滤和它们寻找的标签的表格。</p> + +<div class="note"> +<p><strong>注意：Note:</strong> 如果多个标签被列在“tag name”下，那说明，为了搜索，任何一个或更多的标签必须在文章中。</p> +</div> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">Filter group</th> + <th scope="col">Search filter name</th> + <th scope="col">Tag name</th> + </tr> + </thead> + <tbody> + <tr> + <th>Topic</th> + <td>Open Web Apps</td> + <td>{{Tag("Apps")}}</td> + </tr> + <tr> + <th></th> + <td>HTML</td> + <td>{{Tag("HTML")}}</td> + </tr> + <tr> + <th></th> + <td>CSS</td> + <td>{{Tag("CSS")}}</td> + </tr> + <tr> + <th></th> + <td>JavaScript</td> + <td>{{Tag("JavaScript")}}</td> + </tr> + <tr> + <th></th> + <td>APIs and DOM</td> + <td>{{Tag("API")}}</td> + </tr> + <tr> + <th></th> + <td>Canvas</td> + <td>{{Tag("Canvas")}}</td> + </tr> + <tr> + <th></th> + <td>SVG</td> + <td>{{Tag("SVG")}}</td> + </tr> + <tr> + <th></th> + <td>MathML</td> + <td>{{Tag("MathML")}}</td> + </tr> + <tr> + <th></th> + <td>WebGL</td> + <td>{{Tag("WebGL")}}</td> + </tr> + <tr> + <th></th> + <td>XUL</td> + <td>{{Tag("XUL")}}</td> + </tr> + <tr> + <th></th> + <td>Marketplace</td> + <td>{{Tag("Marketplace")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox</td> + <td>{{Tag("Firefox")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox for Android</td> + <td>{{Tag("Firefox Mobile")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox for Desktop</td> + <td>{{Tag("Firefox Desktop")}}</td> + </tr> + <tr> + <th></th> + <td>Firefox OS</td> + <td>{{Tag("Firefox OS")}}</td> + </tr> + <tr> + <th></th> + <td>Mobile</td> + <td>{{Tag("Mobile")}}</td> + </tr> + <tr> + <th></th> + <td>Web Development</td> + <td>{{Tag("Web Development")}}</td> + </tr> + <tr> + <th></th> + <td>Add-ons & Extensions</td> + <td>{{Tag("Add-ons ")}}|| {{Tag("Extensions")}} || {{Tag("Plugins")}} || {{Tag("Themes")}}</td> + </tr> + <tr> + <th></th> + <td>Games</td> + <td>{{Tag("Games")}}</td> + </tr> + <tr> + <th>Skill level</th> + <td>I'm an Expert</td> + <td>{{Tag("Advanced")}}</td> + </tr> + <tr> + <th></th> + <td>Intermediate</td> + <td>{{Tag("Intermediate")}}</td> + </tr> + <tr> + <th></th> + <td>I'm Learning</td> + <td>{{Tag("Beginner")}}</td> + </tr> + <tr> + <th>Document type</th> + <td>Docs</td> + <td><em>This restricts the search to docs content, leaving out Hacks and other MDN content.</em></td> + </tr> + <tr> + <th></th> + <td>Demos</td> + <td><em>This includes Demo Studio content in the search results.</em></td> + </tr> + <tr> + <th></th> + <td>Tools</td> + <td>{{Tag("Tools")}}</td> + </tr> + <tr> + <th></th> + <td>Code Samples</td> + <td>{{Tag("Example")}}</td> + </tr> + <tr> + <th></th> + <td>How-To & Tutorial</td> + <td>{{Tag("Guide")}}</td> + </tr> + <tr> + <th></th> + <td>Developer Profiles</td> + <td><em>This includes developer profiles from the MDN site in the search results.</em></td> + </tr> + <tr> + <th></th> + <td>External Resources</td> + <td><em>The dev team is still figuring this out...</em></td> + </tr> + </tbody> +</table> + +<h2 id="你可以修改的标签的错误">你可以修改的标签的错误</h2> + +<p>这些种类的标签错误你可以帮助修改：</p> + +<dl> + <dt>没有标签</dt> + <dd>一般来说文章应该至少有一个 "<a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Category" title="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Categories">category</a>" 标签和一个 "<a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Topic" title="/en-US/docs/Project:MDN/Contributing/Tagging_standards#Topic">topic</a>"标签. 虽然有其他标签也好, 但是如果你能帮我们提供最基本的标签（前文所说的category和topic标签）, 你将会是一名（维护）文档的英雄!</dd> + <dt>不符合我们<s>标签</s>标准的标签</dt> + <dd>请修正一切含有不合标准标签的文档.请注意由于<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=776048">Kuma的一个bug</a>, 一些本地化的标签(比如 <code>Référence</code>) 可能会出现在一些英语页面上. 这些标签还有可能反复出现,即使你已经吧它们删除; 请耐心处理这些问题直到kuma的那个bug被修复.</dd> + <dt>不正确的标签</dt> + <dd>如果你正在看一篇关于HTML的文章并且发现它被标上了"JavaScript"的标签, 那很有可能这是一个错误标签! 同理, 如果一篇文章在讨论Mozilla internals 但是有一个"Web"标签, 那也有可能是错误的. 删除这些错误的标签并且如果还没有合适标签的话，加上正确的标签. 同样请更正拼写错误的标签(e.g., 因为标签是大小写敏感的, 所以"Javascript" 仍然匹配, 但是我们还是不要马虎对待!).</dd> + <dt>缺失的标签</dt> + <dd>如果一篇文章有标签但是不全面, 请补全. 比如, 一页JavaScript 的参考文档被(正确) 标签为 "JavaScript" 但是除此之外什么也没有了, 请你就为它标上"参考"的标签!</dd> + <dt>垃圾标签</dt> + <dd>这只潜伏的怪兽是所有标签问题中最让人讨厌的: some Web vermin has deposited its droppings in the page tags (like "Free warez!" or "Hey I was browsing your site and wanted to ask you if you could help me solve this problem I'm having with Flash crashing all the time"). We've got to delete these right away! They're ugly, they're hard to manage if they're allowed to linger too long, and they're terrible for {{Glossary("SEO")}}.</dd> +</dl> + +<p>如果你发现了以上问题, 请<a href="/en-US/docs/Project:MDN/Contributing/Getting_started#Logging_into_MDN">登录MDN</a>点击MDN窗口右上方的 EDIT按钮. 等编辑器载入完成后, 到页面底部, 你就会看到标签. 想了解标签操作界面的更多信息, 请参看 "<a href="/en-US/docs/Project:MDN/Contributing/Editor_guide#The_tags_box" title="/en-US/docs/Project:MDN/Contributing/Editor_guide#The_tags_box">The tags box</a>" in the <a href="/en-US/docs/Project:MDN/Contributing/Editor_guide" title="/en-US/docs/Project:MDN/Contributing/Editor_guide">MDN editor guide</a>.</p> diff --git a/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html b/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html new file mode 100644 index 0000000000..4420d3f04e --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html @@ -0,0 +1,69 @@ +--- +title: 如何给JavaScript相关页面添加标签 +slug: MDN/Contribute/Howto/Tag_JavaScript_pages +translation_of: MDN/Contribute/Howto/Tag_JavaScript_pages +--- +<div>{{MDNSidebar}}</div><p class="summary"><strong>标记工作包括给页面添加元信息，使得这些页面的相关内容能被搜索工具等正确的分拣。</strong></p> + +<dl> + <dt>哪里需要做这件事<strong>?</strong></dt> + <dd>那些特定的<a href="/en-US/docs/Web/JavaScript/Doc_status#No_tags">没有标签的JavaScript相关的页面</a></dd> + <dt><strong>开始标记任务前你需要知道些什么？</strong></dt> + <dd>一些基本的JavaScript编程知识，比如javascript中的方法和属性都是些什么。</dd> + <dt><strong>你的工作有以下几个步骤</strong></dt> + <dd> + <ol> + <li>选择下面列举的某篇文章。</li> + <li>点击该文章所对应的链接，载入页面。</li> + <li>当页面载入完毕时，点击顶部附近的<strong>EDIT按钮，</strong>就会进入MDN编辑模式。</li> + <li>最后就是添加Javascript相关的标签了，我们提供了如下可选的标签。 + <table class="standard-table"> + <thead> + <tr> + <th scope="col">标签名</th> + <th scope="col">适用于含有哪些内容的页面</th> + </tr> + </thead> + <tbody> + <tr> + <td>Method</td> + <td>方法</td> + </tr> + <tr> + <td>Property</td> + <td>属性</td> + </tr> + <tr> + <td><font face="Consolas, Liberation Mono, Courier, monospace">Prototype</font></td> + <td>原型</td> + </tr> + <tr> + <td>Object type name</td> + <td>所述对象的名字，例如String.fromCharCode就应该有String标签</td> + </tr> + <tr> + <td><code>ECMAScript6 </code>and <code>Experimental</code></td> + <td>在新版ECMAScript标准中增加的特性</td> + </tr> + <tr> + <td><code>Deprecated</code></td> + <td>不赞成使用的特性（那些不鼓励使用但仍然被浏览器支持的特性）</td> + </tr> + <tr> + <td><code>Obsolete</code></td> + <td>被废弃的特性（那些不再被浏览器支持的特性）</td> + </tr> + <tr> + <td>others</td> + <td>查看 <a href="/en-US/docs/Project:MDN/Contributing/Tagging_standards">MDN 标签规则</a> 中其他可选标签</td> + </tr> + </tbody> + </table> + </li> + <li>添加备注信息并保存你的修改。</li> + <li>你做到了！</li> + </ol> + </dd> +</dl> + +<p> </p> diff --git a/files/zh-cn/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html b/files/zh-cn/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html new file mode 100644 index 0000000000..29ad28e098 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_a_new_entry_in_the_glossary/index.html @@ -0,0 +1,107 @@ +--- +title: 如何撰写和引用一个词汇表中的条目 +slug: MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary +translation_of: MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary +--- +<div>{{MDNSidebar}}</div> + +<p>MDN <a href="/zh-CN/docs/Glossary">术语表</a> 是一个定义所有被用于文档和编码的术语、行话和缩写的地方。对词汇表做出贡献是使Web更易于理解的简单方法。您不需要高水平的技术技能来编写词汇表条目，因为它们应该保持简单直接。</p> + +<h2 id="如何写一个条目">如何写一个条目</h2> + +<p>如果您正在寻找需要词汇表条目的主题，请查看词汇表首页末尾的<a href="/zh-CN/docs/Glossary#Contribute_to_the_glossary">未撰写文档的条目清单</a>。请单击您希望创建的词汇条目的链接，进入”新的词汇表页面“准备新条目的创建。然后按照后面的步骤操作。</p> + +<p>如果您有添加新的词汇表条目的想法，只需在新选项卡中打开以下按钮，然后按照按钮下方的步骤操作：</p> + +<p></p><div class="align-center"><a class="button ignore-external mega positive" href="/zh-CN/docs/new?parent=4391">向术语表中添加一个新条目<div></div></a></div><p></p> + +<h3 id="第一步_写概要">第一步: 写概要</h3> + +<p>任何词汇表页面的第一段是对该术语的简单和简短描述（最好不超过两个句子）。 确保阅读说明的人能够立即了解定义的术语。</p> + +<div class="note"> +<p><strong>注意:</strong> 请不要直接从其他地方复制和粘贴定义（尤其是维基百科，因为许可证版本范围较小，因此与MDN不兼容）。确保条目内容简单易懂是很重要的。值得花一些时间来撰写定义，而不是简单盲目地窃取其他地方的内容。 这个词汇表应该是有用的新内容，而不是和别处重复的。</p> +</div> + +<p>使用“链接到词汇表条目”工具可以方便读者直接看到词汇条目中的定义，不需要读者跳转到词汇条目的页面。（更多内容请浏览如何使用 \{{Glossary}} 宏插入词汇表条目的链接。）</p> + +<p>如果需要的话，你可以添加少量额外的段落，但是这很容易导致你写了一整篇文章的情况发生。写一个完整的文章很棒，但是请不要把它们整个放在词汇表中。如果你不确定这里是否适合放你的文章，你就要随时<a href="/en-US/docs/MDN/Community#Join_our_mailing_lists">在这里讨论</a>。</p> + +<h3 id="第二步_扩展链接">第二步: 扩展链接</h3> + +<p>最后，一个词汇表的条目应该总是有“了解更多”这个部分。这个部分应该包含帮助读者看得更深入的链接：探索发现更多细节、学习使用相关技术等。</p> + +<p>我们建议您将链接分为以下三组：</p> + +<dl> + <dt>基础知识</dt> + <dd>提供更多一般信息的链接。如：到<a href="https://zh.wikipedia.org/">维基百科</a>的链接是一个很棒的点。 </dd> + <dt>技术参考</dt> + <dd>链接到更深入的技术信息，在MDN或其他地方。</dd> + <dt>学习它</dt> + <dd>链接到教程、练习或任何其他材料，帮助读者学习使用定义术语背后的技术。</dd> +</dl> + +<h2 id="小建议">小建议</h2> + +<p>所以你想贡献，但你不知道需要定义哪些术语？ <a href="/zh-CN/docs/Glossary#Contribute_to_the_glossary">这里是是建议列表</a>。点击一下，开始吧！</p> + +<h2 id="消除歧义">消除歧义</h2> + +<p>有时，根据上下文，术语有几个含义。 要解决歧义，您必须遵循以下准则：</p> + +<ul> + <li>该术语的主页面必须是一个包含了 {{TemplateLink("GlossaryDisambiguation")}} 宏的消歧页面；</li> + <li>该术语具有定义给定上下文的术语的子页面。</li> +</ul> + +<p>我们以一个例子来说明。<em>signature</em> 条目在至少三种不同的语境中具有不同的含义： <em>安全</em>、<em>函数 </em>和 <em>电子邮件</em>。</p> + +<ol> + <li><a href="/zh-CN/docs/Glossary/Signature">Glossary/Signature</a> 页面是使用了 {{TemplateLink("GlossaryDisambiguation")}} 宏的消歧页面；</li> + <li><a href="/zh-CN/docs/Glossary/Signature/Security">Glossary/Signature/Security</a> 页面是定义安全上下文中签名的条目页面；</li> + <li><a href="/zh-CN/docs/Glossary/Signature/Function">Glossary/Signature/Function</a> 页面是定义函数签名的条目页面；</li> + <li><a href="/zh-CN/docs/Glossary/Signature/Email">Glossary/Signature/Email</a> 页面是定义电子邮件签名的条目页面。</li> +</ol> + +<h2 id="如何使用_Glossary_宏">如何使用 \{{Glossary}} 宏</h2> + +<p>当人们可以在另一个文档访问到词汇的定义，而无需他们从正在阅读的内容进行跳转阅读词汇定义时，词汇表是最好用的。因此，我们敦促您随时使用 {{TemplateLink("Glossary")}} 宏将词汇链接到词汇表：</p> + +<table class="standard-table"> + <thead> + <tr> + <th scope="col">宏</th> + <th scope="col">结果</th> + <th scope="col">备注</th> + </tr> + </thead> + <tbody> + <tr> + <td>\{{Glossary("browser")}}</td> + <td>{{Glossary("browser")}}</td> + <td>当文本与要定义的术语匹配时，只需直接使用宏（不区分大小写）</td> + </tr> + <tr> + <td>\{{Glossary("browser", "Web浏览器")}}</td> + <td>{{Glossary("browser","Web浏览器")}}</td> + <td>要显示替代文本，请使用第二个参数来指定该文本</td> + </tr> + <tr> + <td>\{{Glossary("browser", "Web浏览器", 1)}}</td> + <td>{{Glossary("browser","Web浏览器",1)}}</td> + <td>指定 <code>1</code> 作为可选的第三个参数，将链接显示为常规链接，而不是单纯的提示文本的样式</td> + </tr> + </tbody> +</table> + +<p>使用 \{{Glossary}} 宏创建的链接将总是展示一个包含了词汇表条目的概要段落的提示文本（tooltip）。</p> + +<h3 id="使用方针">使用方针</h3> + +<p>在许多情况下，在MDN上的任何地方使用该宏是非常安全的。 但是，您应该谨慎处理的几种情况：</p> + +<ul> + <li>如果一个术语已经链接到MDN的另一部分，这样的情况请不要使用 \{{Glossary}} 宏；</li> + <li>在文章部分（Section）中，对于相同的术语仅使用一次 \{{Glossary}} 宏 （<em>提示：一个部分总是以标题开始的</em>）。</li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html new file mode 100644 index 0000000000..4ef7b2bcec --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html @@ -0,0 +1,446 @@ +--- +title: How to write an API reference +slug: MDN/Contribute/Howto/Write_an_API_reference +tags: + - API + - Documentation + - Guide + - Howto + - MDN Meta + - NeedsTranslation + - TopicStub +translation_of: MDN/Contribute/Howto/Write_an_API_reference +--- +<div>{{MDNSidebar}}</div> + +<div class="summary"> +<p><span class="seoSummary">This guide takes you through all you need to know to write an API reference on MDN.</span></p> +</div> + +<h2 id="Getting_prepared">Getting prepared</h2> + +<p>Before starting to document an API, there are some things you should prepare and plan in advance of starting to actually write.</p> + +<h3 id="Prerequisite_knowledge">Prerequisite knowledge</h3> + +<p>It is assumed that before reading this guide you have a reasonable knowledge of:</p> + +<ul> + <li>Web technologies like HTML, CSS and JavaScript. JavaScript is most important.</li> + <li>Reading Web technology specs. You'll be looking at these a lot as you document APIs.</li> +</ul> + +<p>Everything else can be learned along the way.</p> + +<h3 id="Prerequisite_resources">Prerequisite resources</h3> + +<p>Before starting to document an API, you should have available:</p> + +<ol> + <li>The latest spec: Whether it is a W3C Recommendation or an early editor's draft, you should refer to the latest available draft of the spec that covers (or specs that cover) that API. To find it, you can usually do a Web search. The latest version will often be linked to from all versions of the spec, listed under "latest draft" or similar.</li> + <li>The latest modern web browsers: These should be experimental/alpha builds such as <a href="https://nightly.mozilla.org/">Firefox Nightly</a>/<a href="https://www.google.com/intl/en/chrome/browser/canary.html">Chrome Canary</a> that are more likely to support the features you are documenting. This is especially pertinent if you are documenting a nascent/experimental API.</li> + <li>Demos/blog posts/other info: Find as much info as you can.</li> + <li>Useful engineering contacts: It is really useful to find yourself a friendly engineering contact to ask questions about the spec, someone who is involved in the standardization of the API, or its implementation in a browser. Good places to find them are: + <ul> + <li>Your internal company address book, if you work for a relevant company.</li> + <li>A public mailing list that is involved in the discussion of that API, such as Mozilla's <a href="https://lists.mozilla.org/listinfo/dev-platform">dev-platform</a> or <a href="https://lists.mozilla.org/listinfo/dev-webapi">dev-webapi</a> lists, or a W3C list like <a href="https://lists.w3.org/Archives/Public/public-webapps/">public-webapps</a>.</li> + <li>The spec itself. For example, the <a href="https://webaudio.github.io/web-audio-api/">Web Audio API spec</a> lists the authors and their contact details at the top.</li> + </ul> + </li> +</ol> + +<h3 id="Take_some_time_to_play_with_the_API">Take some time to play with the API</h3> + +<p>You will return to building demos many times through the course of documenting an API, but it is useful to start by spending time familiarizing yourself with how the API works — learn what the main interfaces/properties/methods are, what the primary use cases are, and how to write simple functionality with it.</p> + +<p>When an API has changed, you need to be careful that existing demos you refer to or learn from are not out of date. Check the main constructs that are used in the demo to see if they match up to the latest spec. They may also not work in up-to-date browsers, but this is not a very reliable test, as often the old features continue to be supported for backwards compatibility.</p> + +<div class="note"> +<p><strong>Note</strong>: If the spec has been recently updated so that, say, a method is now defined differently, but the old method still works in browsers, you will often have to document both in the same place, so that the old and new methods are covered. If you need help, refer to demos you have found, or ask an engineering contact.</p> +</div> + +<h3 id="Create_the_list_of_documents_you_need_to_write_or_update">Create the list of documents you need to write or update</h3> + +<p>Reference documents for an API are quite numerous. There is an overview page for the API, a page for each interface, one for each method (including constructors) and property (including event handlers properties). There is also one page per event.</p> + +<h4 id="Overview_page">Overview page</h4> + +<p>The API overview page described the role of the API and the top-level interfaces. Its name is NAME OF API and its slug (that is the end part of the URL) must contains at least one space. It is placed at the top level of the API reference (<a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>)</p> + +<ul> + <li>Title: <em>Web Audio API</em></li> + <li>Slug: <em>Web/API/Web_Audio_API</em></li> + <li>Tags: must include the 'Overview' and 'API' tags</li> +</ul> + +<p>Note that most API have a special sidebar with quicklinks. This sidebar lists all interfaces, and possibly tutorials and related API.</p> + +<h4 id="Interfaces">Interfaces</h4> + +<p>Each interface will have its own page too. It will describe the purpose of the interface and lists all constructors, methods, and properties. The title of the page will be the name of the interface (always starting with an uppercase letter), its slug, the interface name, will be at the top level of the API reference (<a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>)</p> + +<ul> + <li>Title: <em>AudioContext</em></li> + <li>Slug: <em>Web/API/AudioContext</em></li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface.</em></li> +</ul> + +<ul> + <li>Title: <em>AudioNode</em></li> + <li>Slug: <em>Web/API/AudioNode</em></li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface</em>.</li> +</ul> + +<div class="note"> +<p><strong>Note:</strong> We document every property and interface appearing in the <u>prototype</u> of an object implementing this interface. This has the following consequences:</p> + +<ul> + <li>We do not document inherited properties and methods of the interface: they are listed on the respective parent interface. We do hint at their existence though.</li> + <li>We do document properties and methods defined in mixins, though we use the mixin name as interface name. (This is not optimal as the mixin name will not appear in the console, but prevents the duplication of documentation. We may revisit this in the future.)</li> + <li>There is one subpage per method, or constructor: if there are several variants, with different parameters, we still create one subpage and use its Syntax section to list all variants.</li> + <li>Special methods like the stringfier (<code>toString()</code>) and the jsonizier (<code>toJSON()</code>) are also listed if they do exist.</li> + <li>Named constructors (like <code>Image()</code> for {{domxref("HTMLImageElement")}} ) are also listed, if relevant.</li> +</ul> +</div> + +<h4 id="Properties">Properties</h4> + +<p>The set of properties of a given interface can be found on its <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#Properties">WebIDL</a>. We document each one in a single page. It will describe the purpose of the property, its syntax, and provide examples of use, in isolation. Its slug is the property name, as a subpage of the interface:</p> + +<ul> + <li>Title: <em>AudioContext.currentTime</em></li> + <li>Slug: <em>Web/API/AudioContext/currentTime</em></li> + <li>Tags: must contain the API name as a tag (here <em>Web Audio API</em>), the interface name (here <em>AudioContext</em>) as well as <em>Property</em>. If the property is read-only, like this example, <em>Read-only</em> must be added too.<br> + </li> + <li>Title: <em>AudioNode.numberOfInputs</em></li> + <li>Slug: <em>Web/API/AudioNode/numberOfInputs</em></li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface</em>.</li> +</ul> + +<div class="note"> +<p><strong>Note:</strong> Event handlers properties (<code>onXYZ</code> properties) are also listed: they'll have their individual subpage, like any other property.</p> +</div> + +<h4 id="Methods">Methods</h4> + +<p>Like for properties, methods are listed on the interface's <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#Methods">WebIDL</a> and we document each method in a single page. It will describe the purpose of the method, its syntax, and provide examples of use, in isolation. Its slug, without the parenthesis, is the method name, as a subpage of the interface:</p> + +<ul> + <li>Title: <em>AudioContext.createBuffer()</em> Note the parentheses, making it clear that it is a method.</li> + <li>Slug: <em>Web/API/AudioContext/createBuffer </em>No parenthesis here.</li> + <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), the interface name (here <em>AudioContext</em>) as well as <em>Method</em>.</li> +</ul> + +<h4 id="Constructors">Constructors</h4> + +<p>Similar in structure to methods, they also have their own pages. Note that only one unnamed constructor may exist per interface. The title convention is slightly different than the one of methods: it isn't prefixed.</p> + +<ul> + <li>Title: <em>Worker() </em>Note the parenthesis and the absence of prefix</li> + <li>Slug: <em>Web/API/Worker/Worker</em> No parenthesis here. Constructors are also subpages of the interface page.</li> + <li>Tags: must include the API name as a tag (here <em>Web Workers</em>), the interface name (here Worker) as well as<em> Constructor</em>.</li> +</ul> + +<h4 id="Events">Events</h4> + +<p>Events are the last type of objects needing documentation. Unless the previous documents, event subpages lies under the Web/Events hierarchy. Each event has its own subpage:</p> + +<ul> + <li>Title: <em>start</em></li> + <li>Slug: <em>Web/Events/start</em></li> +</ul> + +<h4 id="Listing_them_all">Listing them all</h4> + +<p>Creating a list of all these subpages is a good way to track them. For example:</p> + +<ul> + <li>Web_Audio_API</li> + <li>AudioContext + <ul> + <li>AudioContext.currentTime</li> + <li>AudioContext.destination</li> + <li>AudioContext.listener</li> + <li> ...</li> + <li>AudioContext.createBuffer()</li> + <li>AudioContext.createBufferSource()</li> + <li> ...</li> + </ul> + </li> + <li>AudioNode + <ul> + <li>AudioNode.context</li> + <li>AudioNode.numberOfInputs</li> + <li>AudioNode.numberOfOutputs</li> + <li> ...</li> + <li>AudioNode.connect(Param)</li> + <li> ...</li> + </ul> + </li> + <li>AudioParam</li> + <li>Events (update list) + <ul> + <li>start</li> + <li>end</li> + <li>…</li> + </ul> + </li> +</ul> + +<p>Each interface in the list has a separate page created for it as a subpage of https://developer.mozilla.org/en-US/docs/Web/API; for example, the document for {{domxref("AudioContext")}} would be located at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext. Each {{anch("Interface pages", "interface page")}} explains what that interface does and provides a list of the methods and properties that comprise the interface. Then each method and property is documented on its own page, which is created as a subpage of the interface it's a member of. For instance, {{domxref("AudioContext.currentTime")}} is documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/currentTime.</p> + +<p>For example, given the list above, the {{domxref("AudioContext")}} interface is documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext</p> + +<h3 id="Create_the_overview_page">Create the overview page</h3> + +<p>Now create the overview (API landing) page:</p> + +<ol> + <li>Go to <a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a> and, making sure you are logged in, select the <em>Cog icon > New sub-page</em>. You should now be in an editor for a new page.</li> + <li>Enter the title as the API name as defined by the spec, plus "API". So for example "Web Audio API", "IndexedDB API", or "MediaRecorder API".</li> + <li>The Slug should be auto-filled, with underscores in the place of spaces. If it isn't, correct it.</li> + <li>Enter some dummy content into the large content area, such as "TBD" or "Content", then click <em>Save Changes</em>. Or just soar right on into the section {{anch("Overview page")}} and start filling out the real content right away.</li> +</ol> + +<p>Your landing page now exists! Now all you have to do is fill it in, which is discussed in the next section.</p> + +<h2 id="Structure_of_an_overview_page">Structure of an overview page</h2> + +<div class="warning"> +<p><strong>Important</strong>: This section is still a proposal, without consensus yet reached. Don't use it yet.</p> +</div> + +<p>API landing pages will differ greatly in length, depending on how big the API is, but they will all have basically the same features. See <a href="/en-US/docs/Web/API/Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API</a> for an example of a big landing page.</p> + +<p>The features of a landing page are outlined below:</p> + +<ol> + <li><strong>Description</strong>: the first paragraph of the landing page should provide a short, concise description of the API's overarching purpose.</li> + <li><strong>Concepts and usage section</strong>: The next section should be titled "[name of API] concepts and usage", and provide an overview of all the main functionality that the API provides, what problems it solves, and how it works — all at a high level. This section should be fairly short, and not go into code or specific implementation details.</li> + <li><strong>List of interfaces</strong>: This section should be titled "[name of API] interfaces", and provide links to the reference page for each interface that makes up the API, along with a short description of what each one does. See the "Referencing other API features with the \{{domxref}} macro" section for a quicker way to create new pages. Only current interfaces should be in this list; obsolete ones should be placed in (or moved into, if obsoleted after initially being documented) the following section.</li> + <li><strong>Obsolete interfaces:</strong> This section lists obsolete interfaces. <em>Ed. note: should this be a subsection of the main "Interfaces" section above?</em></li> + <li><strong>List of mixins</strong>: If any mixins are defined on the API spec, list them under a separate section, as they aren't interfaces as such.</li> + <li><strong>Example</strong>: This section should show a simple use case for the API.</li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc.</li> + <li><strong>Tags</strong>: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.</li> +</ol> + +<h2 id="Structure_of_an_interface_page">Structure of an interface page</h2> + +<p>Now you should be ready to start writing your interface pages. Each interface reference page should observe the following structure:</p> + +<ol> + <li><strong>\{{APIRef}}</strong>: Include the \{{APIRef}} macro in the first line of each interface page, including the name of the API as an argument, so for example \{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left hand side of the interface page, including properties and methods, and other quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.<br> + <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li> + <li><strong>Standardization status</strong>: The banner indicating the standardization status should be added next (these can be placed on the same line as the \{{APIRef}} macro.): + <ul> + <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li> + <li>\{{Deprecated_header}}</li> + <li>\{{Obsolete_header}}</li> + <li>\{{Non-standard_header}}</li> + </ul> + </li> + <li><strong>Description</strong>: the first paragraph of the interface page should provide a short concise description of the interface's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Note that if the interface defines a mixin, you shouldn't use the term "Interface" to describe it, but mixin instead — it isn't really a standalone interface as such, but a mixin that adds functionality to multiple other interfaces. Similarly, if the interface is actually a dictionary, you should use that term instead of "interface".</li> + <li><strong>Inheritance diagram:</strong> Use the {{TemplateLink("InheritanceDiagram")}} macro to embed an SVG inheritance diagram for the interface. For most interfaces, you won't need any parameters, but if the inheritance chain is long, you may need to use \{{InheritanceDiagram(600, 120)}} to make room vertically for two rows of boxes.</li> + <li> + <p><strong>List of properties, List of methods</strong>: These sections should be titled "Properties" and "Methods", and provide links (using the \{{domxref}} macro) to a reference page for each property/method of that interface, along with a description of what each one does. These should be marked up using description/definition lists, which can be created using the "Definition List", "Definition Term", and "Definition Description" buttons on the MDN editor toolbar. Each description should be short and concise — one sentence if possible. See the "Referencing other API features with the \{{domxref}} macro" section for a quicker way to create links to other pages.<br> + <br> + At the beginning of both sections, before the beginning of the list of properties/methods, indicate inheritance using the appropriate sentence, in italics:<br> + <em>This interface doesn't implement any specific properties, but inherits properties from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em><br> + <em>This interface also inherits properties from </em><em>\{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.<br> + This interface doesn't implement any specific methods, <em>but inherits methods from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em><br> + <em>This interface also inherits methods from </em><em>\{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em></em></p> + + <div class="note"> + <p><strong>Note</strong>: If the interface features event handlers, put these inside the "Properties" section (they are a type of property) under a subheading of "Event handlers".</p> + </div> + + <div class="note"> + <p><strong>Note</strong>: Properties that are read-only should have the \{{readonlyInline}} macro, which creates a nifty little "Read only" badge, included on the same line as their \{{domxref}} links (after the use of the \{{experimentalInline}}, \{{obsoleteInline}}, \{{non-standard_Inline}} and \{{deprecatedInline}} macros, if some of these are needed.</p> + </div> + </li> + <li><strong>Example</strong>: Include a code listing to show typical usage of a major feature of the API. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you could reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">Github gh-pages </a>feature (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page. + <div class="note"> + <p><strong>Note</strong>: More details about writing code examples can be found in the "Examples" section.</p> + </div> + </li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>Polyfill</strong>: If appropriate, include this section, providing code for a polyfill that enables the API to be used even on browsers that don't implement it. If no polyfill exists or is needed, leave this section out entirely.</li> + <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc. We have a liberal policy for linking to external sources, but pay attention: + <ul> + <li>Do not include pages with the same information as another page in the MDN; link to that page instead.</li> + <li>Do not put author names — we are a writer-neutral documentation site. Link to the document; the author name will be displayed there.</li> + <li>Pay special attention to blog posts: they tend to become outdated (old syntax, wrong compat information). Link to them only if they have a clear added value that can't be found in a maintained document.</li> + <li>Do not use action verb like "See … for more information" or "Click to…", you don't know if your reader is able to see, or to click on the link (like on a paper version of the document).</li> + </ul> + </li> + <li><strong>Tags</strong>: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.</li> +</ol> + +<h3 id="Interface_page_examples">Interface page examples</h3> + +<p>The following are exemplary examples of Interface pages:</p> + +<ul> + <li>{{domxref("Request")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li> + <li>{{domxref("SpeechSynthesis")}} from the <a href="/en-US/docs/Web/API/Web_Speech_API">Web Speech API</a>.</li> +</ul> + +<h2 id="Structure_of_a_property_page">Structure of a property page</h2> + +<p>You can now fill in your interface property pages. Since the structures of all of them are the same, it usually works best to open all the property pages for each interface in separate tabs. From here you can fill one in fully, then copy its contents to all the other property pages and just update the bits that need changing, rather than having to fill each one in from scratch.</p> + +<p>Edit the property page name to follow the <code>Interface.property_name</code> convention.</p> + +<p>Property pages must have the following sections:</p> + +<ol> + <li><strong>Title</strong>: the title of the page must be <strong>InterfaceName.propertyName</strong>. The interface name must start with a capital letter. Although an interface is implemented in JavaScript on the prototype of objects, we don't include <code>.prototype.</code> in the title, like we do in the <a href="/en-US/docs/Web/JavaScript/Reference">JavaScript reference</a>.</li> + <li><strong>\{{APIRef}}</strong>: Include the \{{APIRef}} macro in the first line of each property page, including the name of the API as an argument, so for example \{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left hand side of the interface page, including properties and methods, and other quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.<br> + <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li> + <li><strong>Standardization status</strong>: The banner indicating the standardization status should be added next to the interface name (these can be placed on the same line as the \{{APIRef}} macro): + <ul style="margin-left: 40px;"> + <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li> + <li>\{{Deprecated_header}}</li> + <li>\{{Obsolete_header}}</li> + <li>\{{Non-standard_header}}</li> + </ul> + </li> + <li><strong>Description</strong>: the first paragraph of the property page should provide a short, concise description of the property's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default/initial value, and whether it's read only or not. The structure of the first sentence must be: + <dl> + <dt>For read-only properties</dt> + <dd>The <code><strong>InterfaceName.property</strong></code> read-only property returns a \{{domxref("type")}} that...</dd> + <dt>For other properties</dt> + <dd>The <strong><code>InterfaceName.property</code></strong> property is a \{{domxref("type")}} that…</dd> + </dl> + + <div class="note"><strong>Note</strong>: <code>InterfaceName.property</code> should be in <code><code></code>, and should additionally be in bold (<code><strong></code>) the first time it's used.</div> + </li> + <li><strong>Syntax</strong>: The syntax section should show how to get the property, and how to set it, if it's not read only. Use the <code>syntaxbox</code> class for it and italics for part to be replaced by the actual variable name. For example: + <pre class="syntaxbox">var <em>myType</em> = <em>oscillator</em>.type; +<em>oscillator</em>.type = <em>aType;</em> +</pre> + The syntax section should also have a subsection — "Value", which will contain a description of the property's value. This should contain the data type of the property, and what it represents. For an example, see {{domxref("SpeechRecognition.grammars")}}</li> + <li> + <p><strong>Example</strong>: Include a code listing to show typical usage of the property in question. You should start with a simple example that shows how an object of the type is created and how to access the property. More complex examples can be added after such an example. In these additional examples, rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you can reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">github gh-pages feature</a> (so long as it uses only client-side code of course.) You can also make use of the <a href="/en-US/docs/MDN/Contribute/Tools/Sample_server">MDN Sample Server</a>, which is particularly helpful for more complex samples. If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page.</p> + + <div class="note"><strong>Note</strong>: If you make use of Github, the example must live under <a href="https://github.com/mdn/">github.com/mdn</a>. See the "Examples" section for more details.</div> + </li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when using this technology: like methods and properties affected by a change of this property or events thrown in relation to it. More links useful when learning about this technology, including MDN (and external) tutorials, examples, libraries,… can be added, though it may be useful to consider adding them on the interface reference page instead.</li> + <li><strong>Tags</strong>: There is a set of standard tags you should include for each property page — see the "Tags" section for more.</li> +</ol> + +<h3 id="Property_page_examples">Property page examples</h3> + +<p>The following are exemplary examples of property pages:</p> + +<ul> + <li>{{domxref("Request.method")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li> + <li>{{domxref("SpeechSynthesis.speaking")}} from the <a href="/en-US/docs/Web/API/Web_Speech_API">Web Speech API</a>.</li> +</ul> + +<h2 id="Structure_of_a_method_page">Structure of a method page</h2> + +<p>You can now fill in your interface method pages. Since the structure of all of them are the same, one possible way of doing it is to open all the method pages for each interface in separate tabs. From here you can fill one in fully, then copy its contents to all the other method pages and just update the bits that need changing, rather than having to fill each one in from scratch.</p> + +<p>Method pages need the following sections:</p> + +<ol> + <li><strong>Title</strong>: the title of the page must be <strong>InterfaceName.method()</strong> (with the two terminal parentheses), but the slug (the end of the page URL) must not include the brackets. Also the interface name must start with a capital. Although an interface is implemented in JavaScript on the prototype of objects, we don't put <code>.prototype.</code> in the title, like we do in the <a href="/en-US/docs/Web/JavaScript/Reference">JavaScript reference</a>.</li> + <li><strong>\{{APIRef}}</strong>: Include the \{{APIRef}} macro in the first line of each method page, including the name of the API as an argument, so for example \{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left hand side of the interface page, including properties and methods, and other quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.<br> + <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li> + <li><strong>Standardization status</strong>: Next, the banner indicating the standardization status should be added (these can be placed on the same line as the \{{APIRef}} macro): + <ul> + <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li> + <li>\{{Deprecated_header}}</li> + <li>\{{Obsolete_header}}</li> + <li>\{{Non-standard_header}}</li> + </ul> + </li> + <li><strong>Description</strong>: The first paragraph of the method page should provide a short concise description of the method's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default parameter values, any theory that the method relies on, and what the parameter values do. + <dl> + <dt>The beginning of the first sentence must follow the following structure:</dt> + <dd>The <strong>InterfaceName.method()</strong> method interface ...</dd> + </dl> + + <div class="note"><strong>Note:</strong> <code>InterfaceName.method()</code> should be in <code><code></code>, and should also be in bold (<code><strong></code>) the first time it's used.</div> + </li> + <li><strong>Syntax</strong>: The syntax section should include a 2–3 line example — usually just construction of the interface, then calling of the interface method. + <dl> + <dt>The syntax should be of the form:</dt> + <dd>var <em>returnValue</em> = <em>ifName</em>.method(<em>param1</em>, <em>param2</em>, ...)</dd> + <dt>If the method has no return value (<code>void</code> as return value in the webidl), use:</dt> + <dd><em>ifName</em>.method(<em>param1</em>, <em>param2</em>, ...)</dd> + </dl> + The syntax section should include three subsections (see {{domxref("SubtleCrypto.sign()")}} for an example): + + <ul> + <li>"Parameters": This should contain a definition list (or unordered list) that names and describes the different parameters the method takes. You should include the {{optional_inline}} macro next to the parameter name, in the case of optional parameters. If there are no parameters, this section should be omitted.</li> + <li>"Return value": This should say what return value the method has, be it a simple value like a double or boolean, or a more complex value like another interface object, in which case you can use \{{domxref}} macro to link to the MDN API page covering that interface (if it exists.) A method might return nothing, in which case the return value should be written as "\{{jsxref('undefined')}}" (which will look like this in the rendered page: {{jsxref("undefined")}}).</li> + <li>"Exceptions": This should list the different exceptions that can be raised when invoking the method, and what circumstances cause them. If there are no exceptions, this section should be omitted.</li> + </ul> + </li> + <li><strong>Example</strong>: Include a code listing to show typical usage of the method in question. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you should reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">Github gh-pages feature</a> (so long as it uses only client-side code of course.) You can also make use of the <a href="/en-US/docs/MDN/Contribute/Tools/Sample_server">MDN Sample Server</a>, which is particularly helpful for more complex samples. See the "Examples" section for more details. If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page.</li> + <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li> + <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li> + <li><strong>Polyfill</strong>: If appropriate (especially if common browsers are still shipping without support for the method), you can include a section which includes the code for a polyfill to allow the API to be used in browsers that don't implement it.</li> +</ol> + +<h3 id="Method_page_examples">Method page examples</h3> + +<p>The following are exemplary examples of Interface pages:</p> + +<ul> + <li>{{domxref("Document.getAnimations()")}} from the <a href="/en-US/docs/Web/API/Web_Animations_API">Web Animations API</a>.</li> + <li>{{domxref("GlobalFetch.fetch()")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li> +</ul> + +<h2 id="Tagging">Tagging</h2> + +<p>For API reference pages, there are standard tags that all pages should have:</p> + +<ul> + <li>"API"</li> + <li>"Reference"</li> + <li>Name of API (e.g. "Web Audio API")</li> + <li>Any pertinent related keywords (e.g. "audio") </li> +</ul> + +<p>For Interface pages, also add:</p> + +<ul> + <li>"Interface"</li> + <li>The name of the interface, e.g. "AudioContext"</li> +</ul> + +<p>For method pages, also add:</p> + +<ul> + <li>"Method"</li> + <li>The name of the interface the method relates to, e.g. "AudioContext"</li> + <li>The name of the method, e.g. "createBuffer"</li> +</ul> + +<p>For property pages, also add:</p> + +<ul> + <li>"Property"</li> + <li>The name of the interface the property relates to, e.g. "AudioContext"</li> + <li>The name of the property, e.g. "currentTime" </li> +</ul> + +<p>In all cases, also add a keyword indicating the standardization status:</p> + +<ul> + <li>Experimental (if the spec is not a CR)</li> + <li>Deprecated</li> + <li>Obsolete</li> + <li>Non-standard</li> +</ul> + +<p>These tags will be used to generate correct quicklinks, with nice icons. See <a href="/en-US/docs/MDN/Contribute/Howto/Tag">How to properly tag pages</a> for additional information on tagging, as well as about other tags you may find useful.</p> diff --git a/files/zh-cn/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html new file mode 100644 index 0000000000..239c6a83f4 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html @@ -0,0 +1,505 @@ +--- +title: Information contained in a WebIDL file +slug: >- + MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file +translation_of: >- + MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file +--- +<div> +<p><font><font>{{MDNSidebar}}</font></font></p> + +<p><font><font>在编写有关API的文档时，信息来源很多：规范描述了应该实现的内容以及模型，实现描述了实际放在浏览器中的内容。</font><font>WebIDL文件是一种非常简洁的方式，可以提供很多（但不是全部）有关API的信息。</font><font>本文档提供了有助于理解WebIDL语法的参考。</font></font></p> + +<p><font><font>IDL代表</font></font><em><strong><font><font>接口定义语言</font></font></strong></em><font><font>，它用于描述API。</font><font>在更广泛的计算领域，有几种IDL。</font><font>在浏览器领域，我们使用的IDL称为</font></font><em><font><font>WebIDL</font></font></em><font><font>。</font><font>有两种WebIDL可用：WebIDL规范中给出的一种，以及在浏览器中实现的一种。</font><font>规范是规范引用，浏览器WebIDL描述了在特定浏览器中实际实现的内容，并包含其他内容，例如注释和有关非标准元素的信息。</font></font></p> +</div> + +<p> </p> + +<h2 id="在哪里可以找到WebIDL文件"><font><font>在哪里可以找到WebIDL文件</font></font></h2> + +<p><font><font>WebIDL可以在多个位置找到：</font></font></p> + +<ul> + <li><font><font>每个规范在文本中都包含WebIDL：它是一种传达精确定义的非常方便的方法。</font><font>这些描述了API的语法。</font><font>虽然是规范参考，但我们必须记住，它们可能与实际实施不同。</font><font>在MDN上，我们希望实用并记录Web平台的真正含义，而不是理想应该是什么。</font><font>因此，请仔细检查实现中的内容（如果发现错误，请不要犹豫，立即提交）。</font></font></li> + <li><font><font>三个浏览器引擎使用（修改）WebIDL作为其工具链的一部分：Gecko，Chromium / Blink和WebCore / WebKit。</font><font>Edge在内部使用它，但遗憾的是它们不公开（它会帮助我们很多）。</font></font> + <ul> + <li><font><font>对于Gecko，所有WebIDL文件都分组在一个目录中：</font></font><a href="https://dxr.mozilla.org/mozilla-central/source/dom/webidl/">https://dxr.mozilla.org/mozilla-central/source/dom/webidl/</a><font><font> </font></font></li> + <li><font><font>他们的延伸是</font></font><code>.webidl</code><font><font>。</font></font><code>*.idl</code><font><font>Gecko源代码树中</font><font>还有其他 </font><font>文件，但它们不是WebIDL，因此您可以忽略它们。</font><font>旧版本的Gecko有一些WebIDL分散在某些地方，甚至可能使用Mozilla的IDL而不是WebIDL来描述一些Web界面，但这在任何最近的Gecko代码中都不会成为问题。</font></font></li> + <li><font><font>对于Chromium，它们分散在源代码中，所以你需要多花点功夫：例如</font></font><a href="http://src.chromium.org/viewvc/blink/trunk/Source/modules/mediastream/MediaStream.idl"><font><font>http://src.chromium.org/viewvc/blink/trunk/Source/modules/mediastream/MediaStream.idl</font></font></a></li> + <li><font><font>同样，WebCore正如预期的那样，因为Chromium是从它分叉出来的，例如</font></font><a href="https://github.com/WebKit/webkit/blob/master/Source/WebCore/html/DOMTokenList.idl"><font><font>https://github.com/WebKit/webkit/blob/master/Source/WebCore/html/DOMTokenList.idl</font></font></a> </li> + </ul> + </li> +</ul> + +<h2 id="Different_dialects_of_WebIDL">Different dialects of WebIDL</h2> + +<p>WebIDL is defined in <a href="https://heycam.github.io/webidl/">its specification</a>. But it has been designed to be extended to convey more information, and browser vendors have done so:</p> + +<ul> + <li>For Gecko, MDN has the <a href="/en-US/docs/Mozilla/WebIDL_bindings">documentation</a> of its dialectal WebIDL.</li> + <li>For Chromium, Google also created a <a href="https://www.chromium.org/blink/webidl">document</a> to describe its extensions.</li> + <li>For WebCore, Apple also made available a <a href="https://trac.webkit.org/wiki/WebKitIDL">page</a> for its dialect.</li> +</ul> + +<div class="note"> +<p>We describe here only the subset of WebIDL which is most useful when writing documentation. There are many more annotations useful for implementers; refer to the four documents linked above to have a complete overview.</p> +</div> + +<h2 id="Interfaces">Interfaces</h2> + +<p>This section explains the WebIDL syntax that describes overall API features.</p> + +<h3 id="Name_of_the_interface">Name of the interface</h3> + +<p>The interface name is the string that appears after the keyword <code>interface</code><em> </em>and before the next opening bracket (<code>'{'</code>) or colon (<code>':'</code>).</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>interface</strong> URL {};</span></pre> + +<p>Each WebIDL interface, being a true interface or a mixin, has its own page in the documentation, listing every constructor, property and method defined for it.</p> + +<h3 id="Inheritance_chain">Inheritance chain</h3> + +<p>The parent, if any, of a given interface is defined after the interface name, following a colon (<code>':'</code>). There can be only one parent per interface.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">interface HTMLMediaElement : <strong>HTMLElement</strong> {…}</span></pre> + +<p><span>The inheritance chain is listed automatically in the sidebar (using the \{{APIRef}} macro). It can also be added as an SVG image via the macro \{{InheritanceDiagram}}.</span></p> + +<h3 id="Mixins">Mixins</h3> + +<p>Some properties or methods are available to several interfaces. To prevent redefinition they are defined in special WebIDL interfaces called <em>mixins</em>. In the WebIDL, they are prefixed using the <code>[NoInterfaceObject]</code> annotation. The name of a mixin, <code>Body</code> in the following example, doesn't appear in JavaScript.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[NoInterfaceObject]</strong> + <strong>interface</strong> Body {…}</span></pre> + +<p>For documentation purposes, we create a mixin page, with the same structure as an interface page. As they are not true interfaces, the word <em>interface</em> is not used — <em>mixin</em> is used instead.</p> + +<p>Mixin methods and properties are listed in the same way as regular methods and properties:</p> + +<ul> + <li>They have their own pages, prefixed with the mixin name. E.g {{domxref('Body.bodyUsed')}} or {{domxref('Body.blob()')}}.</li> + <li>They are listed on the interface page when the interface <em>implements</em> the mixin. Unlike regular properties and methods, they are prefixed with the mixin name and not the interface name. You can see <code>Body</code> properties and methods listed on both {{domxref('Request')}} and {{domxref('Response')}} interfaces, as they both implement the <code>Body</code> mixin.</li> +</ul> + +<p>Mixins implemented on an interface are defined using the <code>implements</code> keyword.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">Request <strong>implements</strong> Body; +Response <strong>implements</strong> Body;</span></pre> + +<div class="note"> +<p><span><strong>Note:</strong> Mixin names do not appear in a Web developer console. We shouldn't show them, but we currently do this as it saves us from duplicating content, which would lead to a maintenance issue. We do this if the mixin is only used in one interface (such cases are bugs in the relevant specs — they shouldn't be defined as mixins, but as partial interfaces.)</span></p> +</div> + +<h3 id="Availability_in_workers"><span>Availability in workers</span></h3> + +<p>Availability in Web workers (of any type) and on the Window scope is defined using an annotation: <code>[Exposed=(Window,Worker)]</code>. The annotation applies to the partial interface it is listed with. If no annotation is available, the default value is <code>Window</code>.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Exposed=(Window,Worker)]</strong> +interface Performance { + [DependsOn=DeviceState, Affects=Nothing]<a class="l d1" href="http://mxr.mozilla.org/mozilla-central/source/dom/webidl/Performance.webidl#19"> +</a> DOMHighResTimeStamp now(); +};</span> + +<strong>[Exposed=Window]</strong> +partial interface Performance { + [Constant] + readonly attribute PerformanceTiming timing; + [Constant] + readonly attribute PerformanceNavigation navigation; + + jsonifier; +};</pre> + +<p>In this case <code>Performance.now()</code> is available on the <code>Window</code> scope and to any worker, while <code>Performance.timing</code>, <code>Performance.navigation</code> and <code>Performance.toJSON()</code> are not available to Web workers.</p> + +<p>The most common values for the <code>[Exposed]</code> are:</p> + +<dl> + <dt><code>Window</code></dt> + <dd>The partial interface is available to the {{domxref('Window')}} global scope.</dd> + <dt><code>Worker</code></dt> + <dd>The partial interface is available to any kind of worker, that is if the global scope is a descendant of {{domxref('WorkerGlobalScope')}} — {{domxref('DedicatedWorkerGlobalScope')}}, {{domxref('SharedWorkerGlobalScope')}}, or {{domxref('ServiceWorkerGlobalScope')}} (It also is available to <code>ChromeWorker</code>, but we don't document this as they are not visible on the Web and are internal to Firefox.)</dd> + <dt><code>DedicatedWorker</code></dt> + <dd>The partial interface is available to the {{domxref('DedicatedWorkerGlobalScope')}} only.<code> </code></dd> + <dt><code>SharedWorker</code></dt> + <dd>The partial interface is available to the {{domxref('SharedWorkerGlobalScope')}} only.</dd> + <dt><code>ServiceWorker</code></dt> + <dd>The partial interface is available to the {{domxref('ServiceWorkerGlobalScope')}} only.</dd> +</dl> + +<p>Another value is possible, like <code>System</code>, but this has a <a href="/en-US/docs/Mozilla/WebIDL_bindings#Exposed">special meaning</a> and doesn't need to be documented.</p> + +<p>Note that these possible values are themselves defined in WebIDL files. Interfaces may have a <code>[Global=xyz]</code> annotation. It means that when an object of this type is used as a global scope, any interface, property or method, with <code>xyz</code> as a value of <code>[Exposed]</code> is available.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[Global=(Worker,DedicatedWorker), Exposed=DedicatedWorker] +interface DedicatedWorkerGlobalScope : WorkerGlobalScope {…}</span></pre> + +<p>Here, it is defined that when the global scope is of type <code>DedicatedWorkerGlobalScope</code>, that is if we are in a dedicated worker, any interface, property or method exposed – using the <code>[Exposed]</code> annotation – to <code>Worker</code> or <code>DedicatedWorker</code> is available.</p> + +<p>Even the primary global is defined in WebIDL. The primary global is the value of an <code>[Exposed]</code> annotation when not present. This is defined using the <code>[PrimaryGlobal]</code> annotation and is present on {{domxref('Window')}}:</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[PrimaryGlobal, NeedResolve] +/*sealed*/ interface Window : EventTarget {…}</span></pre> + +<h3 id="Preferences">Preferences</h3> + +<div class="note"> +<p><strong>Note:</strong> this information is specific to Gecko and should only be used in the Browser compatibility section.</p> +</div> + +<p>In Gecko, the availability of a partial interface, including its constructor, properties and methods may be controlled by a preference (usually called a "pref"). This is marked in the WebIDL too.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Pref="media.webspeech.synth.enabled"]</strong> +interface SpeechSynthesis { + readonly attribute boolean pending; + readonly attribute boolean speaking; + readonly attribute boolean paused; +};</span></pre> + +<p><span>Here <code>media.webspeech.synth.enabled</code> controls the <code>SpeechSynthesis</code> interface and its properties (the full listing has more than 3.)</span></p> + +<div class="note"> +<p><span><strong>Note:</strong> the default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)</span></p> +</div> + +<h2 id="Properties">Properties</h2> + +<p>You can recognize the definition of a property by the presence of the <code>attribute</code> keyword.</p> + +<h3 id="Name_of_the_property">Name of the property</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">readonly attribute MediaError? <strong>error</strong>;</span></pre> + +<p>In the above example the name of the property is <code>error</code>; in the docs we will refer to it as <code>HTMLMediaElement.error</code> as it belongs to the <code>HTMLMediaElement</code> interface. Linking to the page is either done <strong>with</strong> the interface prefix using \{{domxref('HTMLMediaElement.error')}} or <strong>without</strong> the prefix using \{{domxref('HTMLMediaElement.error', 'error')}} when the context is obvious and unambiguous.</p> + +<h3 id="Type_of_the_property">Type of the property</h3> + +<pre class="syntaxbox"><span id="the-code">readonly attribute <strong>MediaError?</strong> error;</span></pre> + +<p><span>The property value is an object of type <code>MediaError</code>. The question mark (<code>'?'</code>) indicates that it can take a value of <code>null</code>, and the documentation must explain <em>when</em> this may occur. If no question mark is present, the <code>error</code> property can't be <code>null</code>.</span></p> + +<h3 id="Writing_permissions_on_the_property"><span>Writing permissions on the property</span></h3> + +<pre class="syntaxbox"><span id="the-code"><strong>readonly</strong> attribute MediaError? error;</span></pre> + +<p><span>If the keyword <code>readonly</code> is present, the property can't be modified. It must be marked as read-only:</span></p> + +<ul> + <li><span>In the interface, by adding the \{{ReadOnlyInline}} macro next to its definition term.</span></li> + <li><span>In the first sentence of its own page, by starting the description with: <em>The read-only <code><strong>HTMLMediaElement.error</strong></code> property…</em></span></li> + <li><span>By adding the <code>Read-only</code> tag to its own page.</span></li> + <li><span>By starting its description in the interface page with <em>Returns…</em></span></li> +</ul> + +<div class="note"> +<p><span><em><strong>Note:</strong> Only read-only properties can be described as 'returning' a value. Non read-only properties can also be used to set a value.</em></span></p> +</div> + +<ul> +</ul> + +<h3 id="Throwing_exceptions">Throwing exceptions</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[SetterThrows]</strong> + attribute DOMString src;</span></pre> + +<p><span>In some cases, like when some values are illegal, setting a new value can lead to an exception being raised. This is marked using the <code>[SetterThrows]</code> annotation. When this happens, the Syntax section of the property page <em>must</em> have an Exceptions subsection. The list of exceptions and the conditions to have them thrown are listed, as textual information, in the specification of that API.</span></p> + +<p><span>Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. <a href="http://heycam.github.io/webidl/#es-enumeration">Trying to set an illegal enumerated value</a> (mapped to a JavaScript {{jsxref('String')}}) raises a {{exception('TypeError')}} exception. This must be documented, but is only implicitly marked in the WebIDL document.</span></p> + +<p><span>It is uncommon to have getters throwing exceptions, though it happens in a few cases. In this case the <code>[GetterThrows]</code> annotation is used. Here also, the Syntax section of the property page <em>must</em> have an Exceptions subsection.</span></p> + +<pre class="syntaxbox"><code id="line-16">partial interface Blob {</code><code id="line-17"> +</code><code id="line-18"> <strong>[GetterThrows]</strong> +</code><code id="line-19"> readonly attribute <span class="k">unsigned</span> <span class="k">long</span> <span class="k">long</span> size; +};</code> +</pre> + +<h3 id="Not_throwing_exceptions">Not throwing exceptions</h3> + +<p>When the semantics of Webidl is not followed, an exception is often thrown, even without <code>[SetterThrows]</code> or <code>[GetterThrows]</code> set. For example, in strict mode, if we try to set a read-only property to a new value, that is to call its implicit setter, a read-only property will throw in strict mode.</p> + +<p>Mostly for compatibility purpose, this behavior is sometimes annoying. To prevent this by creating a no-op setter (that is by silently ignoring any attempt to set the property to a new value), the <code>[LenientSetter]</code> annotation can be used.</p> + +<pre class="syntaxbox"><code id="line-223">partial interface Document {</code><code id="line-225"><span class="c"> +</span></code><code id="line-226"><strong> [LenientSetter]</strong> +</code><code id="line-227"> readonly attribute boolean fullscreen;</code><code id="line-229"> +</code><code id="line-230"><strong> [LenientSetter]</strong> +</code><code id="line-231"> readonly attribute boolean fullscreenEnabled; +};</code> +</pre> + +<p>In these cases, an extra sentence is added to the description of the property. E.g</p> + +<p><em>Although this property is read-only, it will not throw if it is modified (even in strict mode); the setter is a no-operation and it will be ignored.</em></p> + +<h3 id="New_objects_or_references"><span>New objects or references</span></h3> + +<p><span>The return value of a property can be either a copy of an internal object, a newly created synthetic object, or a reference to an internal object.</span></p> + +<p><span>Basic objects with types like {{jsxref("String")}} (being an IDL <code>DOMString</code>, or other), {{jsxref("Number")}} (being an IDL <code>byte</code>, <code>octet</code>, <code>unsigned int</code>, or other), and {{jsxref("Boolean")}} are always copied and nothing special has to be noted about them (it is natural behavior expected by a JavaScript developer.)</span></p> + +<p><span>For interface objects, the default is to return a <em>reference</em> to the internal object. This has to be mentioned both in the short description in the interface page, and in the description in the specific sub-pages.</span></p> + +<div class="note"> +<p><span><strong>Note:</strong> The keyword <code>readonly</code> used with a property returning an object applies to the <u>reference</u> (the internal object cannot be changed.) The properties of the returned object can be changed, even if they are marked as read-only in the relevant interface.</span></p> +</div> + +<p>Sometimes an API must return a <em>new</em> object, or a <em>copy</em> of an internal one. This case is indicated in the WebIDL using the <code>[NewObject]</code> annotation.</p> + +<pre class="syntaxbox" lang="en"><strong>[NewObject]</strong> + readonly attribute TimeRanges buffered;</pre> + +<p>In this case, each call to <code>buffered</code> returns a different object: changing it will not change the internal value, and a change in the internal value will not affect each object instance. In the documentation, we will mark it by using the adjective <em>new</em> next to object:</p> + +<p><em>The <strong><code>HTMLMediaElement.buffered</code></strong> read-only property returns a new \{{domxref("TimeRanges")}} object that… </em></p> + +<p>and</p> + +<dl> + <dt><em>\{{domxref("HTMLMediaElement.buffered")}}\{{readonlyinline}}</em></dt> + <dd><em>Returns a new \{{domxref("TimeRanges")}} object that …</em></dd> +</dl> + +<p>In the case of a reference to a collection object (like <code>HTMLCollection</code>, <code>HTMLFormElementsCollection</code>, or <code>HTMLOptionsCollection</code>, always without <code>[NewObject]</code>), we make it explicit that changes to the underlying object will be available via the returned reference. To mark this, we qualify the collection as a <strong>live </strong><code>HTMLCollection</code><strong> </strong>(or <code>HTMLFormElementsCollections</code>, or <code>HTMLOptionsCollection</code>), both in the interface description and in the subpage.</p> + +<p>E.g.</p> + +<dl> + <dt>\{{domxref("HTMLFormElement.elements")}}\{{readonlyinline}}</dt> + <dd>Returns a live \{{domxref("HTMLFormControlsCollection")}} containing…</dd> +</dl> + +<h3 id="Availability_in_workers_2"><span>Availability in workers</span></h3> + +<p>Individual property availability in workers is also found in the WebIDL. For a property, the default is the same availability as the <code>interface</code> (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the <code>partial interface</code> it is defined in.</p> + +<p>For documentation, the subpage must contain a sentence indicating if it is available or not in Web workers, right before the "Syntax" section.</p> + +<h3 id="Preferences_2">Preferences</h3> + +<div class="note"> +<p>This information is specific to Gecko and should only be used in the Browser compatibility section.</p> +</div> + +<p>In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Pref="media.webvtt.enabled"]</strong> + readonly attribute TextTrackList? textTracks;</span></pre> + +<p><span>Here <code>media.webvtt.enabled</code> controls the <code>textTracks</code> property. </span></p> + +<div class="note"> +<p><span>The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another).</span></p> +</div> + +<h2 id="Methods">Methods</h2> + +<p>You can recognize the definition of a method by the presence of parentheses after the name.</p> + +<h3 id="Name_of_the_method">Name of the method</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">DOMString <strong>canPlayType</strong>(DOMString type);</span></pre> + +<p>The name of the method is <code>canPlayType</code>, and we will refer to it as <code>HTMLMediaElement.canPlayType()</code> (with the parentheses that indicate that it is a method) in the docs, as it belongs to the <code>HTMLMediaElement</code> interface. Linking to the page is either done <strong>with</strong> the interface prefix using \{{domxref('HTMLMediaElement.canPlayType()')}}, or <strong>without</strong> the prefix using \{{domxref('HTMLMediaElement.canPlayType', 'canPlayType()')}} when the context is obvious and unambiguous. The parentheses should always be included.</p> + +<h3 id="Parameters">Parameters</h3> + +<pre class="syntaxbox"><span id="the-code">TextTrack addTextTrack(TextTrackKind <strong>kind</strong>, + optional DOMString <strong>label</strong> = "", + optional DOMString <strong>language</strong> = "");</span></pre> + +<p>The parameters of a method are listed in the Syntax section of the method sub-page. They are listed in the WebIDL in order, between the parenthesis, as a comma-separated list. Each parameter has a name (indicated above) and a type (e.g. a <code>'?'</code> means that the <code>null</code> value is valid.) If marked <code>optional</code>, the parameter is optional to include in a method call and must have the \{{OptionalInline}} flag included when it is listed in the Syntax section. The parameter's default value is listed after the equality sign (<code>'='</code>).</p> + +<h3 id="Type_of_the_return_value">Type of the return value</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">DOMString <strong>canPlayType</strong>(DOMString type);</span></pre> + +<p><span>The return value type is indicated first inside the parentheses — in the above case the value is an object of type <code>DOMString</code>. if followed by a question mark (<code>'?'</code>), a value of <code>null</code> can be returned too, and the documentation must explain <em>when</em> this may happen. If no question mark is present, like here, the return value can't be <code>null</code>.</span></p> + +<p><span>The keyword <code>void</code> means that there is no return value. It is not a return value type. If the WebIDL entry reads <code>void</code>, the <em>Return value</em> section in the docs should contain only a simple <em>None</em>.</span></p> + +<h3 id="Throwing_exceptions_2">Throwing exceptions</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Throws]</strong> + void fastSeek(double time);</span></pre> + +<p><span>Some methods can throw exceptions. This is marked using the <code>[Throws]</code> annotation. When this happens, the Syntax section of the method page <em>must</em> have an Exceptions subsection. The list of exceptions and the conditions to have them thrown are listed, as textual information, in the specification of that API.</span></p> + +<p><span>Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. <a href="http://heycam.github.io/webidl/#es-enumeration">Trying to set an illegal enumerated value</a> (mapped to a JavaScript {{jsxref('String')}}) as a parameter will raise a {{exception('TypeError')}} exception. This must be documented, but it is only implicitly marked in the WebIDL document.</span></p> + +<p><span>Have a look at one of these <a href="https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#Exceptions"><em>Exceptions</em> sections</a>.</span></p> + +<h3 id="Availability_in_workers_3"><span>Availability in workers</span></h3> + +<p>Individual method availability in workers is also found in the WebIDL. For a method, the default is the same availability as the <code>interface</code> (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the <code>partial interface</code> it is defined it.</p> + +<p>For the documentation, the sub-page must contain a sentence indicating if it is available in Web workers, right before the Syntax section.</p> + +<h3 id="Preferences_3">Preferences</h3> + +<div class="note"> +<p><strong>Note:</strong> this information is specific to Gecko and should only be used in the Browser compatibility section.</p> +</div> + +<p>In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code"><strong>[Pref="media.webvtt.enabled"]</strong> + TextTrack addTextTrack(TextTrackKind kind, + optional DOMString label = "", + optional DOMString language = "");</span></pre> + +<p><span>Here <code>media.webvtt.enabled</code> controls the <code>addTextTrack()</code> method. </span></p> + +<div class="note"> +<p><span><strong>Note:</strong> The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)</span></p> +</div> + +<h3 id="sect1"> </h3> + +<h2 id="Special_methods">Special methods</h2> + +<p>Some methods are not listed as regular methods in WebIDL but instead as special keywords, which translate to specific standard JavaScript methods.</p> + +<h3 id="toString()_and_toJSON()">toString() and toJSON()</h3> + +<p>A stringifier is mapped to <code>toString()</code> and defined as:</p> + +<pre class="syntaxbox"><strong><span id="the-code">stringifier;</span></strong></pre> + +<p>The <code>toString()</code> method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Range.toString()")}})</p> + +<p>A jsonifier is mapped to <code>toJSON()</code> and defined as:</p> + +<pre class="syntaxbox" lang="en"><strong><span id="the-code">jsonifier; </span></strong><span>// Gecko version</span><strong><span> +serializer;</span></strong><span> // Standard version</span> +</pre> + +<p>The <code>toJSON()</code> method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Performance.toJSON()")}})</p> + +<div class="note"> +<p><strong>Note:</strong> the WebIDL specification uses <code>serializer</code> instead of <code>jsonifier</code>. This is not used in Gecko — only the non-standard likely early proposal <code>jsonifier</code> is found in mozilla-central.</p> +</div> + +<p> </p> + +<h3 id="Iterator-like_methods">Iterator-like methods</h3> + +<p>An interface may be defined as <em>iterable</em>, meaning that it will have the following methods: <code>entries()</code>, <code>keys()</code>, <code>values()</code> and <code>forEach()</code>. They also supports the use of {{jsxref("Statements/for...of", "for...of")}} on an object implementing this interface.</p> + +<p>There are two kinds of iteration possible: the <em>value iterator</em> and the <em>pair iterator.</em></p> + +<h4 id="Value_iterator">Value iterator</h4> + +<pre class="syntaxbox">iterable<<em>valueType</em>></pre> + +<p>The iterator will iterate over values of type <em>valueType</em>. The generated methods will be:</p> + +<ul> + <li><code>entries()</code>, which returns an {{jsxref('iterator')}} on the indexes (that are <code>unsigned long</code>).</li> + <li><code>values()</code>, which returns an {{jsxref('iterator')}} on the values.</li> + <li><code>keys()</code>, which returns an {{jsxref('iterator')}} on the keys, that are its indexes (that are <code>unsigned long</code>). In the case of value iterators, <code>keys()</code> and <code>entries()</code> are identical.</li> + <li><code>forEach()</code>, which returns an {{jsxref('iterator')}} on the keys that calls a given callback function one for each entry in the list.</li> +</ul> + +<p>Such an iterator allows to use the syntax <code>for (var p in object)</code> as a shorthand of <code>for (var p in object.entries())</code>. We add a sentence about it in the interface description.</p> + +<div class="note"> +<p><strong>Note:</strong> the value pairs to iterate over can be defined in two different ways:</p> + +<ol> + <li>Outside the webidl file, in the prose accompanying it. Such a prose is in the spec and usually starts with: <em>"The <a class="external" href="https://heycam.github.io/webidl/#dfn-values-to-iterate-over">values to iterate over</a>…"</em>.</li> + <li>In the webidl file, implicitly, if the interface supports indexed properties, that is when the interface has a <code>getter</code> methods with a parameter of type <code>unsigned long</code>.</li> +</ol> +</div> + +<h4 id="Pair_iterator">Pair iterator</h4> + +<pre class="syntaxbox">iterable<<em>keyType, valueType</em>></pre> + +<p>The iterator will iterate over values of type <em>valueType</em>, with keys of type <em>keyType</em>. The generated methods will be:</p> + +<ul> + <li><code>entries()</code> that returns an {{jsxref('iterator')}} on the indexes (of type <em>keyType</em>). E.g. {{domxref('FormData.entries()')}}</li> + <li><code>values()</code> that returns an {{jsxref('iterator')}} on the values. E.g. {{domxref('FormData.values()')}}</li> + <li><code>keys()</code> that returns an {{jsxref('iterator')}} on the keys. E.g. {{domxref('FormData.keys()')}}</li> + <li>Once {{bug(1216751)}} lands, <code>forEach()</code>.</li> +</ul> + +<p>Such an iterator allows to use the syntax <code>for (var p in object)</code> as a shorthand of <code>for (var p in object.entries())</code>. We add a sentence about it in the interface description. E.g. {{domxref('FormData')}}.</p> + +<div class="note"> +<p><strong>Note:</strong> the value pairs to iterate over are <em>not</em> defined in the webidl file, but in the prose accompanying it. Such a prose is in the spec and usually starts with: <em>"The <a class="external" href="https://heycam.github.io/webidl/#dfn-value-pairs-to-iterate-over">value pairs to iterate over</a>…"</em><br> + E.g, for {{domxref('FormData')}} you find in the spec: <em>"The <a class="external" href="https://heycam.github.io/webidl/#dfn-value-pairs-to-iterate-over">value pairs to iterate over</a> are the <a href="https://xhr.spec.whatwg.org/#concept-formdata-entry" title="concept-FormData-entry">entries</a> with the key being the <a href="https://xhr.spec.whatwg.org/#concept-formdata-entry-name" title="concept-FormData-entry-name">name</a> and the value the <a href="https://xhr.spec.whatwg.org/#concept-formdata-entry-value" title="concept-FormData-entry-value">value</a>. "</em></p> +</div> + +<h3 id="Set-like_methods">Set-like methods</h3> + +<p>An interface may be defined as <em>set-like</em>, meaning that it represents an <em>ordered set of values</em> will have the following methods: <code>entries()</code>, <code>keys()</code>, <code>values()</code>, <code>forEach(),</code> and <code>has()</code> (it also has the <code>size</code> property). They also supports the use of {{jsxref("Statements/for...of", "for...of")}} on an object implementing this interface. The set-like can be prefixed <code>readonly</code> or not. If not read-only, the methods to modify the set are also implemented: <code>add()</code>, <code>clear()</code>, and <code>delete()</code>.</p> + +<pre class="syntaxbox">setlike<<em>valueType</em>></pre> + +<p>The generated properties will be:</p> + +<ul> + <li><code>entries()</code> that returns an {{jsxref('iterator')}} on the indexes. E.g. {{domxref('FontFaceSet.entries()')}}.</li> + <li><code>values()</code> that returns an {{jsxref('iterator')}} on the values. E.g. {{domxref('FontFaceSet.values()')}}.</li> + <li><code>keys()</code> that returns an {{jsxref('iterator')}} on the keys. E.g. {{domxref('FontFaceSet.keys()')}},</li> + <li><code>forEach()</code>.</li> +</ul> + +<p>In the case, the set-like declaration is not prefixed by read-only, the following methods are also generated:</p> + +<ul> + <li><code>add()</code> that adds an entry. E.g. {{domxref('FontFaceSet.add()')}}.</li> + <li><code>clear()</code> that empty the set-like. E.g. {{domxref('FontFaceSet.clear()')}}.</li> + <li><code>delete()</code> that remove an entry. E.g. {{domxref('FontFaceSet.delete()')}}.</li> +</ul> + +<p>Such an set interface also allows to use the syntax <code>for (var p in object)</code> as a shorthand of <code>for (var p in object.entries())</code>. We add a sentence about it in the interface description. E.g. {{domxref('FontFaceSet')}}.</p> + +<p> </p> + +<h2 id="Constructors">Constructors</h2> + +<p>Constructors are a little bit hidden in WebIDL: they are listed as annotations of the main interface.</p> + +<h3 id="Unnamed_constructors">Unnamed constructors</h3> + +<p>This is the most common case for constructors. The constructor of a given interface A, can be used as <code>a = new A(<em>parameters</em>);</code></p> + +<pre class="syntaxbox" lang="en"><span id="the-code"> [<strong>Constructor</strong>, Func="MessageChannel::Enabled", + Exposed=(Window,Worker)] + interface MessageChannel {…};</span></pre> + +<p><span>A constructor with the same interface is defined using the <code>Constructor</code> annotation on the interface. There can be parenthesis and a list of parameters or not (like in the above example.) We document all the unnamed constructors on a sub-page — for example the above is given the slug <em>Web/API/MessageChannel/MessageChannel</em> and the title <code>MessageChannel()</code>.</span></p> + +<p><span>Another example of an unnamed constructor, with parameters:</span></p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[<strong>Constructor</strong>(DOMString type, optional MessageEventInit eventInitDict), + Exposed=(Window,Worker,System)] + interface MessageEvent : Event {…};</span></pre> + +<p>There can also be several unnamed constructors, differing by their parameter lists. All syntax is documented in one single sub-page.</p> + +<pre class="syntaxbox" lang="en"><span id="the-code">[<strong>Constructor</strong>(DOMString url, URL base), + <strong>Constructor</strong>(DOMString url, optional DOMString base), + Exposed=(Window,Worker)] + interface URL {};</span></pre> + +<h3 id="Named_constructors">Named constructors</h3> + +<pre class="syntaxbox" lang="en"><span id="the-code">[<strong>NamedConstructor</strong>=Image(optional unsigned long width, optional unsigned long height)] + interface HTMLImageElement : HTMLElement {…</span></pre> + +<p><span>A named constructor is a constructor that has a different name than that of its interface. For example<code> new Image(…)</code> creates a new <code>HTMLImageElement</code> object. They are defined in the WebIDL using the <code>NamedConstructor</code> annotation on the interface, followed by the name of the constructor after the equality sign (<code>'='</code>) and the parameter inside the parenthesis, in the same format as you'll see for methods.</span></p> + +<p><span>There can be several named constructors for a specific interface, but this is extremely rare; in such a case we include one sub-page per name.</span></p> + +<h3 id="Availability_in_workers_4"><span>Availability in workers</span></h3> + +<p>Constructors have the same availability as the interface, or partial interface, they are defined on. The sub-page provides this information in the same way as for a method.</p> + +<h3 id="Preferences_4">Preferences</h3> + +<p>Constructors are controlled by the same preference as the interface, or partial interface, they are defined on. The sub-page provides this information in the same way as for a method.</p> diff --git a/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html b/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html new file mode 100644 index 0000000000..15c6f0b2ee --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html @@ -0,0 +1,117 @@ +--- +title: 如何写文章帮助人们了解 Web +slug: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +tags: + - MDN元数据 + - 学习社区 + - 指导 + - 贡献指南 +translation_of: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web +--- +<div>{{MDNSidebar}}</div> + +<p>MDN 的<strong><a href="/zh-CN/docs/Learn">学习区</a></strong>是我们给新手开发者介绍 Web 概念的大本营。因为它的内容主要面对初学者，这是你分享知识，帮助新手逐渐了解 Web 的绝佳地点。确保新手开发者能够跟上这里的内容是很重要的，所以我们格外重视学习区。</p> + +<p><span class="seoSummary">这篇文章解释了如何给<a href="/zh-CN/docs/Learn">学习区</a>写文章。</span></p> + +<h2 id="如何写学习社区的文章">如何写学习社区的文章</h2> + +<p>要开始贡献你的知识，只需点击绿色大按钮，然后按照下面的五个步骤。如果你想找点子，请看一下我们的团队<a href="https://trello.com/b/LDggrYSV"> Trello </a>！</p> + +<div class="align-center"><a class="button ignore-external mega positive" href="/en-US/docs/new?parent=111819">写一篇新的学习文章</a> + +<div></div> +</div> + +<p>这篇文章可能不会在正确的地方出现，但至少是在MDN上。如果你需要找人谈谈把它搬到正确的地方，请<a href="/en-US/docs/Learn#Contact_us">联系我们</a>。</p> + +<h3 id="第一步：写两行">第一步：写两行</h3> + +<p>你文章的第一句话需要总结一下你将要涉及的主题，第二句话应该更详细地介绍你要放在文章中的内容（项目）。例如：</p> + +<div class="summary"> +<p> {{glossary("HTML")}} 文件包含的结构和内容, {{Glossary("CSS")}}以及其他主要的Web技术，使内容看起来像你想要的那样。在本文中，我们将介绍这项技术是如何工作的，以及如何编写你自己的基本示例。</p> +</div> + +<p>注意示例如何简要说明CSS是用于样式化页面的核心Web技术。 这足以使读者很好地了解本文所涵盖的内容。</p> + +<p>因为学习区域的文章主要是针对初学者的，所以每篇文章都应该涵盖一个简单的主题，以免给读者带来太多的新信息。如果你不能在一句话中总结这篇文章，那么你可能在一篇文章中做得太多了!</p> + +<h3 id="第二步：添加一个顶部框">第二步：添加一个顶部框</h3> + +<p>然后添加一个顶框，以帮助读者了解他们在学习过程中的位置。 这是“<a href="/en-US/docs/Learn/Understanding_URLs">了解URL及其结构</a> ”顶部框的示例。 您可以在编写自己的文章时将其用作模型。</p> + +<table class="learn-box standard-table"> + <tbody> + <tr> + <th scope="row">必要条件:</th> + <td>您首先必须清楚Internet的工作方式，Web服务器是什么，与Web链接背后的所有概念。</td> + </tr> + <tr> + <th scope="row">目标:</th> + <td>您将了解什么是URL以及它如何在Web上工作</td> + </tr> + </tbody> +</table> + +<dl> + <dt>必要条件</dt> + <dd>读者首先必须知道什么东西才能读懂你的一篇文章?在有可能的状况下，让每一个前提条件链接到另一篇涵盖概念的学习领域的一篇文章(除了您写的是是一篇完全不需要首先先验知识的无比基础的文章)。</dd> + <dt>目标</dt> + <dd>这一章节粗略说明了您的读者在阅读学习这篇文章的过程中会学到（并学会）什么。这与一行程序有点不同;一行代码总结了文章的主题，而目标部分专门列出了读者在阅读文章过程中所希望完成的全部内容。</dd> +</dl> + +<div class="note"> +<p>注意:要创建此表，您可以复制并粘贴上面的示例表，或者使用MDN的编辑器 <a href="https://wiki.developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Tables">台式工具</a>。如果选择使用table工具，则需要在默认的standard-table类之外特别添加learn-box CSS类。为此，当您创建或编辑表的属性时，请转到“Advanced”面板并将样式表类字段设置为“standard-table learn-box”。</p> +</div> + +<h3 id="第三步写一个完整的描述">第三步:写一个完整的描述</h3> + +<p>接下来，写一个更长的描述，提供更全面的文章概述，突出最重要的概念。不要忘记解释为什么读者要花时间来学习这个主题并阅读你的文章！</p> + +<h3 id="第四步：更深一步">第四步：更深一步</h3> + +<div>当你完成了所有这些，你终于可以深入到主题。你可以根据自己的喜好来组织文章的这一部分(尽管您能够随时咨询我们的 <a href="/en-US/docs/MDN/Contribute/Style_guide">设计指南</a>)。这是你闪耀的机会!详细解释你要写的主题。提供指向完整参考文档的链接，详细解释该技术的工作原理，提供语法和用法细节，等等。由你决定 + +<div></div> +</div> + +<ul> + <li>专注于一个主题。如果你觉得你需要涵盖其他主题，这意味着要么你错过了一篇必备文章，要么你需要把你的文章分解成多个主题</li> + <li>使用简单的英语。尽可能避免使用技术术语，或者至少定义它们并在适用的情况下链接到它们的<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_a_new_entry_in_the_Glossary#How_to_use_the_.7B.7BGlossary.7D.7D_macro">术语表条目。</a></li> + <li>包括直接的例子，使理论概念更容易掌握。许多人以身作则学得最好。与写学术论文相比，我们希望初学者能容易地跟上文章的节奏</li> + <li>视觉辅助工具通常可以使内容更容易消化，并携带额外的信息，所以请随意使用图像、图表、视频和表格。如果您正在使用包含文本的图表，我们建议您使用{{Glossary("SVG")}}，这样我们的翻译团队就可以本地化文本。</li> +</ul> + +<p>看一看我们的函数的前几节<a href="/en-US/docs/Learn/JavaScript/Building_blocks/Functions">可重用代码块文章</a> ，有一些很好的描述部分。</p> + +<h3 id="第五步提供“主动学习”材料">第五步:提供“主动学习”材料</h3> + +<p>为了阐明本文并帮助读者更好地理解他们正在学习的内容，请确保提供练习、教程和需要完成的任务。通过让他们积极地、实际地使用和试验你文章中解释的概念，你可以帮助他们将信息“锁定”在大脑中。</p> + +<p>您可以选择在页面中直接包含这些示例作为 <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实时实例</a>,或者<a href="/en-US/docs/MDN/Contribute/Editor/Links">直接链接到它们。</a> （如果它们不能作为实时实例。） 如果你有兴趣帮助创造这些有价值的东西 ，请参阅<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web">《创建一个交互式的练习来帮助学习网络》</a></p> + +<p>如果您不能提供到现有活动学习材料的链接(您不知道或者没有时间创建它们)，那么您应该在文章中添加标记{{tag ("NeedsActiveLearning")}}。这样，其他贡献者就可以找到需要积极学习材料的文章，并可能帮助你找到它们。</p> + +<p dir="rtl">看看<a href="/en-US/docs/Learn/CSS/Introduction_to_CSS/Simple_selectors#Active_learning_Selecting_different_elements">《主动学习:选择不同的元素》</a>进行现场互动学习练习或者<a href="/en-US/docs/Learn/JavaScript/Building_blocks/Functions#Active_learning_Playing_with_scope">《主动学习: 玩转范围》</a>或者另一种不同风格的练习，要求它们在本地下载模板并按照提供的步骤更改</p> + +<p dir="rtl"></p> + +<p dir="rtl"> </p> + +<h3 id="第六步：查看文章，并放入学习区域导航菜单">第六步：查看文章，并放入学习区域导航菜单</h3> + +<p>在你写完你的文章后，让我们知道，这样我们可以看一看，做一个回顾，并提出改进建议 。再次看看我们的 <a href="/en-US/docs/Learn#Contact_us">联系方式</a> 板块以寻找最好的联系方式。</p> + +<p>完成文章的另一部分是把它放在学习区主导航菜单中。这个菜单是 <a href="/en-US/docs/Template:LearnSidebar">LearnSidebar 宏</a>生成的。 你需要特殊的权限来编辑，所以，再一次，让我们团队中的一个人把它添加进去。</p> + +<p>您至少应该将其添加到您的页面中，这是通过在页面顶部的段落中添加宏调用\{{LearnSidebar}}来完成的。</p> + +<ul> +</ul> + +<h2 id="推荐文章">推荐文章</h2> + +<p>您想做出贡献，但是您不知道该写什么?</p> + +<p>学习社区维护了一个要写文章的<a href="https://trello.com/b/LDggrYSV">Trello看板</a>。随意挑选一个，然后开始去写吧！</p> diff --git a/files/zh-cn/mdn/contribute/howto/write_for_seo/index.html b/files/zh-cn/mdn/contribute/howto/write_for_seo/index.html new file mode 100644 index 0000000000..c8bab8d102 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/write_for_seo/index.html @@ -0,0 +1,77 @@ +--- +title: 如何带着SEO的思维将MDN的Web文档写的更符合搜索引擎展现 +slug: MDN/Contribute/Howto/Write_for_SEO +tags: + - MDN内容贡献 + - MDN搜索优化 + - MDN搜索引擎优化 + - MDN文档 + - MDN的SEO优化 + - SEO + - 搜索引擎优化 +translation_of: MDN/Contribute/Howto/Write_for_SEO +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/zh-CN/docs/MDN")}}{{draft("为了更好的将MDN的文档符合SEO要求，我们在此提供了一些提升MDN搜索引擎优化的技术建议。本文是由MDN的志愿者们整理翻译完成的。 ")}}</div> + +<p><span class="seoSummary">本指南涵盖了我们对内容的基础要求、推荐和实践参考，以确保搜索引擎可以更好的对我们的内容进行分类和索引，同时确保用户可以轻松地获取到所需的内容。</span></p> + +<h2 id="简介">简介</h2> + +<p>MDN写作的首要目标是向开发者们阐明和指导开放的Web技术，以便他们能够快速找到他们想要的东西，或者为了优化自己的代码而寻找需要的细节，因此我们在MDN提供的内容可以被更容易的搜索到就非常重要了。</p> + +<p>由于绝大部分读者是通过搜索引擎搜索找到MDN的内容的，那么作为作者，我们就要始终记得内容对搜索引擎的友好程度这件事。为了对搜索引擎友好，我们撰写了SEO指引的内容以帮助MDN的作者和编辑们能够确保MDN上的每篇内容的设计、撰写和标记方式都符合SEO规范，以获得搜索引擎更好的收录索引和展现。</p> + +<h2 id="本文档的状态">本文档的状态</h2> + +<p>目前我们刚开始了改进MDN文档在搜索引擎优化({{Glossary("SEO")}}) 的长期项目的初期阶段。 我们最近完成了一系列小规模实验来测试能提升SEO的方法，并确定哪些内容能够作为SEO指南提供给我们的贡献者们。</p> + +<p>我们仍在编辑并更新本文，同时将其他贡献者提供的参考纳入到我们的发现中。</p> + +<h2 id="SEO_要点">SEO 要点</h2> + +<p>The following is a list of things you should check while writing and reviewing content to help ensure that the page and its neighbors will be indexed properly by search engines.</p> + +<ul> + <li>Make sure the page's contents are <a href="/en-US/docs/MDN/Contribute/Howto/Write_for_SEO#Ensure_pages_aren't_too_similar">different enough from other pages</a> that search engines don't assume they're about the same thing.</li> +</ul> + +<h2 id="避免过于相似的内容页面">避免过于相似的内容页面</h2> + +<p>Each article should be as unique as possible. Articles that look similar to one another textually will wind up being considered to be about roughly the same thing, even if they aren't. For example, if an interface has the properties <code>width</code> and <code>height</code>, it's easy for the text to be surprisingly similar, with just a few words swapped out, and using the same example. This makes it hard for search engines to know which is which, and they wind up sharing page rank, resulting in both being harder to find than they ought to be.</p> + +<p>Understandably, writers confronted with two related properties like <code>width</code> and <code>height</code> (or any other set of functionally related features) are tempted to write the article on <code>width</code>, then copy that article and paste it into the one on <code>height</code>, replacing a few words. Done!</p> + +<p>Unfortunately, the result is two pages that, as far as search engines are concerned, may as well be the same thing.</p> + +<p>It's important, then, to ensure that every page has its own content. Here are some suggestions to help you accomplish that:</p> + +<ul> + <li>Consider use cases where there might be more differences than one would think. For instance, in the case of <code>width</code> and <code>height</code>, perhaps consider ways horizontal space and vertical space are used differently, and provide a discussion about the appropriate concepts. Perhaps you mention the use of width in terms of making room for a sidebar, while using height to handle vertical scrolling or footers or similar. Including information about accessibility issues is a useful and important idea as well.</li> + <li>Use entirely different examples on each page. Examples in these situations are often even more similar than the body text, since the examples may use both (or all) of the similar methods or properties to begin with, thereby requiring no real changes when reused. So throw out the example and write a new one, or at least provide multiple examples, with at least some of them different.</li> + <li>Include descriptions of each example. Both an overview of what the example does as well as coverage of how it works, in an appropriate level of detail given the complexity of the topic and the target audience, should be included.</li> +</ul> + +<p>The easiest way to avoid being overly similar is of course to write each article from scratch if time allows.</p> + +<h2 id="避免页面内容过短">避免页面内容过短</h2> + +<p>如果文章过短，那么搜索引擎可能会难以甚至无法对其建立关键字索引。一般来说，文章的主体内容应该至少包含 250-300 个单词。但是也不要对内容确实很少的文章进行刻意的扩充，在可能的情况下尽量遵守该指导原则即可。</p> + +<ul> + <li>Keep an eye on the convenient word counter located in the top-right corner of the editor's toolbar on MDN. This is not an exact representation of the true word count, since the true word count is based on the rendered page, not the page as you see it in the editor. That means macros that add a lot of words will result in a higher word count, while macros that insert nothing but adjust formatting will result in a lower word count.</li> + <li>Obviously, if the article is a stub, or is missing material, add it. We try to avoid outright "stub" pages on MDN, although they do exist, but there are plenty of pages that are missing large portions of their content.</li> + <li>Generally review the page to ensure that it's structured properly for the <a href="/en-US/docs/MDN/Contribute/Structures/Page_types">type of page</a> it is. Be sure every section that it should have is present and has appropriate content.</li> + <li>Make sure every section is complete and up-to-date, with no information missing. Are all parameters listed and explained? Make sure any exceptions are covered (this is a particularly common place where content is missing).</li> + <li>Be sure everything is fully fleshed-out. It's easy to give a quick explanation of something, but make sure that all the nuances are covered. Are there special cases? Known restrictions that the reader might need to know about?</li> + <li>There should be examples covering all parameters or at least the parameters (or properties, or attributes) that users from the beginner through intermediate range are likely to use, as well as any advanced ones that require extra explanation. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details and the handling of errors in examples; readers <em>will</em> copy and paste your example to use in their own projects, and your code <em>will</em> wind up used on production sites! See <a href="/en-US/docs/MDN/Contribute/Structures/Code_examples">Code examples</a> and our <a href="/en-US/docs/MDN/Contribute/Guidelines/Code_samples">Code sample guidelines</a> for more useful information.</li> + <li>If there are particularly common use cases for the feature being described, talk about them! Instead of assuming the reader will figure out that the method being documented can be used to solve a common development problem, actually add a section about that use case with an example and text explaining how the example works.</li> + <li>Include proper {{htmlattrxref("alt", "img")}} text on all images and diagrams; this text counts, as do captions on tables and other figures.</li> + <li>Do <em>not</em> descend into adding repetitive, unhelpful material or blobs of keywords, in an attempt to improve the page's size and search ranking. This does more harm than good, both to content readability and to our search results.</li> +</ul> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/MDN/Contribute">Contributing to MDN</a></li> + <li><a href="/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide">Writing style guide</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/howto/如何添加或更新浏览器兼容性数据/index.html b/files/zh-cn/mdn/contribute/howto/如何添加或更新浏览器兼容性数据/index.html new file mode 100644 index 0000000000..8c0513d654 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/如何添加或更新浏览器兼容性数据/index.html @@ -0,0 +1,30 @@ +--- +title: 如何添加或更新浏览器兼容性数据 +slug: MDN/Contribute/Howto/如何添加或更新浏览器兼容性数据 +translation_of: MDN/Contribute/Howto/Add_or_update_browser_compatibility_data +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">如果你有浏览器在兼容Web特性方面的信息 —— 或者有意愿并有能力做一些这方面的研究和/或实验 —— 你可以帮助更新MDN的<a href="https://github.com/mdn/browser-compat-data/">浏览器兼容性数据库</a>（<abbr title="Browser Compatibility Database">BCD</abbr>）。</span></p> + +<ul> + <li>熟悉使用 Github</li> + <li>熟悉使用 JSON</li> + <li>了解有关、或有能力测试各种不同浏览器与网页标准及特性的兼容性</li> +</ul> + +<dl> + <dt>哪些地方需要做？</dt> + <dd> + <p>在MDN上你有这几种方法可以帮助改进浏览器兼容性方面的信息：</p> + + <ul> + <li>添加尚未收录在BCD仓库内的网页特性数据</li> + <li>依据浏览器新版本的变更内容、现有数据中的更正错误，或者某项技术的特性之最新变更等信息来更新现有数据</li> + <li>提交 pull requests 到 <a class="external external-icon" href="https://github.com/mdn/browser-compat-data/issues" rel="noopener">BCD issues filed on Github</a>.</li> + </ul> + </dd> + <dt>做这个任务你需要知道哪些知识？</dt> + <dt>做这个任务需要哪些步骤？</dt> + <dd>欲了解如何更新在GitHub上的组成BCD仓库的 <a class="glossaryLink" href="https://developer.mozilla.org/en-US/docs/Glossary/JSON" title="JSON: The JavaScript Object Notation (JSON) is a data-interchange format. Although not a strict subset, JSON closely resembles a subset of JavaScript syntax. Though many programming languages support JSON, JSON is especially useful for JavaScript-based apps, including websites and browser extensions.">JSON</a> 文件的详细信息，请参见<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">兼容性表格</a>页面。如要了解我们特别寻求帮助的问题列表，请到 <a class="external external-icon" href="https://github.com/mdn/browser-compat-data/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22" rel="noopener">Github issues with the "Help Wanted" tag</a>.</dd> + <dt> </dt> + <dt> </dt> +</dl> diff --git a/files/zh-cn/mdn/contribute/howto/学习_交互_在线_起步_开始/index.html b/files/zh-cn/mdn/contribute/howto/学习_交互_在线_起步_开始/index.html new file mode 100644 index 0000000000..91b8a8640d --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/学习_交互_在线_起步_开始/index.html @@ -0,0 +1,185 @@ +--- +title: 如何创建一个交互学习环境 +slug: MDN/Contribute/Howto/学习_交互_在线_起步_开始 +tags: + - MDN Meta + - 交互 + - 如何使用 + - 学习 + - 教程 +translation_of: MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web +--- +<div>{{MDNSidebar}}</div><p>动态的内容对于学习 Web 来说是重要的。 她能让学习的人更加积极主动。 这可以是练习，实例，任务，评价等等。总之，任何有助于学习理解的东西都行。</p> + +<p>这儿还没有能够直接创建动态的实例内容。但是一些第三方工具可以帮助你创建（如： <a href="https://jsfiddle.net/" rel="external">JSFiddle</a>，<a href="https://codepen.io/">CodePen</a>，<a href="http://dabblet.com/">Dabblet</a>，等），你可以将其链接放在 MDN 文章中。另外，你可以使用 WebMaker 项目的 <a href="https://thimble.mozilla.org/" rel="external">Thimble</a> 来创造更加高级的内容。</p> + +<p>目前，MDN 虽然没有能够轻易创建动态实例内容的工具。不过，如果你是工程师，可以使用当前 MDN 提供的功能创建自定义的主动学习内容，下面内容将告诉你如何操作。</p> + +<h2 id="MDN_live_samples">MDN live samples</h2> + +<p>MDN 有一个非常炫酷的功能：live samples。她是一种可以将 MDN 页面内任何 HTML, CSS, Javascript 代码等效执行的机制。在使用她以前，你最好通读一下 <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Using the live sample system</a>，这是我们关于她的完整文档。虽然她很容易使用，不过通过阅读文档，你会学到一些奇淫巧技。</p> + +<p>有意思的是，将任何类型的工具或实例嵌入到 MDN 页面中都可以通过调教她轻松做到。</p> + +<h3 id="隐藏代码">隐藏代码</h3> + +<p>通过实例创建主动学习内容的第一种方法是编辑要添加内容的页面。使用 Live Sample 功能创建内容，只构建你需要的功能，不要在乎代码的复杂度。当内容准备好之后，只需切换到编辑器视图，并用 class 为 <code>hidden </code>的 {{HTMLElement('div')}} 来包围你的代码。这样代码就会隐藏，不过实例依然可以访问和显示。</p> + +<p>看看这个简单的代码：</p> + +<div class="moreinfo"> +<p>点击这个方块提供随机色，或者直接输入色值</p> + +<div class="hidden"> +<h4 id="hidden_code_example">hidden code example</h4> + +<h5 id="HTML">HTML</h5> + +<pre class="brush: html"><div class="square"> + #<input class="color"> +</div></pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css">body { + padding: 10px; + margin : 0; +} + +.square { + width : 80px; + height : 80px; + padding: 10px; + background-color: black; + color: white; + text-align: center; +} + +.color { + width: 60px; + text-transform: uppercase; +} +</pre> + +<h5 id="JS">JS</h5> + +<pre class="brush: js">function setColor(color) { + document.querySelector('.square').style.backgroundColor = '#' + color; + document.querySelector('.color').value = color; +} + +function getRandomColor() { + var color = Math.floor(Math.random() * 16777215); + return color.toString(16); +} + +function getInputColor() { + var value = document.querySelector('.color').value; + var color = Number('0x' + color); + if (color === +color) { + return color.toString(16); + } + return value; +} + +document.addEventListener('click', function () { + setColor(getRandomColor()); +}); + +document.addEventListener('keyup', function () { + setColor(getInputColor()); +}); +</pre> +</div> +{{EmbedLiveSample('hidden_code_example', 120, 120)}}</div> + +<p>如果你使用 MDN 编辑器查看该页面代码，你会看到如下 HTML 代码：</p> + +<pre class="brush: html"><div class="moreinfo"> +<p>Click on the following square to randomly change its color or just type an hexadecimal code color</p> + +<div class="hidden"> +<h4 id="hidden_code_example">hidden code example</h4> + +<h5 id="HTML">HTML</h5> + +<pre class="brush: html"> +&lt;div class="square"&gt; + #&lt;input class="color"&gt; +&lt;/div&gt;</pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css"> +body { + padding: 10px; + margin : 0; +} + +.square { + width : 80px; + height : 80px; + padding: 10px; + background-color: black; + color: white; + text-align: center; +} + +.color { + width: 60px; + text-transform: uppercase; +} +</pre> + +<h5 id="JS">JS</h5> + +<pre class="brush: js"> +function setColor(color) { + document.querySelector('.square').style.backgroundColor = '#' + color; + document.querySelector('.color').value = color; +} + +function getRandomColor() { + var color = Math.floor(Math.random() * 16777215); + return color.toString(16); +} + +function getInputColor() { + var value = document.querySelector('.color').value; + var color = Number('0x' + color); + if (color === +color) { + return color.toString(16); + } + return value; +} + +document.addEventListener('click', function () { + setColor(getRandomColor()); +}); + +document.addEventListener('keyup', function () { + setColor(getInputColor()); +}); +</pre> +</div> + +\{{EmbedLiveSample('hidden_code_example', 120, 120)}} +</div></pre> + +<p>你可以在 <a href="/en-US/docs/Web/API/Canvas_API#JavaScript">the Canvas API page</a> 查看更多高级例子。</p> + +<h3 id="外部代码">外部代码</h3> + +<p>前面的例子在你想嵌入主动学习内容时是可行的。不过，如果你想要处理更加复杂的代码，这个 <code>hidden</code> 的 {{HTMLElement('div')}} 就比较麻烦。</p> + +<p>另外种方案是将内容写入 MDN 页面，然后嵌入另一个页面中。为此，我们可以使用 {{TemplateLink("EmbedDistLiveSample")}} 替代{{TemplateLink("EmbedLiveSample")}} 。</p> + +<p>我们学习配置这个模拟远程代码嵌入的实例：</p> + +<div class="moreinfo"> +<p>点击这个方块提供随机色，或者直接输入色值</p> +{{EmbedLiveSample('The_example', 120, 120, '', 'MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example')}}</div> + +<p>这下如果你继续使用 <a href="/en-US/docs/MDN/Contribute/Editor/Source_mode">MDN 编辑器</a>查看页面源码，将看不到隐藏元素。如果你需要看，则需要前往这个页面<a href="/en-US/docs/MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example">地址</a>。</p> + +<p>你可以在 <a href="/en-US/docs/Web/Guide/HTML/Forms/How_to_build_custom_form_widgets">HTML 表单教程</a>中查看更多高级例子，那里可以使用表单尝试。</p> diff --git a/files/zh-cn/mdn/contribute/howto/成为一名测试版试验员/index.html b/files/zh-cn/mdn/contribute/howto/成为一名测试版试验员/index.html new file mode 100644 index 0000000000..08693b3ff1 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/成为一名测试版试验员/index.html @@ -0,0 +1,53 @@ +--- +title: 如何成为一名测试版试验员 +slug: MDN/Contribute/Howto/成为一名测试版试验员 +tags: + - MDN Meta +translation_of: MDN/Contribute/Howto/Be_a_beta_tester +--- +<div>{{MDNSidebar}}</div> + +<p>随着MDN Kuma平台的开发人员不断地对站点进行更改，我们为那些选择成为测试版测试人员提供对这些新特性的早期访问。与任何“beta”测试一样，在某些情况下，一些功能可能无法正常工作。</p> + +<h2 id="参与beta测试">参与beta测试</h2> + +<ol> + <li>登录MDN，在顶部导航栏点击你的用户名。<br> + <img alt="Shows location of the user's profile link in the top navigation" src="https://mdn.mozillademos.org/files/15099/profile_link.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 59px; width: 383px;"><br> + 随后跳转到你的资料页。</li> + <li>点击<strong>编辑</strong>按钮。<br> + <img alt="Shows location of the button to edit a user's profile (which may vary depending on window dimensions" src="https://mdn.mozillademos.org/files/15093/profile_edit_link.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 144px; width: 387px;"><br> + 随后在编辑模式下打开资料页。</li> + <li>勾选复选框成为 <strong>Beta 测试者</strong>。<br> + <img alt="Shows the location of the Beta Tester checkbox" src="https://mdn.mozillademos.org/files/15095/profile_beta_checkbox.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 139px; width: 305px;"></li> + <li>点击资料页底部的<strong>发布</strong>按钮<br> + <img alt="Shows the location of the Publish button on a user's profile page" src="https://mdn.mozillademos.org/files/15097/profile_publish_button.png" style="box-shadow: 2px 2px 7px 1px #9e9e9e; height: 218px; width: 477px;"></li> +</ol> + +<h2 id="退出Beta测试">退出Beta测试</h2> + +<ol> + <li>登录MDN，在顶部导航栏点击你的用户名。随后会跳转到你的资料页。</li> + <li>点击<strong>编辑</strong>按钮。随后在编辑模式下打开资料页。</li> + <li>取消 <strong>Beta 测试者</strong>的复选框</li> + <li>点击<strong>发布</strong>按钮.</li> +</ol> + +<h2 id="对beta测试给予反馈">对beta测试给予反馈</h2> + +<p>你有两种方式可以对 beta 测试进行反馈:</p> + +<ul> + <li>在MDN讨论组里分享质量反馈. 在 <a href="https://discourse.mozilla-community.org/t/beta-redesign-feedback/16544">Beta feedback thread</a> 发布一个帖子. 或者,</li> + <li>按照下面的步骤提交 bug:</li> +</ul> + +<ol> + <li>如果你还没有账号，创建一个 <a href="https://bugzilla.mozilla.org/createaccount.cgi">Bugzilla</a> 账号.</li> + <li>打开 <a href="https://bugzilla.mozilla.org/form.mdn#h=detail%7Cbug">bug report in Bugzilla for MDN</a>.</li> + <li>在“摘要”字段中包含 “beta” 一词，帮助 MDN开发人员过滤和区分传入的 bug。.</li> + <li>尽你所能填写 bug 报告. 越详细越好.</li> + <li>点击<strong>提交</strong>按钮.</li> +</ol> + +<p> </p> diff --git a/files/zh-cn/mdn/contribute/index.html b/files/zh-cn/mdn/contribute/index.html new file mode 100644 index 0000000000..c28b259fc6 --- /dev/null +++ b/files/zh-cn/mdn/contribute/index.html @@ -0,0 +1,20 @@ +--- +title: 为 MDN 做贡献 +slug: MDN/Contribute +tags: + - Guide + - Landing + - MDN Meta +translation_of: MDN/Contribute +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p>欢迎！你来到了这里，说明你已经迈出了成为 MDN 贡献者的第一步！</p> + +<p><span class="seoSummary">本页面包含如何为 MDN 做贡献的各个方面的内容，包括风格指南、编辑器和工具使用指南，等等。在编辑或创建任何页面前，请先阅读并确认你已了解了 <a href="https://www.mozilla.org/zh-CN/about/legal/terms/mozilla/">Mozilla 条款</a>。 </span></p> + +<p>如果你以前没有为 MDN 做贡献的经验，这个<a href="/zh-CN/docs/MDN/Getting_started">入门指南</a>可以帮你找到一个你所熟悉的或者力所能及的任务。</p> + +<p>{{LandingPageListSubPages()}}</p> + +<p> </p> diff --git a/files/zh-cn/mdn/contribute/localize/index.html b/files/zh-cn/mdn/contribute/localize/index.html new file mode 100644 index 0000000000..d67b35280a --- /dev/null +++ b/files/zh-cn/mdn/contribute/localize/index.html @@ -0,0 +1,68 @@ +--- +title: MDN 本地化 +slug: MDN/Contribute/Localize +tags: + - I10n + - Landing + - Localization + - MDN +translation_of: MDN/Contribute/Localize +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p>MDN 被全世界的人们和 Firefox 项目组内部用作 Web 技术的参考和指南。众多的本地化社区是 Mozilla 项目的一个关键部分，他们对文档的翻译和本地化工作可以帮助世界各地的人们开发开放 Web。如果你想更多地了解本地化相关的内容，或者准备开始一个新的本地化工作，你可以从这里开始。</p> + +<h2 id="MDN_上的本地化类型">MDN 上的本地化类型</h2> + +<p>MDN 上的本地化包含三个方面，它们位于不同的系统并要求不同访问权限。</p> + +<h4 id="MDN_站点的用户界面">MDN 站点的用户界面</h4> + +<p>指的是每个或大多数 MDN 页面中都有的框架、导航和用户控制组件等部分。这些地方使用 Mozilla <a href="https://developer.mozilla.org/zh-CN/docs/Localizing_with_Pontoon">Pontoon</a> 系统自动翻译，<a href="https://pontoon.mozilla.org/projects/mdn/">这里</a>是该项目的主页。如果你所在地区的语言没有包含在 MDN 中，你可以联系 Pontoon 管理员来启用。见<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Localize/Starting_a_localization">创建新的 MDN 本地化</a>。</p> + +<h4 id="MDN_上的内容">MDN 上的内容</h4> + +<p>指 MDN 页面中的主体内容，包含参考、指南和教程等文章。可以使用 <a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Localize/Translating_pages">MDN 内建的翻译接口</a>来翻译这些文章。如果你所在地区的语言没有包含在该接口所支持的语言列表中，可参考<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Localize/Starting_a_localization">创建新的 MDN 本地化</a>来了解如何操作。</p> + +<h4 id="宏字符串">宏字符串</h4> + +<p>这些字符串由<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Structures/Macros">宏模板</a>产生，以创建导航、消息或某些预定义的结构。因为修改模板可能会对已经使用该模板的所有页面产生影响，所以每次修改模板都需要通过<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Tools/Template_editing">提交一个 pull request 并经过评审</a>。</p> + +<p>以下页面提供了 MDN 上本地化的更多信息：</p> + +<p>{{LandingPageListSubpages}}</p> + +<h2 id="MDN_上的本地化社区">MDN 上的本地化社区</h2> + +<p>MDN 上的本地化活动由两个主体共同完成：独立的个人和一起工作的本地化小组，后者可能是一个更大的 Mozilla 本地化社区的一部分。MDN 上的本地化项目则由本地化带头人所领导。</p> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Localize/Localization_projects">本地化项目</a></li> + <li><a href="/zh-CN/docs/MDN/Community/Roles/Localization_driver_role">本地化带头人</a></li> +</ul> + +<h2 id="中文翻译术语表和翻译规范">中文翻译术语表和翻译规范</h2> + +<p>这篇文章列出了翻译中会遇到的一些术语以及翻译时推荐遵守的规范，推荐阅读：</p> + +<p><a href="/zh-CN/docs/Glossary_of_translation">翻译术语表和翻译规范</a></p> + +<h2 id="本地化相关的工具">本地化相关的工具</h2> + +<p>这里介绍几个对你的本地化工作非常有用的工具：</p> + +<dl> + <dt><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localizing_with_Pontoon" title="/en-US/docs/Mozilla/Localization/Localizing_with_Verbatim">Pontoon</a></dt> + <dd>用于多个 Mozilla 项目中的字符串的翻译，包括 MDN 用户界面和 Firefox 用户界面。</dd> + <dt><a href="http://transvision.mozfr.org/" title="http://transvision.mozfr.org/">Transvision</a></dt> + <dd>由 Mozilla 法国社区提供的一个工具。它可以搜索某个英文在 Mozilla 代码中所有出现的地方，并列出针对目标语言的所有翻译。当需要确定某个单词或短语如何翻译更好时很有用。</dd> +</dl> + +<h2 id="参阅">参阅</h2> + +<ul> + <li><a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Localization">Mozilla 中的本地化</a></li> + <li><a href="https://developer.mozilla.org/zh-CN/docs/Glossary_of_translation">翻译术语表和翻译规范</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/localize/localization_projects/index.html b/files/zh-cn/mdn/contribute/localize/localization_projects/index.html new file mode 100644 index 0000000000..96cf43b145 --- /dev/null +++ b/files/zh-cn/mdn/contribute/localize/localization_projects/index.html @@ -0,0 +1,49 @@ +--- +title: 本地化项目 +slug: MDN/Contribute/Localize/Localization_projects +tags: + - MDN元信息 + - 参考 + - 国际化 + - 本地化 + - 社区 +translation_of: MDN/Contribute/Localize/Localization_projects +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">所有在 MDN 上的本地化及翻译工作都是由我们了不起的社区志愿者们完成的。这篇文章列出了 MDN 上“中文(简体)”本地化项目的带头人以及其他贡献者们。</span></p> + +<p>比起普通的贡献者，每个本地化项目的带头人都拥有下面这些特点：他们对 MDN 这个平台比较了解；他们投入 MDN 本地化的时间和精力也比其他贡献者多；他们会有一些其他贡献者没有的编辑权限，比如移动页面，比如修改某些特殊页面的内容；他们会和 MDN 的管理员进行邮件往来。</p> + +<div class="note"> +<p>每个参与“中文(简体)”本地化的贡献者都应该自觉的把自己的名字添加到下面的表格中（会自动同步到本文档的英文页面中去），并在个人详情页完善好自己的个人信息，以便其他人联系。</p> +</div> + +<table class="fullwidth-table"> + <tbody> + <tr> + <th style="width: 100px;">本地化语言</th> + <th style="width: 100px;">本地化带头人</th> + <th>其他贡献者们</th> + <th>备注</th> + </tr> + <tr> + <td> + <p>中文 (简体)</p> + </td> + <td> + <div id="leader">{{userlink("ziyunfei")}}</div> + </td> + <td> + <div>{{userlink("Terry.Qiao")}}, {{userlink("iwo")}}, {{userlink("du.wei")}}, {{userlink("xcffl")}}, {{userlink("c_king")}}, {{userlink("yan")}}, {{userlink("shengyouxiao")}}, {{userlink("sunnylost")}}, {{userlink("Joyce")}}, {{userlink("Chajn")}}, {{userlink("sagitattoo")}}, {{userlink("ma3r")}}, {{userlink("hyspace")}}, {{userlink("TimZhao")}}, {{userlink("drygin")}}, {{userlink("zhangyaochun1987")}}, {{userlink("donghao526")}}, {{userlink("jtyjty99999")}}, {{userlink("Nightingale")}}, {{userlink("bingguo")}}, {{userlink("fishenal")}}, {{userlink("wanglingzhi")}}, {{userlink("Meteormatt")}}, {{userlink("Darrel.Hsu")}}, {{userlink("aztack")}}, {{userlink("smith_zhong")}}, {{userlink("fatbigbright")}}, {{userlink("manjun.han")}}, {{userlink("stoprunning3")}}, {{userlink("Kennyluck")}}, {{userlink("Technommy")}}, {{userlink("Will_Chen")}}, {{userlink("Jimmie_Felidae")}}, {{userlink("alimon")}}, {{userlink("cagen53070830")}}, {{userlink("crazybullet")}}, {{userlink("princetoad@gmail.com")}}, {{userlink("xiaoxiong")}}, {{userlink("zbinlin")}}, {{userlink("liminjun")}}, {{userlink("Jack_No1")}}, {{userlink("endlesswind")}}, {{userlink("evantre")}}, {{userlink("wanglong")}}, {{userlink("wangming")}}, {{userlink("Elvis_7")}}, {{userlink("anjianshi")}}, {{userlink("xuxun")}}, {{userlink("RobberPhex")}}, {{userlink("YangHanlin")}}, {{userlink("chyingp")}}, {{userlink("companycy")}}, {{userlink("robsean")}}, {{userlink("Fiag")}}, {{userlink("hutuxu")}}, {{userlink("jessiecaisme")}}, {{userlink("sleepholic")}}, {{userlink("xuexiaocai")}}, {{userlink("ArthasTree")}}, {{userlink("Wenbin")}}, {{userlink("xupingmao")}}, {{userlink("Dx.Yang")}}, {{userlink("HeyMemo")}}, {{userlink("LieGroup")}}, {{userlink("amibug")}}, {{userlink("gqqnbig")}}, {{userlink("lilyh")}}, {{userlink("sunorry")}}, {{userlink("Kasuganosora")}}, {{userlink("LinusYu")}}, {{userlink("Maple-Jan")}}, {{userlink("ZhangJianxiang")}}, {{userlink("bowen-shi")}}, {{userlink("figure7")}}, {{userlink("qiumaoyuan")}}, {{userlink("sonicview")}}, {{userlink("zekai.zheng")}}, {{userlink("VinceZhao")}}, {{userlink("coolfire")}}, {{userlink("ericchan1336")}}, {{userlink("jingyu9575")}}, {{userlink("jiraiya")}}, {{userlink("fskuok")}}, {{userlink("jpuncle")}}, {{userlink("reygreen1")}}, {{userlink("yanhaijing1234")}}, {{userlink("yfdyh000")}}, {{userlink("DaoG")}}, {{userlink("Josephok")}}, {{userlink("Othella")}}, {{userlink("aihua")}}, {{userlink("guoyunhebrave")}}, {{userlink("hxl")}}, {{userlink("james.li")}}, {{userlink("jedmeng")}}, {{userlink("ndon")}}, {{userlink("yisi")}}, {{userlink("ReyCG")}}, {{userlink("smartkid")}}, {{userlink("OlingCat")}}, {{userlink("Breezewish")}}, {{userlink("iakuf")}}, {{userlink("ccForward")}}, {{userlink("Jone_Casper")}}, {{userlink("jasonworg")}}, {{userlink("NIGHTEAGLE")}}, {{userlink("saintwinkle")}}, {{userlink("psychebb")}}, {{userlink("zorceta")}}, {{userlink("Light1980")}}, {{userlink("Gaohaoyang")}}, {{userlink("Dolphin_Wood")}}, {{userlink("nyx2014")}}, {{userlink("licop")}}, {{userlink(" qianjiahao")}}, {{userlink("charlie")}}, {{userlink("kun.yan")}}, {{userlink("Jacksunwei")}}, {{userlink("FredWe")}}, {{userlink("lukywong")}}, {{userlink("lttxzmj")}}, {{userlink("pantao")}}, {{userlink("Serifx")}}, {{userlink("kangmingxuan")}}, {{userlink("Ende93")}}, {{userlink("MarxJiao")}}, {{userlink("distums")}}, {{userlink("binggg")}}, {{userlink("Jiang-Xuan")}}, {{userlink("ArcherGrey")}}, {{userlink("johncido")}}, {{userlink("runyul")}}, {{userlink("xjr7670")}}, {{userlink("pluwen")}}, {{userlink("Lyra007")}}, {{userlink("zsxeee")}}, {{userlink("codeofjackie")}}, {{userlink("Louis-7")}}, {{userlink("Chor")}}, {{userlink("celdr")}}, {{userlink("Roronoa_Zoro")}}, {{userlink("mynull")}}, {{userlink("Lsnsh")}}, {{userlink("CharCat")}},{{userlink("guow10")}},{{userlink("Tindoc")}},{{userlink("SirnoChan")}},{{userlink("kagurakana")}},{{userlink("plusmultiply0")}},{{userlink("Adrian-Yan")}},{{userlink("Mookiepiece")}},{{userlink("cheiron")}},</div> + + <div>{{userlink("greatofdream")}},{{userlink("lastVigo")}},{{userlink("sdutwsl")}},</div> + </td> + <td> + <div id="notes"> + <p><span style="line-height: 1.5;">如有问题讨论，请加 QQ 群 26079139 咨询带头人。</span></p> + </div> + </td> + </tr> + </tbody> +</table> diff --git a/files/zh-cn/mdn/contribute/localize/rss_feeds/index.html b/files/zh-cn/mdn/contribute/localize/rss_feeds/index.html new file mode 100644 index 0000000000..9b7fb55d18 --- /dev/null +++ b/files/zh-cn/mdn/contribute/localize/rss_feeds/index.html @@ -0,0 +1,217 @@ +--- +title: MDN RSS 订阅源 +slug: MDN/Contribute/Localize/RSS_feeds +translation_of: MDN/Tools/Feeds +--- +<div>{{MDNSidebar}}</div><p>订阅你所感兴趣的本地化项目，第一时间得知文档变化。</p> +<table class="fullwidth-table"> + <thead> + <tr> + <th scope="col">本地化语言</th> + <th scope="col">简称</th> + <th scope="col">本地化名称</th> + <th scope="col">订阅源地址</th> + </tr> + </thead> + <tbody> + <tr> + <th><a href="https://developer.mozilla.org/ar/">Arabian</a></th> + <td>ar</td> + <td>عربي</td> + <td><a href="https://developer.mozilla.org/ar/docs/feeds/atom/all">https://developer.mozilla.org/ar/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/bn-BD/">Bengali (Bangladesh)</a></th> + <td>bn-BD</td> + <td>বাঙ্গালী</td> + <td><a href="https://developer.mozilla.org/bn-BD/docs/feeds/atom/all">https://developer.mozilla.org/bn-BD/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/ca/">Catalan</a></th> + <td>ca</td> + <td>català</td> + <td><a href="https://developer.mozilla.org/ca/docs/feeds/atom/all">https://developer.mozilla.org/ca/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/cs/">Czech</a></th> + <td>cs</td> + <td>Čeština</td> + <td><a href="https://developer.mozilla.org/cs/docs/feeds/atom/all">https://developer.mozilla.org/cs/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/de/">German</a></th> + <td>de</td> + <td>Deutsch</td> + <td><a href="https://developer.mozilla.org/de/docs/feeds/atom/all">https://developer.mozilla.org/de/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/el/">Greek</a></th> + <td>el</td> + <td>Ελληνικά</td> + <td><a href="https://developer.mozilla.org/el/docs/feeds/atom/all">https://developer.mozilla.org/el/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/en-US/">English</a></th> + <td>en-US</td> + <td>English</td> + <td><a href="https://developer.mozilla.org/en-US/docs/feeds/atom/all">https://developer.mozilla.org/en-US/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/es/">Spanish</a></th> + <td>es</td> + <td>Español</td> + <td><a href="https://developer.mozilla.org/es/docs/feeds/atom/all">https://developer.mozilla.org/es/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/fa/">Persian</a></th> + <td>fa</td> + <td>فارسی</td> + <td><a href="https://developer.mozilla.org/fa/docs/feeds/atom/all">https://developer.mozilla.org/fa/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/fi/">Finnish</a></th> + <td>fi</td> + <td>suomi</td> + <td><a href="https://developer.mozilla.org/fi/docs/feeds/atom/all">https://developer.mozilla.org/fi/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/fr/">French</a></th> + <td>fr</td> + <td>Français</td> + <td><a href="https://developer.mozilla.org/fr/docs/feeds/atom/all">https://developer.mozilla.org/fr/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/fy-NL/">Frisian</a></th> + <td>fy-NL</td> + <td>Frysk</td> + <td><a href="https://developer.mozilla.org/fy-NL/docs/feeds/atom/all">https://developer.mozilla.org/fy-NL/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/ga-IE/">Georgian (Ireland)</a></th> + <td>ga-IE</td> + <td>Gaeilge (Éire)</td> + <td><a href="https://developer.mozilla.org/ga-IE/docs/feeds/atom/all">https://developer.mozilla.org/ga-IE/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/he/">Hebrew</a></th> + <td>he</td> + <td>עברית</td> + <td><a href="https://developer.mozilla.org/he/docs/feeds/atom/all">https://developer.mozilla.org/he/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/hr/">Croatian</a></th> + <td>hr</td> + <td>Hrvatski</td> + <td><a href="https://developer.mozilla.org/hr/docs/feeds/atom/all">https://developer.mozilla.org/hr/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/hu/">Hungarian</a></th> + <td>hu</td> + <td>Magyar</td> + <td><a href="https://developer.mozilla.org/hu/docs/feeds/atom/all">https://developer.mozilla.org/hu/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/id/">Indonesian</a></th> + <td>id</td> + <td>Bahasa Indonesia</td> + <td><a href="https://developer.mozilla.org/id/docs/feeds/atom/all">https://developer.mozilla.org/id/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/it/">Italian</a></th> + <td>it</td> + <td>Italiano</td> + <td><a href="https://developer.mozilla.org/it/docs/feeds/atom/all">https://developer.mozilla.org/it/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/ja/">Japanese</a></th> + <td>ja</td> + <td>日本語</td> + <td><a href="https://developer.mozilla.org/ja/docs/feeds/atom/all">https://developer.mozilla.org/ja/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/ka/">Georgian</a></th> + <td>ka</td> + <td>ქართული</td> + <td><a href="https://developer.mozilla.org/ka/docs/feeds/atom/all">https://developer.mozilla.org/ka/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/ko/">Korean</a></th> + <td>ko</td> + <td>한국어</td> + <td><a href="https://developer.mozilla.org/ko/docs/feeds/atom/all">https://developer.mozilla.org/ko/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/nl/">Dutch</a></th> + <td>nl</td> + <td>Nederlands</td> + <td><a href="https://developer.mozilla.org/nl/docs/feeds/atom/all">https://developer.mozilla.org/nl/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/pl/">Polish</a></th> + <td>pl</td> + <td>Polski</td> + <td><a href="https://developer.mozilla.org/pl/docs/feeds/atom/all">https://developer.mozilla.org/pl/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/pt-BR/">Portuguese (Brazil)</a></th> + <td>pt-BR</td> + <td>Português (do Brasil)</td> + <td><a href="https://developer.mozilla.org/pt-BR/docs/feeds/atom/all">https://developer.mozilla.org/pt-BR/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/pt-PT/">Portuguese (Europe)</a></th> + <td>pt-PT</td> + <td>Português (Europeu)</td> + <td><a href="https://developer.mozilla.org/pt-PT/docs/feeds/atom/all">https://developer.mozilla.org/pt-PT/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/ro/">Romanian</a></th> + <td>ro</td> + <td>română</td> + <td><a href="https://developer.mozilla.org/ro/docs/feeds/atom/all">https://developer.mozilla.org/ro/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/ru/">Russian</a></th> + <td>ru</td> + <td>Русский</td> + <td><a href="https://developer.mozilla.org/ru/docs/feeds/atom/all">https://developer.mozilla.org/ru/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/sq/">Albanian</a></th> + <td>sq</td> + <td>Shqip</td> + <td><a href="https://developer.mozilla.org/sq/docs/feeds/atom/all">https://developer.mozilla.org/sq/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/th/">Thai</a></th> + <td>th</td> + <td>ไทย</td> + <td><a href="https://developer.mozilla.org/th/docs/feeds/atom/all">https://developer.mozilla.org/th/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/tr/">Turkish</a></th> + <td>tr</td> + <td>Türkçe</td> + <td><a href="https://developer.mozilla.org/tr/docs/feeds/atom/all">https://developer.mozilla.org/tr/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/vi/">Vietnamese</a></th> + <td>vi</td> + <td>Tiếng Việt</td> + <td><a href="https://developer.mozilla.org/vi/docs/feeds/atom/all">https://developer.mozilla.org/vi/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/zh-CN/">Chinese (Simplified)</a></th> + <td>zh-CN</td> + <td>中文 (简体)</td> + <td><a href="https://developer.mozilla.org/zh-CN/docs/feeds/atom/all">https://developer.mozilla.org/zh-CN/docs/feeds/atom/all</a></td> + </tr> + <tr> + <th><a href="https://developer.mozilla.org/zh-TW/">Chinese (Traditional)</a></th> + <td>zh-TW</td> + <td>中文 (繁體)</td> + <td><a href="https://developer.mozilla.org/zh-TW/docs/feeds/atom/all">https://developer.mozilla.org/zh-TW/docs/feeds/atom/all</a></td> + </tr> + </tbody> +</table> +<p>如果你想要更灵活的自定义所订阅的消息，请查看<a href="/zh-CN/docs/MDN/User_guide/Feeds" title="Feeds | MDN">订阅源</a>一文。</p> diff --git a/files/zh-cn/mdn/contribute/localize/starting_a_localization/index.html b/files/zh-cn/mdn/contribute/localize/starting_a_localization/index.html new file mode 100644 index 0000000000..56f977a6b2 --- /dev/null +++ b/files/zh-cn/mdn/contribute/localize/starting_a_localization/index.html @@ -0,0 +1,65 @@ +--- +title: Starting a new MDN localization +slug: MDN/Contribute/Localize/Starting_a_localization +tags: + - 未翻译 +translation_of: MDN/Contribute/Localize/Starting_a_localization +--- +<div>{{MDNSidebar}}</div> + +<p>If your language doesn't already have a <a href="/en-US/docs/Project:MDN/Localizing/Localization_projects" title="/en-US/docs/Project:MDN/Localizing/Localization_projects">localization project</a> on MDN, and you have the time and the enthusiasm to do so, you should consider starting a new one. This article is a guide to how to go about starting a localization project.</p> + +<h2 id="Getting_started">Getting started</h2> + +<p>If you'd like to start a localization project to translate MDN into your language, here are the steps you need to follow to get up and running.</p> + +<ol> + <li>First, <a href="https://localize.mozilla.org/projects/mdn/" title="https://localize.mozilla.org/projects/mdn/">check to see</a> if there's already a localization for that language.</li> + <li>Contact your locale's <a href="http://wiki.mozilla.org/L10n:Localization_Teams">Mozilla l10n team</a> and let them know that you want to start it.</li> + <li>Sign up to our <a href="/Project:en/Community">Mailing Lists</a> and head to the <a href="irc://irc.mozilla.org/mdn" title="irc://irc.mozilla.org/devmo">#mdn</a> IRC channel on <a class="link-irc" href="irc://irc.mozilla.org">irc.mozilla.org</a>.</li> + <li>Contact the <a href="mailto:mdn-admins@mozilla.org?subject=Starting%20a%20localization%20project" title="mailto:mdn-admins@mozilla.org?subject=Starting%20a%20localization%20project">MDN administration team</a> to let them know you're starting a new localization. You don't need their permission or anything, but we likes to know who you are. Let us know a little bit about you and which locale you're planning to start work on.</li> + <li>Add a row for your language to the list of <a href="/en-US/docs/Project:MDN/Localizing/Localization_projects" title="/en-US/docs/Project:MDN/Localizing/Localization_projects">localization projects</a>, and include anyone else who is planning to work on it.</li> + <li><a href="https://bugzilla.mozilla.org/enter_bug.cgi?alias=&assigned_to=nobody%40mozilla.org&blocked=&bug_file_loc=http%3A%2F%2F&bug_severity=normal&bug_status=NEW&comment=&component=Localization&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&defined_groups=1&dependson=&description=&flag_type-4=X&flag_type-607=X&flag_type-791=X&flag_type-800=X&form_name=enter_bug&keywords=&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=--&product=Mozilla%20Developer%20Network&qa_contact=website%40mdn.bugs&rep_platform=All&requestee_type-4=&requestee_type-607=&requestee_type-791=&requestee_type-800=&short_desc=&status_whiteboard=&target_milestone=---&version=unspecified" title="https://bugzilla.mozilla.org/enter_bug.cgi?alias=&assigned_to=nobody%40mozilla.org&blocked=&bug_file_loc=http%3A%2F%2F&bug_severity=normal&bug_status=NEW&comment=&component=Localization&contenttypeentry=&contenttypemethod=autodetect&contenttypeselection=text%2Fplain&data=&defined_groups=1&dependson=&description=&flag_type-4=X&flag_type-607=X&flag_type-791=X&flag_type-800=X&form_name=enter_bug&keywords=&maketemplate=Remember%20values%20as%20bookmarkable%20template&op_sys=All&priority=--&product=Mozilla%20Developer%20Network&qa_contact=website%40mdn.bugs&rep_platform=All&requestee_type-4=&requestee_type-607=&requestee_type-791=&requestee_type-800=&short_desc=&status_whiteboard=&target_milestone=---&version=unspecified">Create a bug</a> in <a href="http://bugzilla.mozilla.org">Bugzilla</a> requesting that your language be added to the list of languages supported by MDN. This bug should be in the "Mozilla Developer Network" > "Localization" category. It will be automatically assigned to the correct person. This is needed so that your language shows up in the list of languages to choose from on the site; until this is done, you won't be able to continue.</li> + <li>Wait while the MDN team handles your request. If your bug isn't responded to within three or four days, please add a comment to the bug asking for an "ETA" for completion.</li> + <li>Once the locale has been added to MDN, you can <a href="https://localize.mozilla.org/projects/mdn/" title="https://localize.mozilla.org/projects/mdn/">use the Verbatim tool</a> to translate the user interface strings for the site, and you can begin translating articles on the wiki. While translating the site's strings in Verbatim isn't required, it does add a nice touch to have the user interface presented in your language.</li> +</ol> + +<h2 id="Organizing_a_localization_project">Organizing a localization project</h2> + +<p>There are lots of great tips from various existing translation teams; you should feel free to adopt any of these ideas you choose. In addition, please feel free to add your own suggestions as well. See <a href="/profiles/traducción">this template</a> in the Spanish wiki for an example.</p> + +<ul> + <li>Use a macro to identify articles that are in the process of being translated. The macro should provide an information box that includes a link to the original version of the article. You may also wish to use page tags to indicate pages that need more translation work. This helps track articles that are in the process of being translated.</li> + <li>Use a macro to include articles that need to be translated in article lists with a flag or marker next to them indicating that the article hasn't been translated yet. This is a way to advertise important articles in need of translation. See <a href="/profiles/tradúceme">this template</a> in the Spanish version of MDN for an example.</li> + <li>Make use of the "Needs technical review" and "Needs editorial review" flags, to mark articles that have been translated but should be double-checked for technical and grammatical accuracy.</li> + <li>Use the "junk" tag to mark pages that need to be deleted. Since only admins have access to delete articles, this provides a way to mark that an article is obsolete until the admins get the page deleted.</li> + <li>Be sure to include translations of these MDN "how to" pages, and include additional pages as necessary to explain your localization team's policies and practices.</li> +</ul> + +<p>To find help with your project, be sure to ask around on the dev-mdc mailing list, the <a href="irc://irc.mozilla.org/devmo" title="irc://irc.mozilla.org/devmo">#devmo</a> IRC channel, and other MDN-related discussion areas. See "<a href="/en-US/docs/Project:MDN/Contributing/Join_the_community" title="/en-US/docs/Project:MDN/Contributing/Join_the_community">Join the MDN community</a>" for pointers to community discussion channels that will help you find others interested in joining your localization team.</p> + +<p>You may also be able to find others interested in helping you by attending local Web development events, at your local hacker space, and the like. Be creative!</p> + +<h2 id="Localization_look_and_feel">Localization look and feel</h2> + +<p>The basic structure of each of the localizations of MDN should be essentially the same. In general, you should try to maintain the same hierarchy of pages, so that each page on each language corresponds to a similar page in each locale.</p> + +<p>You are welcome to link to external local pages, write your own articles, and translate everything from the English wiki. If you do decide to write your own articles, it would be helpful if you could provide an English translation for the English wiki so it can then get translated into all of the other localized wikis.</p> + +<p>Adding local resources you should keep a neutral point of view; that is, you shouldn't promote a particular perspective, and should instead simply provide the facts as best as possible (see information about the <a href="http://en.wikipedia.org/wiki/NPOV">NPOV</a> rule on Wikipedia). You should not link to commercial sites (like paid courses, web design companies, etc.). You should promote open standards and cross-browser compatibility over closed or proprietary methods wherever possible.</p> + +<div class="note"> +<p><strong>Note:</strong> Team leads are encouraged to monitor their locale's content for spam and other inappropriate materials and take steps to get them removed or corrected.</p> +</div> + +<h2 id="Policy">Policy</h2> + +<p>All materials created and translated for the MDN should follow our <a href="/en-US/docs/Project:Copyrights">Copyright and Licensing Policies</a>.</p> + +<p>If you encounter problems of any sort—technical, policy, or other—please contact the <a href="mailto:mdn-admins@mozilla.org?subject=Localization%20question" title="mailto:mdn-admins@mozilla.org?subject=Localization%20question">MDN admin team</a>.</p> + +<h2 id="See_also">See also</h2> + +<ul> + <li><a href="/en-US/docs/Project:MDN/Localizing" title="/en-US/docs/Project:MDN/Localizing">Localizing MDN</a></li> +</ul> diff --git a/files/zh-cn/mdn/contribute/localize/translating_pages/index.html b/files/zh-cn/mdn/contribute/localize/translating_pages/index.html new file mode 100644 index 0000000000..4d6a915298 --- /dev/null +++ b/files/zh-cn/mdn/contribute/localize/translating_pages/index.html @@ -0,0 +1,54 @@ +--- +title: 翻译 MDN 上的页面 +slug: MDN/Contribute/Localize/Translating_pages +tags: + - MDN + - 向导 + - 国际化 + - 本地化 + - 页面翻译 +translation_of: MDN/Contribute/Localize/Translating_pages +--- +<div>{{MDNSidebar}}</div> + +<p>本文是翻译 MDN 的基本指南，包括翻译的机制以及处理不同内容的技巧。</p> + +<h2 id="创建页面翻译">创建页面翻译</h2> + +<p>当您浏览到一个 MDN 的页面，并想要翻译成您的语言，请参照以下步骤：</p> + +<ol> + <li>点击页面上的语言图标 ( {{FontAwesomeIcon("icon- language")}}) 打开<strong>语言</strong>菜单，并点击<strong>添加翻译副本</strong>，就会看到选择语言的页面。</li> + <li>点击您想要翻译成的语言。翻译文章的页面会打开，页面左边是文章的原语言。</li> + <li>在<strong>翻译描述</strong>下，您可以翻译标题，或者，也可以将slug翻译成目标语言。slug 是网页 URL 的最后那一部分（例如，这篇文章的“Translating_pages”）。一些语言的社区不翻译 slug，保留使用英语版本的 slug。请您对比其他 MDN 上您的语言的文章来决定一个普遍的做法。当您完成描述的翻译时，您可以点击<strong>翻译描述</strong>后的减号来隐藏它，这样下面翻译内容的部分就有更大的空间。</li> + <li>在<strong>翻译内容</strong>下，翻译页面的主体内容。</li> + <li>为您翻译的页面添加至少一个标签。</li> + <li>当您完成时点击<strong>保存更改。</strong></li> +</ol> + +<div class="note"><strong>注意：</strong> 翻译中的文章用户初始界面为英文版。如果 MDN 的本地化中您的目标语言存在的话，那么在接下来的访问翻译特定文章时，用户界面将以目标语言显示。MDN 用户界面能使用 <a href="https://pontoon.mozilla.org/projects/mdn/" title="https://pontoon.mozilla.org/projects/mdn/">Pontoon</a> 来本地化。如何使用这个工具的细节参阅 <a href="https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localizing_with_Pontoon" title="/en-US/docs/Mozilla/Localization/Localizing_with_Pontoon">使用 Pontoon 进行本地化</a>。</div> + +<h2 id="编辑已有翻译">编辑已有翻译</h2> + +<ul> + <li>在一已翻译的网页上，点击<strong>编辑</strong>按键（有的时候标记为目标语言）。翻译中的文章视图展开。</li> +</ul> + +<p><span id="cke_bm_86C" style="display: none;"> </span>如果英语版本已经被更改而翻译副本还是上次更新状态，翻译中的文章视图在英语版面中显示一个源级别的不同更改。帮助您看到翻译副本中什么需要更新。</p> + +<h2 id="标签翻译">标签翻译</h2> + +<p>确保页面至少有一个标签，即使是翻译的页面。一般而言，和原始文章使用相同的标签是一个好主意。</p> + +<p>一些标签用于搜索筛选，或者作为贡献者之间的约定。这些标签无需翻译。如果需要了解这些标签，请参看<a href="/zh-CN/docs/Project:MDN/Contributing/Tagging_standards">标签标准</a>。 如果标签标准里面没有您想用的标签，您可以新建翻译了的标签来分类内容。</p> + +<h2 id="给本地化新手的小技巧">给本地化新手的小技巧</h2> + +<p>如果您不熟悉 MDN 的本地化，请参考以下建议：</p> + +<ul> + <li>可以先从<a href="/zh-CN/docs/Glossary">术语表</a>中的文章开始翻译，因为它们非常简短。</li> + <li>优先翻译标记为<a href="/en-US/docs/tag/l10n%3Apriority">"本地化:高优先级"</a>的文章。一般来说，教程和概念性文章比参考页面的优先级更高，因为读者在学习新概念时更需要翻译。</li> + <li>请不要翻译双花括号之间的文本，例如<code>\{{some-text("more text")}}</code>，而且标点符号也不要修改。这是一个<a href="/zh-CN/docs/MDN/Contribute/Structures/Macros">Macros</a>（宏），它可能会在页面上创建一个结构，或者做一些其他有用的事情。您可能会看到由宏生成的未翻译文本；在您对 MDN 有更深入的了解之前，不用担心这个问题。（修改这个文本需要<a href="en-US/docs/MDN/Contribute/Tools/Template_editing">特殊权限</a>，因为宏可能非常强大。）如果您好奇，请查看<a href="/zh-CN/docs/MDN/Contribute/Content/Custom_macros">常用的宏</a>，以查看宏所做的事情。</li> + <li>访问<a href="/zh-CN/docs/MDN/Contribute/Localize/Localization_projects">本地化项目</a>页面，了解更多关于您的语言环境本地化的信息。</li> +</ul> diff --git a/files/zh-cn/mdn/contribute/persona_sign-in/index.html b/files/zh-cn/mdn/contribute/persona_sign-in/index.html new file mode 100644 index 0000000000..d10ee0432f --- /dev/null +++ b/files/zh-cn/mdn/contribute/persona_sign-in/index.html @@ -0,0 +1,26 @@ +--- +title: MDN 和 Persona登录 +slug: MDN/Contribute/Persona_sign-in +translation_of: Archive/MDN/Persona_sign-ins +--- +<div>{{MDNSidebar}}</div><div class="warning"> +<p><strong>警告：</strong>我们不再提供使用 Persona 登录到 MDN 的服务。所以请您<a href="/zh-CN/docs/MDN/Contribute/Howto/Link_a_GitHub_account">马上将 GitHub 账户关联到您的 MDN 资料</a>以继续登录 MDN。</p> +</div> + +<p>当前MDN给志愿者提供有两种身份认证方式：Mozilla Persona 和 GitHub。从 2016 年 11 月 1 日开始，我们将会把 Persona 从可选登录方式中移除。因此您必须在您的个人资料中启用 Github 身份认证以避免无法登陆到 MDN 的情况出现，您若有任何问题都可以联系 <a href="https://mzl.la/accounthelp">Account Help</a>。</p> + +<p>我们认识到这很不方便，我们也为此深感抱歉。但不幸的是， 我们不得不这样做。了解更多内容可以参见{{anch("Why is Persona being removed", "Why was Persona removed?")}}</p> + +<h2 id="为什么_Persona_会被移除">为什么 Persona 会被移除?</h2> + +<p>Mozilla 已经关闭了 Persona 项目，而 Persona 将会于2016年11月1日起停止服务。您可以参看在 Mozilla wiki 上的文章以<a href="https://wiki.mozilla.org/Identity/Persona_Shutdown_Guidelines_for_Reliers#FAQs">了解更多Mozilla关停Persona决定的信息</a>。我们现在目前把 GitHub 作为唯一的认证方式。</p> + +<h2 id="Persona_何时会被移除">Persona 何时会被移除?</h2> + +<p>我们将会在2016年11月1日禁用Persona这个身份认证方式，换句话来说，您最后能用Persona登录MDN的日子将会是2016年10月31日。我们将从现在开始，越发频繁、紧急地发布通告，以催促您<a href="/zh-CN/docs/MDN/Contribute/Howto/Link_a_GitHub_account">在您的MDN资料中关联一个GitHub账户</a>。请您尽快完成，以避免丢失您MDN账户上的任何数据。</p> + +<h2 id="MDN_会提供其他身份认证方式吗">MDN 会提供其他身份认证方式吗?</h2> + +<p>我们很乐意这样做，但现在还没有其他认证方式能够符合我们的要求；另外我们当前并没有将开发人员资源与其他供应商进行整合。所以目前您作为志愿者访问 MDN 的唯一方式就是<a href="/zh-CN/docs/MDN/Contribute/Howto/Link_a_GitHub_account">在您的 MDN 资料中关联的一个 GitHub 账户</a>。</p> + +<p>当然请记住，您并不需要为了阅读我们的内容而登录到 MDN。但如果您有一个账户，并希望能在将来任何时候给MDN做贡献，<strong>请您一定要在2016年10月31日前添加一个Github 账户到您的个人资料里，时间越快越好</strong>。</p> diff --git a/files/zh-cn/mdn/editor/basics/index.html b/files/zh-cn/mdn/editor/basics/index.html new file mode 100644 index 0000000000..d6435b8282 --- /dev/null +++ b/files/zh-cn/mdn/editor/basics/index.html @@ -0,0 +1,61 @@ +--- +title: 编辑器 UI 元素 +slug: MDN/Editor/Basics +tags: + - 指南 + - 新手 + - 编辑器 +translation_of: MDN/Editor/Basics +--- +<p><span class="seoSummary">MDN内置 WYSIWYG（所见即所得）编辑器，目的就是让编辑工作变得更加轻松。你可以轻松地在网站各处创建、编辑、修改文章或其他页面。</span> 编辑器界面如下所示，包含八个关键区域。本指南将提供每个区域的介绍，以便您了解如何使用整个编辑环境。</p> + +<div class="note"> +<p>我们不断努力改进MDN，所以有时候本指南或下面的屏幕截图可能会稍微过时。不过，我们会定期更新此文档，以避免其无法使用。</p> +</div> + +<p><img alt="Screenshot of the editor UI (August 2017) with each section labeled" src="https://mdn.mozillademos.org/files/15261/edit-page-with-labels.png" style="border-style: solid; border-width: 2px; height: 723px; width: 808px;"></p> + +<p>上图所示的编辑器各个UI区域已罗列在下表中，点击下面的链接来了解每个部分。</p> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Editor/Basics/Page_info">页面信息（上图中的 Page info ）</a></li> + <li><a href="/zh-CN/docs/MDN/Contribute/Editor/Basics/Page_controls">页面控制（Page controls）</a></li> + <li><a href="/zh-CN/docs/MDN/Contribute/Editor/Basics/Toolbar">工具栏（Toolbar）</a></li> + <li><a href="/zh-CN/docs/MDN/Contribute/Editor/Edit_box">编辑框（Edit box）</a></li> + <li><a href="/zh-CN/docs/MDN/Contribute/Editor/Basics/Tags">标签（Tags）</a></li> + <li><a href="#修订意见">修订意见（Revision comment）</a></li> + <li><a href="#复核请求">复核请求（Review requests）</a></li> + <li><a href="/zh-CN/docs/MDN/Contribute/Editor/Basics/Attachments">附件（Attachments）</a></li> +</ul> + +<h2 id="修订注释">修订注释</h2> + +<p>我们强烈建议你每次编辑完成后要附上对修改的注释（修订注释）。这些注释将被保存到页面的修订历史中，就像这个<a href="/zh-CN/dashboards/revisions" title="/zh-CN/dashboards/revisions">修订看板</a>。这将有助于向复核你修改的人提供解释说明。想要添加修订意见也很简单，只要在<strong>发布</strong>之前，在修订意见框中填入注释即可。</p> + +<p>这么做的好处：</p> + +<ul> + <li>如果你进行修改的原因不明显，你的注释可以向别人解释你的想法。</li> + <li>如果你的修改在技术上很复杂，注释可以向编辑者解释它背后的逻辑。甚至可以在注释中包含一个bug追踪号，以便向编辑者提供更多参考信息。</li> + <li>如果你的编辑涉及删除大量的内容，你的注释可以证明删除的合理性（例如，“我把这个内容移到第X条”）。</li> +</ul> + +<h2 id="复核请求">复核请求</h2> + +<p>MDN社区使用<strong>复核</strong>来追踪和提高MDN内容的质量。通过在文章页面上设置特定标志来表示这篇文章需要审查复核。你可以在 <a href="/zh-CN/docs/MDN/Contribute/Howto" title="/zh-CN/docs/Project:MDN/Contributing/How_to_help">MDN 使用指南</a>中了解更多关于<a href="/zh-CN/docs/MDN/Contribute/Howto/Do_a_technical_review" title="/zh-CN/docs/Project:MDN/Contributing/How_to_help#Content_reviews">技术复核</a>和<a href="/zh-CN/docs/MDN/Contribute/Howto/Do_an_editorial_review">文法复核</a>的知识。</p> + +<p>想要申请对你所做的文章进行复核，只需勾选对应复核类型前面的复选框即可。任何对技术方面的修改，都应申请技术复核，当然，如果你申请文法复核，想找个人来检查你的写作和样式，那也是极好的。</p> + +<p>当申请复核后，文章将会被添加到<a href="/zh-CN/docs/needs-review/technical">需要技术复核</a>或<a href="/zh-CN/docs/needs-review/editorial">需要文法复核</a>列表，但这并不能保证会立马有人来复核你的文章。对于技术复核，最好直接联系相关技术领域的<a href="/zh-CN/docs/MDN/Community/Roles/Subject-matter_experts">学科专家</a>。对于编辑评论，您可以在 <a href="https://discourse.mozilla.org/c/mdn">MDN 论坛</a>中发帖以请求其他人来复核你的更改。</p> + +<p> </p> + +<p>在勾选申请复核之后，请务必点击一下<strong>发布</strong>按钮，这样才能提交复核请求。</p> + +<h2 id="参阅">参阅</h2> + +<ul> + <li><a href="https://docs.ckeditor.com/">CKEditor User's Guide</a></li> +</ul> + +<h6 id="EditorGuideQuicklinks">{{EditorGuideQuicklinks}}<span id="cke_bm_73C" style="display: none;"> </span></h6> diff --git a/files/zh-cn/mdn/editor/basics/page_controls/index.html b/files/zh-cn/mdn/editor/basics/page_controls/index.html new file mode 100644 index 0000000000..48175fd7c8 --- /dev/null +++ b/files/zh-cn/mdn/editor/basics/page_controls/index.html @@ -0,0 +1,37 @@ +--- +title: MDN 编辑器页面控件 +slug: MDN/Editor/Basics/Page_controls +tags: + - 指南 + - 编辑器 +translation_of: MDN/Editor/Basics/Page_controls +--- +<div>{{MDNSidebar}}</div> + +<p>页面控件由对整个页面起作用的按钮组成，为了减少多余的滚动，页面控件在编辑器的顶部和底部都可见。一共有四个页面控制按钮：</p> + +<div class="note"> +<p>如果你编写的页面符合 MDN 的要求，而编辑器却不能保存成功，你可以<a href="mailto:mdn-spam-watch@mozilla.com?subject=MDN%3A%20Content%20Rejection%20Appeal&body=%3CDescribe%20the%20content%20you%20were%20trying%20to%20save%20and%20where%20you%20were%20trying%20to%20place%20it.%3E">电子邮件联系开发团队</a>寻求帮助。</p> +</div> + +<dl> + <dt>发布并继续编辑</dt> + <dd>点击这个按钮，会在不关闭编辑器的前提下保存并发布页面。这样你就可以定期保存编辑工作，在页面修订历史中创建存档，这些存档说不定以后会用到。在创建新页面时这个按钮是不可用。查看<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Editor/Basics#修订注释">修订注释框</a>以了解如何在保存文章时添加修订注释。</dd> + <dt>发布</dt> + <dd>点击该按钮，将保存并发布你的文章，同时关闭编辑器，浏览器跳转到标准模式下的页面。查看<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Editor/Basics#修订注释">修订注释框</a>以了解如何在保存文章时添加修订注释。</dd> + <dt>预览</dt> + <dd>点击这个按钮将打开新的页面或窗口，以发布的样式展示编辑器中的内容，其中的<a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Content/Macros">宏指令</a>和<a href="https://developer.mozilla.org/en-US/docs/MDN/Kuma/Introduction_to_KumaScript#Template_Syntax">模板</a>都如实展示。值得注意的是，此时你的文章并没有被保存。这个按钮的作用，就是在文章发布前检查实际页面效果的，如果出现脚本错误，请参阅<a href="/en-US/docs/MDN/Contribute/Troubleshooting#Scripting_error_while_previewing_a_page">预览页面时排除脚本错误</a>。</dd> + <dd> + <div class="warning" style="font-size: 14px;"> + <p><strong>警告:</strong> Currently some macros and templates don't execute properly in Preview-mode, leaving the Preview page missing some of its content (such as sidebars), and thus with somewhat distorted page layout; i.e. not totally <abbr title="What You See Is What You Get">WYSIWYG</abbr>. Further, if <a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Editor/Basics#scayt"><abbr title="Spell-Check As You Type">SCAYT</abbr> is enabled</a> (and possibly if the page contains certain valid macros or templates), Preview mode may still give a scripting error.</p> + </div> + </dd> + <dt><br> + <a id="DiscardChanges" name="DiscardChanges">放弃</a></dt> + <dd>这个按钮的功能就是取消编辑，放弃所有未曾保存的更改。页面将会跳转回上个页面。</dd> + <dd> + <div class="warning" style="font-size: 14px;"> + <p><strong>警告:</strong> Occasionally <strong>Discard</strong> can malfunction and start acting more like a partial "discard," undoing many of your changes without exiting the editor. If this happens to you, you should save, exit, and re-enter the editor.</p> + </div> + </dd> +</dl> diff --git a/files/zh-cn/mdn/editor/basics/page_info/index.html b/files/zh-cn/mdn/editor/basics/page_info/index.html new file mode 100644 index 0000000000..54be30c0cf --- /dev/null +++ b/files/zh-cn/mdn/editor/basics/page_info/index.html @@ -0,0 +1,47 @@ +--- +title: 编辑器 UI 的页面信息区域 +slug: MDN/Editor/Basics/Page_info +tags: + - 指南 + - 新手 + - 编辑器 +translation_of: MDN/Editor/Basics/Page_info +--- +<div>{{MDNSidebar}}</div> + +<p>页面信息区域包含了本页面的信息，但也可以扩展开来以提供额外的页面控件。</p> + +<h2 id="现有页面">现有页面</h2> + +<p>默认情况下，编辑现有页面时，页面信息区域会显示页面标题。</p> + +<p>你可以点击<strong>编辑标题和属性</strong>按钮来打开更多页面控件。如下图：</p> + +<p><img alt="Page info fields for an existing article" src="https://mdn.mozillademos.org/files/15263/Expanded-page-info.png" style="border-style: solid; border-width: 2px; height: 190px; width: 751px;"></p> + +<p>这里可以对下列内容进行设置：</p> + +<dl> + <dt>标题</dt> + <dd>标题会显示在浏览器的标题栏（或标签栏）、面包屑导航栏中，以及文章的顶部。但它不会出现在页面的URL中。</dd> + <dt>目录</dt> + <dd>指定文章中次级标题的级别深度，次级标题会自动生成目录展示在页面上。默认情况下，这里填的是从 <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h2" title="Heading elements implement six levels of document headings, <h1> is the most important and <h6> is the least. A heading element briefly describes the topic of the section it introduces. Heading information may be used by user agents, for example, to construct a table of contents for a document automatically."><code><h2></code></a> 到 <code><a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/h4" title="Heading elements implement six levels of document headings, <h1> is the most important and <h6> is the least. A heading element briefly describes the topic of the section it introduces. Heading information may be used by user agents, for example, to construct a table of contents for a document automatically."><h4></a></code> ，也就是有三级深度。当然，你也可以根据需要自由选择，比如，“没有目录”（不显示目录，如登陆页），或者“所有级别”。</dd> + <dt>最大渲染时长</dt> + <dd>确定页面自动刷新的频率。在绝大多数情况下，设置为零。</dd> + <dt>查找</dt> + <dd>对于已本地化的页面，这个字段可以帮助重新关联变成“孤儿”的页面（脱离英文原版的页面）。对于英语页面来讲，这个字段用处不大，因为，英语是 MDN 的官方语言。</dd> +</dl> + +<h2 id="新页面">新页面</h2> + +<p>如果你拥有<a href="/MDN/Contribute/Howto/Create_and_edit_pages#Getting_page_creation_permission">创建页面权限</a>，你就可以创建新的页面了。查看<a href="/en-US/docs//MDN/Contribute/Howto/Create_and_edit_pages#Creating_a_new_page">如何创建和编辑页面</a>你可以了解到更多这方面的知识。对于创建新页面，页面信息区域看起来如下图：</p> + +<p><img alt="Page info fields for a new page" src="https://mdn.mozillademos.org/files/15265/New-page-info.png" style="border-style: solid; border-width: 2px; height: 214px; width: 739px;"></p> + +<p>你同样可以设置<strong>标题</strong>和<strong>目录</strong>，还可以设置页面的<strong>别名</strong>，别名用于页面URL地址的最后一个部分。以只读状态显示的<strong>父地址</strong>是页面URL中网站根节点之后的部分。当你在标题输入框中输入文字的时候，别名输入框会自动生成对应的内容，其中会用下划线替代标题中的空格。</p> + +<div class="note"> +<p>值得注意的是，我们推荐使用更短的别名和描述更清晰的标题。举例来说，一个关于编辑器页面控件的页面，应该取一个例如：“MDN 编辑器页面控件”的标题，而它的 URL 应该写成“<code>MDN/Contribute/Editor/Basics/Page_controls</code>”，其中“<code>Page_controls</code>”正是这个页面的别名。</p> +</div> + +<p> </p> diff --git a/files/zh-cn/mdn/editor/edit_box/index.html b/files/zh-cn/mdn/editor/edit_box/index.html new file mode 100644 index 0000000000..de23593df5 --- /dev/null +++ b/files/zh-cn/mdn/editor/edit_box/index.html @@ -0,0 +1,145 @@ +--- +title: MDN 编辑器的编辑框 +slug: MDN/Editor/Edit_box +tags: + - MDN + - 快捷键 + - 编辑器 + - 编辑框 +translation_of: MDN/Editor/Keyboard_shortcuts +--- +<p>编辑框正是你写文章的地方，在编辑框中点击右键会根据你点击的位置打开对应的快捷菜单，比如：在表格中点击右键会弹出与编辑表格相关的菜单，在列表中右击就会弹出与列表相关的菜单。</p> + +<p>默认情况下，编辑器会用自己的右键菜单替代浏览器默认的菜单，如果你一定要打开浏览器的默认菜单（比如，使用火狐的拼写检查功能），你可以按住 <kbd>Shift</kbd> 或 <kbd>Control</kbd> 键（ Mac 的 <kbd>Command</kbd> 键），再点击右键。</p> + +<h2 id="快捷键">快捷键</h2> + +<p>丰富而便捷的键盘快捷键能让你在编辑时，手不离开键盘。此处所列的是 Windows 或 Linux 系统下的快捷键，如果是 Mac，只需将 <kbd>Control</kbd> 替换为 <kbd>Command</kbd> 即可。</p> + +<table class="standard-table"> + <colgroup> + <col style="width: 15em;"> + </colgroup> + <tbody> + <tr> + <th>快捷键</th> + <th>描述</th> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>A</kbd></td> + <td>全选</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>C</kbd></td> + <td>复制</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>V</kbd></td> + <td>粘贴</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>V</kbd></td> + <td>粘贴为纯文本</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>X</kbd></td> + <td>剪切</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Z</kbd></td> + <td>撤销</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Y</kbd></td> + <td>重做</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>K</kbd></td> + <td>打开链接编辑器/添加新链接</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd></td> + <td>移除光标所在位置的链接</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>B</kbd></td> + <td>加粗</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>I</kbd></td> + <td>斜体</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>O</kbd></td> + <td>切换 <code><code></code> 样式</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>O</kbd></td> + <td> + <p>切换源码编辑模式</p> + + <div class="note">使用源码编辑模式时请格外小心，你必须按照既定的格式来编辑。请仔细阅读<a href="/zh-CN/docs/Project:MDN/%E8%B4%A1%E7%8C%AE/Editor_guide/Source_mode">编辑器源码模式指南</a>，该指南详细介绍了如何使用源码模式，以及各项注意事项。</div> + </td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>P</kbd></td> + <td>切换当前区域的 <code><pre></code> 样式</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>U</kbd></td> + <td>下划线</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>S</kbd></td> + <td>保存但不关闭编辑器</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>S</kbd></td> + <td>保存并关闭编辑器</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>0</kbd></td> + <td>移除选中区域的样式（此处是数字“0”，不是字母“O”）</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>2</kbd> 至 <kbd>Ctrl</kbd> + <kbd>6</kbd></td> + <td>切换标题的级别（从 2 到 6 ），一级标题仅可供文章头部的页面标题使用。</td> + </tr> + <tr> + <td><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>L</kbd></td> + <td>在无序列表、有序列表和普通段落格式之间切换。</td> + </tr> + <tr> + <td><kbd>Tab</kbd></td> + <td>在缩进模式下增加缩进级别，否则插入两个空格作为制表符。在表格内部，将光标移动到下一个单元格，或者在没有下一个单元格的情况下插入新行。如果光标当前位于页面标题或某个标题中，则光标跳转到下一段。</td> + </tr> + <tr> + <td><kbd>Shift</kbd> + <kbd>Tab</kbd></td> + <td>在缩进模式下降低缩进水平。在表格内部，跳到前一个单元格，如果前面没有单元格，则插入新行。如果光标当前位于页面标题或某个标题中，则光标跳转到下一段。</td> + </tr> + <tr> + <td><kbd>Shift</kbd> + <kbd>Space</kbd></td> + <td>插入空格(<code>&nbsp;</code>)</td> + </tr> + <tr> + <td><kbd>Shift</kbd> + <kbd>Enter</kbd></td> + <td> + <p>跳出当前区域。例如，如果你当前正在某个 <code><pre></code> 区域，按下 <kbd>Shift</kbd> + <kbd>Enter</kbd> ，你将跳出这个区域，回到文章正文。</p> + + <div class="note style-wrap"> + <p>当前不可用，详见：{{bug('780055')}}。</p> + </div> + </td> + </tr> + </tbody> +</table> + +<h2 id="参阅">参阅</h2> + +<ul> + <li><a href="/zh-CN/docs/MDN/Contribute/Editor/Basics">编辑器 UI 元素</a></li> + <li><a href="/zh-CN/docs/MDN/Contribute">为 MDN 做贡献</a></li> + <li><a href="/zh-CN/docs/MDN/Getting_started">初识 MDN</a></li> +</ul> + +<div>{{MDNSidebar}}</div> diff --git a/files/zh-cn/mdn/editor/index.html b/files/zh-cn/mdn/editor/index.html new file mode 100644 index 0000000000..02f71ade9f --- /dev/null +++ b/files/zh-cn/mdn/editor/index.html @@ -0,0 +1,20 @@ +--- +title: MDN 编辑指南 +slug: MDN/Editor +tags: + - MDN + - 指南 + - 文档 +translation_of: MDN/Editor +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p><span class="seoSummary">MDN Web Docs wiki 文档系统的 WYSIWYG (所见即所得)编辑器让贡献新的内容变得简单。这篇指南将告诉你如何使用它，借此来提高你的生产力。在编辑或新建新的页面之前，请阅读并遵守 <a href="https://www.mozilla.org/zh-CN/about/legal/terms/mozilla/">Mozilla 条款</a>。 </span></p> + +<p><a href="/zh-CN/docs/MDN/Contribute/Content/Style_guide" title="Read the MDN style guide">MDN 样式指南</a> 除了告诉你如何进行格式化和样式化内容本身外，还包括我们推荐的语法和拼写规则。</p> + +<p>{{LandingPageListSubpages}}</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/zh-cn/mdn/editor/source_mode/index.html b/files/zh-cn/mdn/editor/source_mode/index.html new file mode 100644 index 0000000000..660f88267e --- /dev/null +++ b/files/zh-cn/mdn/editor/source_mode/index.html @@ -0,0 +1,121 @@ +--- +title: 源码模式 +slug: MDN/Editor/Source_mode +translation_of: MDN/Editor/Source_mode +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">MDN 编辑器有个重要的按键，用来切换到源码编辑模式。此模式下，你可以看到正在编辑的文章的 HTML。<span class="seoSummary">这个指引使你了解 MDN wiki 源码编辑模式<strong>能</strong>做什么，什么<strong>应该</strong>做，但更为重要的是，什么是<strong>不应该</strong>做的。</span></p> + +<div class="warning"> +<p>在你考虑使用源码模式之前，请注意我们强烈建议你不要使用源码模式。如果您只是为了强行符合我们的样式规范，你不应该去使用源码模式。我们确实有一些需求不启用源码模式无法做到。记得查看{{anch("Warnings and caveats")}}。</p> +</div> + +<h2 id="启用源码模式">启用源码模式</h2> + +<p>启用源码模式很简单。在编辑器工具栏的左上角，点击“<strong>Source</strong>”或“<strong>原始碼</strong>”按钮。</p> + +<p><img alt="Partial screenshot of the editor toolbar, with the Source mode button highlighted" src="https://mdn.mozillademos.org/files/15295/Source%20mode%20button.png" style="height: 98px; width: 267px;"></p> + +<p>对于格式化、图片之类的功能，很可能源码模式没有 WYSIWYG (所见即所得)好用，因为你可能需要滚动很远才能找到编辑器中相关源码的位置。</p> + +<h2 id="警告">警告</h2> + +<p>综上所述，你应该极少会需要用到源码模式。只有一些极个别的事情才必须由修改源码实现。最终，我们会更新编辑器界面，为你展示你的修改。</p> + +<p><a href="/en-US/docs/MDN/Contribute">MDN贡献者指南</a>中未明确描述的所有内容均不应添加到源代码中。这意味着：</p> + +<ul> + <li>不要使用自定义字体和样式。若不是标准的一部分，请勿使用。</li> + <li>不要使用特殊颜色。若不是标准视觉样式，请修改为我们提供的样式。</li> +</ul> + +<h2 id="源码模式下编辑">源码模式下编辑</h2> + +<p>一旦启用源码模式，你将可以编辑 wiki 页面的原始 HTML。虽不受编辑器约束，您应竭尽所能保持您的工作与<a href="/en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide">样式指南</a>一致，并且可以安全可靠的工作。</p> + +<div class="note"> +<p>通常，您应该是在源码模式中做一些短暂的调整，而不是长时间的撰写页面。</p> +</div> + +<p>不幸的是，<kbd>Tab</kbd> 键在源码模式中无法使用，请输入两个空格来代替。</p> + +<p>若您使用 MDN 不允许的 HTML 元素和属性，它们会在你保存时直接被移除。此外，文档还将重新被格式化，以使之符合预期。</p> + +<h2 id="合理使用源码模式">合理使用源码模式</h2> + +<p>在一些个别的情况下，使用源码是唯一能遵循MDN格式规范的方式。这一节涵盖了这些情况，并说明了如何在不破坏其他东西的前提下，正确使用这些功能。</p> + +<h3 id="在示例代码中高亮代码行">在示例代码中高亮代码行</h3> + +<p>在用<a href="/zh-CN/docs/MDN/Contribute/Editor/Basics/Toolbar#Blocks_group">工具栏的块组</a>中的<strong>PRE</strong>或<strong>Syntax Highlighter</strong>建立的示例代码片段块中，你会希望让某几行代码更引人注目一些。唯一实现这种事项的方式是开启源码模式，找到包含此部分代码的{{HTMLElement("pre")}}块，然后编辑<code><pre></code>标签的{{htmlattrxref("class")}}属性，加上一个<code>highlight</code>组件，像下面这种格式：</p> + +<ul> + <li><code>highlight[<em>lineNum1</em>, <em>lineNum2</em>, ..., <em>lineNumN</em>]</code></li> +</ul> + +<p>例如，如果现在的标签为<code><pre class="brush: js"></code>，然后你想往第4行和第7行加个高亮，你可把它改为<code><pre class="brush:js; highlight:[4,7]"></code>。</p> + +<p>我们看个更复杂的示例：</p> + +<table class="fullwidth-table"> + <thead> + <tr> + <th scope="col">高亮前</th> + <th scope="col">高亮后</th> + </tr> + </thead> + <tbody> + <tr> + <td> + <pre class="brush: js notranslate"> +var canvas = document.getElementById("canvas"); +var ctx = canvas.getContext("2d"); + +var path1 = new Path2D(); +path1.rect(10, 10, 100, 100); + +var path2 = new Path2D(path1); +path2.moveTo(220, 60); +path2.arc(170, 60, 50, 0, 2 * Math.PI); + +ctx.stroke(path2); +</pre> + + <p>这里的{{HTMLElement("pre")}}标签为：<code><pre class="brush: js"></code></p> + </td> + <td> + <pre class="brush: js; highlight:[4,7] notranslate"> +var canvas = document.getElementById("canvas"); +var ctx = canvas.getContext("2d"); + +var path1 = new Path2D(); +path1.rect(10, 10, 100, 100); + +var path2 = new Path2D(path1); +path2.moveTo(220, 60); +path2.arc(170, 60, 50, 0, 2 * Math.PI); + +ctx.stroke(path2);</pre> + + <p>然后这里的<code><pre></code>标签已经改为了：<code><pre class="brush: js; highlight:[4,7]"></code></p> + </td> + </tr> + </tbody> +</table> + +<h3 id="没有对应工具栏按钮的样式">没有对应工具栏按钮的样式</h3> + +<p>MDN上我们用的一些样式通过通常的用户界面是无法实现的。好消息是，这些不是很常见。示例如：</p> + +<ul> + <li>要应用“keyboard”样式于其上的话，你需要将{{HTMLElement("kbd")}}元素中的键名的文本括上。我们还没有实现这个功能的用户界面，所以调到源码模式，把键名括在<code><kbd></code>中。 例如，如果源码是： + + <pre class="brush: html notranslate"><p>Press the <kbd>Enter</kbd> key to start the countdown.</p></pre> + + <p>输出结果就是：</p> + + <p>Press the <kbd>Enter</kbd> key to start the countdown.</p> + </li> + <li>用于特定页面的一些很不常用的样式也需要手动加上，这尤其在一组盒子上常见。这就是我们用宏来帮助自动建立诸多入口页面组件的缘故。</li> +</ul> diff --git a/files/zh-cn/mdn/guidelines/content_blocks/index.html b/files/zh-cn/mdn/guidelines/content_blocks/index.html new file mode 100644 index 0000000000..cd98951641 --- /dev/null +++ b/files/zh-cn/mdn/guidelines/content_blocks/index.html @@ -0,0 +1,44 @@ +--- +title: 内容块 +slug: MDN/Guidelines/Content_blocks +translation_of: MDN/Guidelines/CSS_style_guide +--- +<div>{{MDNSidebar}}</div><div class="summary"> + <p>This pages lists reusable content blocks.</p> +</div> +<h2 id="Card-grid">Card-grid</h2> +<p>Allows to have a couple of cards next to each other to call out specific contents or can be used for a call to action. CSS class: <code>.card-grid </code>(L 751 - 824 in CustomCSS).</p> +<ul class="card-grid"> + <li><span>CSS Reference</span> + <p>An <a href="/en-US/docs/Web/CSS/Reference" title="en-US/docs/CSS/CSS_Reference">exhaustive reference</a> for <u>seasoned Web developers</u> describing every property and concept of CSS.</p> + </li> + <li><span>CSS Tutorial</span> + <p>A <a href="/en-US/docs/CSS/Getting_Started" title="en-US/docs/CSS/Getting_Started">step-by-step introduction</a> to help <u>complete beginners</u> get started. It presents all the needed fundamentals.</p> + </li> + <li><span>CSS3 Demos</span> + <p>A <a href="/en-US/demos/tag/tech:css3" title="https://developer.mozilla.org/en-US/demos/tag/tech:css3">collection of demos</a> showing the <u>latest CSS technologies</u> in action: a boost for the creativity.</p> + </li> +</ul> +<h2 id="Two_columns">Two columns</h2> +<p>Two columns seperated with a thick grey border. Often used on landing pages. CSS class: <code>.topicpage-table</code> (L 830 - 837 & 82-93 in CustomCSS).</p> +<div class="row topicpage-table"> + <div class="section"> + Column 1</div> + <div class="section"> + Column 2</div> +</div> +<p> </p> +<h2 id="Equal_column_heights">Equal column heights</h2> +<p>Used on the <a href="/en-US/Firefox_OS">Firefox OS</a> landing page to wrap columns that should all be the same height. CSS class <code>.equalColumnHeights</code> (L 25 - 38 in CustomCSS).</p> +<div class="equalColumnHeights"> + <div class="zone-callout"> + Some text<br> + And a new line<br> + </div> + <div class="zone-callout"> + Some more text<br> + <br> + <br> + here</div> +</div> +<p> </p> diff --git a/files/zh-cn/mdn/guidelines/css_style_guide/index.html b/files/zh-cn/mdn/guidelines/css_style_guide/index.html new file mode 100644 index 0000000000..ee85c19b97 --- /dev/null +++ b/files/zh-cn/mdn/guidelines/css_style_guide/index.html @@ -0,0 +1,841 @@ +--- +title: MDN样式指南 +slug: MDN/Guidelines/CSS_style_guide +translation_of: MDN/Guidelines/CSS_style_guide +--- +<p>MDN有许多内置的全局样式，可以在设置文章样式和布局文章时使用，本文是可用类以及何时使用它们的指南。其中一些样式可以通过MDN编辑器的工具栏访问。在这种情况下，我们将在样式标题下包含短语“编辑工具栏”，以及相关工具栏按钮的图像。</p> + +<p>请注意，这些样式的开发是为了涵盖在设置文章内容样式时出现的最常见情况，并且只要可能，您就应该尝试使用可用的类；与标准内容的外观相差太大不利于一致性和可读性。如果你觉得你的页面绝对需要某种特殊的定制样式，你应该首先在MDN讨论论坛中提出这个主题。</p> + +<div class="blockIndicator note"> +<p><strong>注意：如果要搜索MDN上使用给定类的位置，可以</strong>使用表单的URL执行此操作</p> + +<p><code>https://developer.mozilla.org/en-US/search?locale=en-US&css_classnames=<var>desired-css-class</var></code>. 例如，要查找使用卡片网格布局的页面，请尝试URL<a href="https://wiki.developer.mozilla.org/en-US/search?locale=*&css_classnames=card-grid">https://wiki.developer.mozilla.org/en-US/search?locale=*&css_classnames=card-grid</a>.</p> +</div> + +<div class="blockIndicator warning"> +<p><strong>重要提示</strong>: 本指南不完整。有关如何帮助我们完成此指南的信息，请参阅“更新此指南”。</p> +</div> + +<h2 id="内联样式">内联样式</h2> + +<p>本节列出MDN上样式内容块可用的内联样式。</p> + +<h3 id=".button"><code>.button</code></h3> + +<p>MDN提供任何button样式。通常用于设置链接样式（出于安全原因，HTMLElement（“button”）元素从文章源代码中剥离。）</p> + +<p><a class="button" href="https://github.com/mdn/simple-web-worker/archive/gh-pages.zip">下载源代码</a></p> + +<details> +<h4 id="Example_syntax">Example syntax</h4> + +<pre class="brush: html notranslate"><a href="https://github.com/mdn/simple-web-worker/archive/gh-pages.zip" class="button">Download source code</a></pre> +</details> + +<h3 id=".external-icon_and_.ignore-external"><code style="white-space: nowrap;">.external-icon</code> and <code style="white-space: nowrap;">.ignore-external</code></h3> + +<p>指向MDN外部内容的链接会自动设置格式，以便将类外部图标添加到这些链接中，从而创建一个图标，指示它们离开站点。但是，在某些情况下，此图标是不需要的，并且会干扰其他样式。可以通过将忽略外部类添加到链接中来删除它。</p> + +<div class="blockIndicator note"> +<p><strong>注意:</strong> 大多数时候，我们不想用这些。外部图标将自动添加，以帮助防止用户在不知不觉中离开MDN。唯一通常可以接受的用例是指向特定于MDN的域或子域的链接，例如我们用于示例代码或其他服务的那些域或子域。</p> +</div> + +<p><a href="/">Link to MDN</a><br> + <a href="http://wikipedia.org">Link away from MDN</a><br> + <a class="ignore-external" href="http://wikipedia.org">Link away from MDN with <code style="white-space: nowrap;">ignore-external</code></a></p> + +<details> +<h4 id="Example_syntax_2">Example syntax</h4> + +<pre class="brush: html notranslate"><a href="/">Link to MDN</a> +<a href="http://wikipedia.org">Link away from MDN</a> +<a href="http://wikipedia.org" class="ignore-external">Link away from MDN with <code>ignore-external</code></a></pre> +</details> + +<h3 id=".glossaryLink"><code>.glossaryLink</code></h3> + +<p>这是一个类，用于设置词汇表链接的样式，以使它们在页面上不那么显眼。这个类是使用KumaScript宏添加的，如常用宏中所述，因此不会手动插入。</p> + +<details> +<h4 id="Example_macro_syntax">Example macro syntax</h4> + +<p>\{{Glossary("HTML")}}</p> +</details> + +<h3 id=".hidden"><code>.hidden</code></h3> + +<p>允许您隐藏wiki文章中的内容，但可以在编辑器中查看。通常，这用于向创建实时代码示例的脚本提供HTML、CSS和JavaScript，而只向读者显示相关语言。</p> + +<details> +<h4 id="Example_syntax_3">Example syntax</h4> + +<pre class="brush: html notranslate"><h4 id="Hidden_Code_Sample" name="Hidden_Code_Sample">Hidden code Sample</h4> + +<div class="hidden"> +<h5 id="HTML">HTML</h5> + +<pre class="brush: html;"> +&lt;button id="test"&gt; Click me &lt;/button&gt; + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css;"> +button { + background-color: #a00; + color:#fff; + font-size: 20px; +} +</pre> +</div> + +<h5 id="JavaScript_Content">JavaScript Content</h5> + +<pre class="brush: js;"> +document.getElementById("test").addEventListener("click", works); +function works() { + window.alert("you clicked it!"); +} +</pre> + +<p>\{{EmbedLiveSample("Hidden_Code_Sample")}}</p> +</pre> + +<h4 id="Hidden_Code_Sample" name="Hidden_Code_Sample">Hidden code Sample</h4> + +<div class="hidden"> +<h5 id="HTML">HTML</h5> + +<pre class="brush: html notranslate"><button id="test">Click Me</button> +</pre> + +<h5 id="CSS">CSS</h5> + +<pre class="brush: css notranslate">button{ + background-color: #a00; + color:#fff; + font-size: 20px; +} +</pre> +</div> + +<h5 id="JavaScript">JavaScript</h5> + +<pre class="brush: js notranslate">document.getElementById("test").addEventListener("click", works); +function works(){ + window.alert("you clicked it!"); +} +</pre> + +<p>{{EmbedLiveSample("Hidden_Code_Sample", "100%", 150)}}</p> +</details> + +<h3 id=".seoSummary"><code>.seoSummary</code></h3> + +<p>这是一个对页面内容没有可见影响的类，但是，如果该类应用于元素（通常是span），KumaScript将使用元素的内容创建描述meta标记。它们提供了一个简短的描述，可用于搜索引擎和分享网站，如Facebook和Twitter。这个类可以通过MDN编辑器WYSIWYG样式下拉列表中的“SEO摘要”选项获得。</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11859/seosummary-menu-option.png" style="border: 1px solid black; display: block; height: 58px; margin: 0px auto; width: 235px;"></p> + +<details> +<div class="blockIndicator note"> +<p><strong>Note</strong>: If <code>.seoSummary</code> is not explicitly specified on a page, the first paragraph is automatically set as the SEO summary: there is no need to use this on most pages.</p> +</div> + +<p>The final page display won't show any styling change, but in the editor the text that is set as the SEO summary will be marked with a dotted outline and a "SEO Summary" label", as shown below:</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11861/seosummary-editor-representation.png" style="display: block; margin: 0 auto;"></p> + +<p>The below examples are taken from the <a href="/en-US/docs/Mozilla/Add-ons">Mozilla Add-ons</a> page.</p> + +<h3 id="Example_syntax_4">Example syntax</h3> + +<pre class="brush: html notranslate"><p> + <span class="seoSummary">Add-ons add new functionality to <a href="/en-US/docs/Mozilla/Gecko">Gecko</a>-based applications such as Firefox, SeaMonkey, and Thunderbird.</span> + There are two main types of add-on: <a href="#Extensions">Extensions</a> add new features to the application, while <a href="#Themes">Themes</a> modify the application's user interface. +</p></pre> + +<h4 id="Example_of_the_generated_HTMLElementmeta_elements">Example of the generated {{HTMLElement("meta")}} elements</h4> + +<pre class="brush: html; notranslate"><meta property="og:description" content="Add-ons add new functionality to Gecko -based applications such as Firefox, SeaMonkey, and Thunderbird."> +<meta name="description" content="Add-ons add new functionality to Gecko -based applications such as Firefox, SeaMonkey, and Thunderbird."> +<meta name="twitter:description" content="Add-ons add new functionality to Gecko -based applications such as Firefox, SeaMonkey, and Thunderbird."></pre> + +<h4 id="Example_of_how_Facebook_uses_it">Example of how Facebook uses it</h4> + +<p><img alt="SEOSummary as it is used by Facebook" src="https://mdn.mozillademos.org/files/11857/seosummary.jpg" style="display: block; height: 338px; margin: 0px auto; width: 500px;"></p> +</details> + +<div class="blockIndicator note"> +<p><strong>注意:</strong> 这与“.summary”类不同，后者创建了一个特殊的“关于此页”样式的模糊框。该类不设置搜索引擎使用的SEO摘要或MDN用于生成工具提示和自动生成列出子页面的菜单的宏。</p> +</div> + +<h2 id="块级样式">块级样式</h2> + +<p>本节列出MDN上样式内容块可用的块级样式。</p> + +<h3 id=".callout-box"><code style="white-space: nowrap;">.callout-box</code></h3> + +<p>允许您创建一个右浮动框，用于包含要突出显示的标注或相关信息。这是一个示例内容</p> + +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + +<details> +<h4 id="Example_syntax_5">Example syntax</h4> + +<pre class="brush: html notranslate"><div class="callout-box"> + <p>This is an exciting callout</p> +</div> +<p>Example content to float around</p> +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> +</pre> +</details> + +<h3 id=".card-grid"><code style="white-space: nowrap;">.card-grid</code></h3> + +<p>允许您将多张卡片相邻放置，以调出特定内容或映射出多步行动要求。卡片在可用的水平空间中均匀分布；大约2-3张效果最好。</p> + +<ul class="card-grid"> + <li><span>CSS Reference</span> + + <p>An <a href="/en-US/docs/Web/CSS/Reference" title="en-US/docs/CSS/CSS_Reference">exhaustive reference</a> for <u>seasoned Web developers</u> describing every property and concept of CSS.</p> + </li> + <li><span>CSS Tutorial</span> + <p>A <a href="/en-US/docs/CSS/Getting_Started" title="en-US/docs/CSS/Getting_Started">step-by-step introduction</a> to help <u>complete beginners</u> get started. It presents all the needed fundamentals.</p> + </li> + <li><span>CSS3 Demos</span> + <p>A <a href="/en-US/demos/tag/tech:css3" title="https://developer.mozilla.org/en-US/demos/tag/tech:css3">collection of demos</a> showing the <u>latest CSS technologies</u> in action: a boost for the creativity.</p> + </li> +</ul> + +<details> +<h4 id="Example_syntax_6">Example syntax</h4> + +<pre class="brush: html; notranslate"><ul class="card-grid"> + <li>My card content</li> + <li>My second card content</li> + <li>My third card content</li> +</ul></pre> +</details> + +<h3 id=".column-container"><code style="white-space: nowrap;">.column-container</code></h3> + +<p><span style=""> 表示特定宽度列的容器。通常与其他类一起使用，如下所示。</span></p> + +<p><span class="column-4" style="">My first equal width column.</span></p> + +<div class="column-container"> +<div class="column-4"> +<p>My second equal width column.</p> +</div> + +<div class="column-4"> +<p>My third equal width column.</p> +</div> +</div> + +<details> +<h4 id="Example_syntax_7">Example syntax</h4> + +<pre class="brush: html notranslate"><div class="column-container"> + <div class="column-4"> + <p>My first equal width column.</p> + </div> + <div class="column-4"> + <p>My second equal width column.</p> + </div> + <div class="column-4"> + <p>My third equal width column.</p> + </div> +</div></pre> +</details> + +<h3 id=".column-1_.column-2_.column-3_..._all_the_way_up_to_.column-11"><code style="white-space: nowrap;">.column-1</code>, <code style="white-space: nowrap;">.column-2</code>, <code style="white-space: nowrap;">.column-3</code> ... all the way up to <code style="white-space: nowrap;">.column-11</code></h3> + +<p>指定要由.column container包含的特定宽度的列，即列容器宽度（基于12列网格布局）的一定数量的二分之一。每对列之间都留有一个檐沟。</p> + +<div class="column-container"> +<div class="column-1" style="background-color: yellow;">1/12</div> + +<div class="column-11" style="background-color: lime;">11/12</div> +</div> + +<div class="column-container"> +<div class="column-5" style="background-color: yellow;">5/12</div> + +<div class="column-7" style="background-color: lime;">7/12</div> +</div> + +<div class="column-container"> +<div class="column-6" style="background-color: yellow;">6/12</div> + +<div class="column-4" style="background-color: lime;">4/12</div> + +<div class="column-2" style="background-color: pink;">2/12</div> +</div> + +<details> +<h4 id="Example_syntax_8">Example syntax</h4> + +<pre class="brush: html notranslate"><div class="column-container"> + <div class="column-1" style="background-color: yellow;">1/12</div> + <div class="column-11" style="background-color: lime;">11/12</div> +</div> + +<div class="column-container"> + <div class="column-5" style="background-color: yellow;">5/12</div> + <div class="column-7" style="background-color: lime;">7/12</div> +</div> + +<div class="column-container"> + <div class="column-6" style="background-color: yellow;">6/12</div> + <div class="column-4" style="background-color: lime;">4/12</div> + <div class="column-2" style="background-color: pink;">2/12</div> +</div> +</pre> +</details> + +<h3 id=".column-quarter_.column-third_.column-half"><code style="white-space: nowrap;">.column-quarter</code>, <code style="white-space: nowrap;">.column-third</code>, <code style="white-space: nowrap;">.column-half</code></h3> + +<p>指定要由.column container包含的特定宽度的列，该列是列容器宽度的特定部分。每对列之间都留有一条边沟。</p> + +<div class="column-container"> +<div class="column-half" style="background-color: yellow;">Half</div> + +<div class="column-half" style="background-color: lime;">Half</div> +</div> + +<div class="column-container"> +<div class="column-third" style="background-color: yellow;">Third</div> + +<div class="column-third" style="background-color: lime;">Third</div> + +<div class="column-third" style="background-color: pink;">Third</div> +</div> + +<div class="column-container"> +<div class="column-quarter" style="background-color: yellow;">Quarter</div> + +<div class="column-quarter" style="background-color: lime;">Quarter</div> + +<div class="column-quarter" style="background-color: pink;">Quarter</div> + +<div class="column-quarter" style="background-color: cyan;">Quarter</div> +</div> + +<details> +<p>These classes are equivalents of commonly-used numerical width classes, as follows:</p> + +<ul> + <li><code style="white-space: nowrap;">.column-quarter</code> — equivalent to <code style="white-space: nowrap;">.column-3</code></li> + <li><code style="white-space: nowrap;">.column-third</code> — equivalent to <code style="white-space: nowrap;">.column-4</code></li> + <li><code style="white-space: nowrap;">.column-half</code> — equivalent to <code style="white-space: nowrap;">.column-6</code></li> +</ul> + +<h4 id="Example_syntax_9">Example syntax</h4> + +<pre class="brush: html notranslate"><div class="column-container"> + <div class="column-half" style="background-color: yellow;">Half</div> + <div class="column-half" style="background-color: lime;">Half</div> +</div> + +<div class="column-container"> + <div class="column-third" style="background-color: yellow;">Third</div> + <div class="column-third" style="background-color: lime;">Third</div> + <div class="column-third" style="background-color: pink;">Third</div> +</div> +<div class="column-container"> + <div class="column-quarter" style="background-color: yellow;">Quarter</div> + <div class="column-quarter" style="background-color: lime;">Quarter</div> + <div class="column-quarter" style="background-color: pink;">Quarter</div> + <div class="column-quarter" style="background-color: cyan;">Quarter</div> +</div> +</pre> +</details> + +<h3 id="<details>"><code><details></code></h3> + +<p>可以包装在一个内容块周围以隐藏该内容，而不是显示一个“详细信息”链接，单击该链接可展开/折叠其中包含的内容。您可以在本文中看到它的用法。</p> + +<details> +<h4 id="Example_syntax_10">Example syntax</h4> + +<p>This is an example syntax section for {{HTMLElement("details")}} that was hidden with {{HTMLElement("details")}}. Ooooooh, how meta.</p> + +<pre class="brush: html; notranslate"><details> +<h4>Example syntax</h4> +<p>This is an example syntax section for <code>.detail</code> that was hidden with <code>.detail</code>. Ooooooh, how meta.</p> +</details></pre> +</details> + +<h3 id=".example-bad_and_.example-good"><code style="white-space: nowrap;">.example-bad</code> and <code style="white-space: nowrap;">.example-good</code></h3> + +<p>可以使用.example Good和.example bad类突出显示好的和坏的示例。它们通常用于表示示例代码段的<pre>块，但也可以用于其他块。</p> + +<h5 id="Good_code_example">Good code example</h5> + +<pre class="brush: html example-good notranslate"><label for="test">Form label:</label> +<input type="text" id="test"> +</pre> + +<h5 id="Bad_code_example">Bad code example</h5> + +<pre class="brush: html example-bad notranslate"><input type="text"> +</pre> + +<details> +<p><strong>You should always use headings with these classes, as shown below</strong> — CSS is unable to add localized language to the page identifying whether they're good or bad so this is important for people who rely on screen readers, and people with different cultural backgrounds (green and red are not universally good and bad.)</p> + +<h4 id="Example_syntax_11">Example syntax</h4> + +<pre class="brush: html notranslate"><h5 id="Good_code_example">Good code example</h5> + +<pre class="brush: html example-good"> + &lt;label for="test"&gt;Form label:&lt;/label&gt; + &lt;input type="text" id="test"&gt; +</pre> + +<h5 id="Bad_code_example">Bad code example</h5> + +<pre class="brush: html example-bad"> + &lt;input type="text"&gt; +</pre></pre> +</details> + +<h3 id=".moreinfo"><code>.moreinfo</code></h3> + +<p>这个类最初被设计为提供一个链接列表以供进一步阅读，但它可以用于任何远离当前页面的信息。</p> + +<div class="moreinfo"> +<h4 id="基于JavaScript知识构建的工具">基于JavaScript知识构建的工具</h4> + +<dl> + <dt>JavaScript frameworks</dt> + <dd>Developed by Google <a href="https://angularjs.org/">Angular.js</a> is one of the best known frameworks.</dd> + <dd><a href="http://emberjs.com/">Ember.js</a> is open source and community driven.</dd> + <dt>JavaScript Compilers</dt> + <dd><a href="https://babeljs.io/">Babel</a> lets you write ES2015 and compiles to more backwards compatible code.</dd> +</dl> +</div> + +<details> +<h4 id="Example_syntax_12">Example syntax</h4> + +<pre class="brush: html notranslate"><div class="moreinfo"> + <!-- content goes here --> +</div></pre> +</details> + +<h3 id=".blockIndicator.note"><code>.blockIndicator.note</code></h3> + +<p>将内容的一部分转换为便签框，这通常是一个有用的便签，与当前主题相切，但不直接适合信息流。</p> + +<div class="blockIndicator note"> +<p><strong>注意</strong>: 这就是我们通常在MDN文章中呈现注释的方式。</p> +</div> + +<details> +<p>This is available via the "Note box" option in the MDN editor WYSIWYG styles dropdown.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11677/Screen%20Shot%202015-10-05%20at%2006.56.01.png" style="border: 1px solid black; display: block; margin: 0px auto;"><span style="">Example syntax</span></p> + +<pre class="brush: html; notranslate"><div class="blockIndicator note" role="complementary"> + <p><strong>Note</strong>: This is how we usually present a note in an MDN article.</p> +</div></pre> +</details> + +<h3 id=".pull-aside"><code>.pull-aside</code></h3> + +<p>将内容拉到一边。</p> + +<p>有些内容会偏离主题。</p> + +<p>有些内容不太靠边站。</p> + +<details> +<h4 id="Example_Syntax">Example Syntax</h4> + +<pre class="brush: html notranslate"><div class="pull-right">Some content that goes off to the side.</div> +<p>Some content that does not go off to the side.</p></pre> + +<h4 id="Other_uses">Other uses</h4> + +<div class="pull-aside"> +<div class="moreinfo">Combined with the <code>.moreinfo</code> class.</div> +</div> + +<p>Some content that does not go off to the side.</p> + +<p>Some content that does not go off to the side.</p> + +<pre class="brush: html notranslate"><div class="pull-aside"><div class="moreinfo">Some content that goes off to the side.</div></div> +<p>Some content that does not go off to the side.</p> +<p>Some content that does not go off to the side.</p> +</pre> +</details> + +<h3 id=".summary" name=".summary"><code>.summary</code> {{Obsolete_Inline}}</h3> + +<p>为页面创建摘要框，在视觉上显示为带有额外填充的灰色框-应用于文章的开头段落（但不用于参考文章），以使其在页面上具有额外的重要性。</p> + +<div class="blockIndicator warning"> +<p><strong>重要提示:</strong> 这与anch“.seoSummary”类不同，该类建立文本部分，搜索引擎使用该文本部分在结果列表中汇总页面，MDN使用该文本部分创建页面标题及其摘要的工具提示和菜单。这门课完全是一种视觉效果。如果希望同时使用这两个类，可以为页面建立可见和有效的摘要。</p> +</div> + +<p class="summary">这是本文的开头。下面我们将讨论 puppies, giraffes, 和 dugongs.</p> + +<details> +<p>This is available via the "Article Summary" option in the MDN editor WYSIWYG styles dropdown.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11863/article-summary-menu-option.png" style="display: block; height: 238px; margin: 0px auto; width: 254px;"></p> + +<h4 id="Example_syntax_13">Example syntax</h4> + +<pre class="brush: html notranslate"><p class="summary">This is the start of this article. Below we will talk about puppies, giraffes, and dugongs.</p></pre> +</details> + +<h3 id=".topicpage-table"><code>.topicpage-table</code></h3> + +<p>创建用粗灰色边框分隔的两列。常用于登录页。这通常最适合嵌套（“div”）。注意，这两个子元素必须被赋予.section类。</p> + +<div class="topicpage-table"> +<div class="section">Column 1</div> + +<div class="section">Column 2</div> +</div> + +<details open> +<h4 id="Example_syntax_14">Example syntax</h4> + +<pre class="brush: html notranslate"><div class="topicpage-table"> + <div class="section">Column 1</div> + <div class="section">Column 2</div> +</div></pre> +</details> + +<h3 id=".threecolumns"><code>.threecolumns</code></h3> + +<div class="threecolumns"> +<p>使内容块显示在三个等宽列中。</p> + +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + +<p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div> + +<details> +<p>This is available via the "Three columns" option in the MDN editor WYSIWYG styles dropdown.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11779/twocolumn-threecolumn.png" style="border: 1px solid black; display: block; height: 167px; margin: 0px auto; width: 253px;"></p> + +<div class="blockIndicator note"> +<p><strong>Note</strong>: If you want to apply this to a list, then you should apply it to an outer wrapper {{HTMLElement("div")}} — if not, it gets applied to the {{HTMLElement("ul")}} element, which causes the list bullets to not display in Chrome.</p> +</div> + +<h4 id="Example_syntax_15">Example syntax</h4> + +<pre class="notranslate"><div class="threecolumns"> + <p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + + <p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div></pre> +</details> + +<h3 id=".twocolumns"><code>.twocolumns</code></h3> + +<p>使内容块显示在两个等宽列中。 </p> + +<div class="twocolumns"> +<p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + +<p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div> + +<details> +<p>This is available via the "Two columns" option in the MDN editor WYSIWYG styles dropdown.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11779/twocolumn-threecolumn.png" style="border: 1px solid black; display: block; height: 167px; margin: 0px auto; width: 253px;"></p> + +<div class="blockIndicator note"> +<p><strong>Note</strong>: If you want to apply this to a list, then you should apply it to an outer wrapper {{HTMLElement("div")}} — if not, it gets applied to the {{HTMLElement("ul")}} element, which causes the list bullets to not display in Chrome.</p> +</div> + +<h4 id="Example_syntax_16">Example syntax</h4> + +<pre class="notranslate"><div class="twocolumns"> + <p>Mixtape distillery biodiesel pop-up Austin chambray. Fingerstache YOLO tousled, meditation four loko squid brunch single-origin coffee stumptown ethical asymmetrical polaroid Neutra hashtag beard. Mustache Godard Bushwick, Tumblr salvia +1 fixie cornhole beard wayfarers stumptown aesthetic keffiyeh lomo. Meggings lumbersexual keytar Shoreditch.</p> + + <p>Street art PBR YOLO pug, before they sold out fixie artisan blog bicycle rights beard direct trade chillwave. Fanny pack cornhole whatever, Austin single-origin coffee ethical church-key distillery fashion axe tofu farm-to-table irony tattooed Tumblr. Craft beer Thundercats Austin gentrify, wolf Echo Park asymmetrical hella sartorial.</p> +</div></pre> +</details> + +<h3 id=".blockIndicator.warning"><code>.blockIndicator.warning</code></h3> + +<p>将内容的一部分转换为警告框，警告框通常传达读者需要非常小心的一个重要事实（例如，他们需要做一些事情，或避免一些事情来避免严重问题）</p> + +<div class="blockIndicator warning"> +<p><strong>Warning</strong>: Here be dragons!</p> +</div> + +<details> +<p>This is available via the "Warning box" option in the MDN editor WYSIWYG styles dropdown.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/11779/twocolumn-threecolumn.png" style="border: 1px solid black; display: block; height: 167px; margin: 0px auto; width: 253px;"></p> + +<h4 id="Example_syntax_17">Example syntax</h4> + +<pre class="brush: html notranslate"><div class="blockIndicator warning"> + <p><strong>Warning</strong>:Here be dragons!</p> +</div></pre> +</details> + +<h2 id="表格样式">表格样式</h2> + +<p>MDN为HTML“table”元素提供了特定的样式。这一节包括这些。</p> + +<p>没有添加类：</p> + +<table> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">Variety</th> + <th scope="col">Caffeine</th> + <th scope="col">Steeping Time</th> + <th scope="col">Water Temperature</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Black</th> + <td>High</td> + <td>2-3 minutes</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">Green</th> + <td>Low to Medium</td> + <td>1-2 minutes</td> + <td>75 to 80 °C</td> + </tr> + <tr> + <th colspan="4">Caffeine free</th> + </tr> + <tr> + <th scope="row">Herbal</th> + <td>None</td> + <td>3-6 minutes</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h3 id=".standard-table"><code style="white-space: nowrap;">.standard-table</code></h3> + +<table class="standard-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">Variety</th> + <th scope="col">Caffeine</th> + <th scope="col">Steeping Time</th> + <th scope="col">Water Temperature</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Black</th> + <td>High</td> + <td>2-3 minutes</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">Green</th> + <td>Low to Medium</td> + <td>1-2 minutes</td> + <td>75 to 80 °C</td> + </tr> + <tr> + <th colspan="4">Caffeine free</th> + </tr> + <tr> + <th scope="row">Herbal</th> + <td>None</td> + <td>3-6 minutes</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<details> +<p>A standard table can be created using the <em>Table</em> button in the MDN editor WYSIWYG toolbar. Pressing this brings up the Table Properties dialog box, which contains a number of functions. Generally you'll just want to use it to set the number of rows and columns, which cells are table headers ({{HTMLElement("th")}}), and a visible {{HTMLElement("caption")}} and {{HTMLAttrxRef("summary", "table")}} attribute to provide more information for screenreaders, if desired.</p> + +<p><img alt="A diagram showing the Table button in the MDN edit interface, which has a picture of a table on it, and the dialog box that it brings up, which has options on it to set row number, column number, which cells are headings, and more." src="https://mdn.mozillademos.org/files/11997/table-styles-interface-flat.png" style="display: block; margin: 0 auto;"></p> + +<h4 id="Style_notes">Style notes</h4> + +<ul> + <li>Note the different styling applied to the headers ({{HTMLElement("th")}}), and the fact that they have {{HTMLAttrxRef("scope", "th")}} attributes applied for accessibility purposes.</li> + <li>By default, alternating rows have zebra stripes applied, but these can be removed by adding the <code>.no-stripe</code> class to them.</li> + <li>You can force a table to span the full width of the content area (or other immediate containing box, if it is not the content area) by adding the <code>.fullwidth</code> class to the {{HTMLElement("table")}} element.</li> +</ul> + +<h4 id="Example_syntax_18">Example syntax</h4> + +<pre class="brush: html notranslate"><table class="standard-table" summary="This table details what tea we liked to drink back in the heady month of December 2015"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">Variety</th> + <th scope="col">Caffeine</th> + <th scope="col">Steeping Time</th> + <th scope="col">Water Temperature</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Black</th> + <td>High</td> + <td>2-3 minutes</td> + <td>99&nbsp;°C</td> + </tr> + <tr> + <th scope="row">Green</th> + <td>Low to Medium</td> + <td>1-2 minutes</td> + <td>75 to 80&nbsp;°C</td> + </tr> + <tr> + <th scope="row">Herbal</th> + <td>None</td> + <td>3-6 minutes</td> + <td>99&nbsp;°C</td> + </tr> + </tbody> +</table></pre> +</details> + +<h3 id=".standard-table.nostripe"><code><span style="white-space: nowrap;">.standard-table</span>.nostripe</code></h3> + +<table class="nostripe standard-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">Variety</th> + <th scope="col">Caffeine</th> + <th scope="col">Steeping Time</th> + <th scope="col">Water Temperature</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Black</th> + <td>High</td> + <td>2-3 minutes</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">Green</th> + <td>Low to Medium</td> + <td>1-2 minutes</td> + <td>75 to 80 °C</td> + </tr> + <tr> + <th colspan="4">Caffeine free</th> + </tr> + <tr> + <th scope="row">Herbal</th> + <td>None</td> + <td>3-6 minutes</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h3 id=".standard-table.fullwidth"><code>.<span style="white-space: nowrap;">standard-table</span>.fullwidth</code></h3> + +<table class="fullwidth standard-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">Variety</th> + <th scope="col">Caffeine</th> + <th scope="col">Steeping Time</th> + <th scope="col">Water Temperature</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Black</th> + <td>High</td> + <td>2-3 minutes</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">Green</th> + <td>Low to Medium</td> + <td>1-2 minutes</td> + <td>75 to 80 °C</td> + </tr> + <tr> + <th colspan="4">Caffeine free</th> + </tr> + <tr> + <th scope="row">Herbal</th> + <td>None</td> + <td>3-6 minutes</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h3 id=".fullwidth-table"><code style="white-space: nowrap;">.fullwidth-table</code></h3> + +<table class="fullwidth-table"> + <caption>Favorite teas, December 2015</caption> + <thead> + <tr> + <th scope="row">Variety</th> + <th scope="col">Caffeine</th> + <th scope="col">Steeping Time</th> + <th scope="col">Water Temperature</th> + </tr> + </thead> + <tbody> + <tr> + <th scope="row">Black</th> + <td>High</td> + <td>2-3 minutes</td> + <td>99 °C</td> + </tr> + <tr> + <th scope="row">Green</th> + <td>Low to Medium</td> + <td>1-2 minutes</td> + <td>75 to 80 °C</td> + </tr> + <tr> + <th colspan="4">Caffeine free</th> + </tr> + <tr> + <th scope="row">Herbal</th> + <td>None</td> + <td>3-6 minutes</td> + <td>99 °C</td> + </tr> + </tbody> +</table> + +<h2 id="更新本指南">更新本指南</h2> + +<p><span style="">本指南不完整，正在逐步更新。如果您想帮助更新或添加到本指南中，请随时更新或添加！如果您有问题或想讨论并提出改进本文的想法，或者对我们如何改进MDN Web文档的样式或布局有建议，您可以有以下几种选择：</span></p> + +<p><span style="">如果你想帮助完成它，或者想报告一个丢失或错误的文档样式，请联系Chris Mills（以chrisdavidmills的身份发言，在Mozil </span><a href="https://wiki.mozilla.org/IRC" style="">Mozilla IRC</a><span style=""> as chrismills)</span></p> + +<dl> + <dt><a href="https://discourse.mozilla.org/c/mdn">开始讨论MDN Web文档讨论论坛</a><a href="https://discourse.mozilla.org/c/mdn"> forum</a></dt> + <dd>如果您有什么想法想与MDN Web Docs社区或工作人员讨论，请随时在Mozilla讨论站点的MDN Web Docs论坛上开始一个主题。</dd> + <dt><a href="https://github.com/mdn/sprints/issues/new?template=issue-template.md">在GitHub中提交您的建议</a></dt> + <dd>如果您想在我们的官方问题跟踪系统中记录您的建议，我们鼓励您这样做。先用上面的一个频道讨论是个好主意，但这不是必需的。</dd> + <dt><a href="irc://irc.mozilla.org/mdn">在IRC频道提问</a></dt> + <dd>我们的写作人员和贡献者社区使用 <a href="https://wiki.mozilla.org/IRC">Mozilla's IRC 服务器</a> 进行讨论和分享想法。欢迎您加入我们，提出您的问题或建议！（请注意，IRC的参与度很低，可能会在2020年停办；对话是获得答案的最佳选择。）</dd> +</dl> diff --git a/files/zh-cn/mdn/guidelines/index.html b/files/zh-cn/mdn/guidelines/index.html new file mode 100644 index 0000000000..9edc568068 --- /dev/null +++ b/files/zh-cn/mdn/guidelines/index.html @@ -0,0 +1,16 @@ +--- +title: MDN内容和样式指南 +slug: MDN/Guidelines +tags: + - Documentation + - Landing + - MDN + - NeedsTranslation + - TopicStub +translation_of: MDN/Guidelines +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p><span class="seoSummary">代码示例与其它内容应当被表示为适当的形式，这些指南提供了 MDN 文档应当如何被编写并被格式化的规范，以及我们的代码示例与其它内容应当如何被表示的详情说明。</span>你可以通过遵循这些指南来确保自己编写的内容是清晰易用的。</p> + +<p>{{LandingPageListSubpages}}</p> diff --git a/files/zh-cn/mdn/guidelines/layout/index.html b/files/zh-cn/mdn/guidelines/layout/index.html new file mode 100644 index 0000000000..919994b78d --- /dev/null +++ b/files/zh-cn/mdn/guidelines/layout/index.html @@ -0,0 +1,7 @@ +--- +title: MDN page layout guide +slug: MDN/Guidelines/Layout +translation_of: Archive/Meta_docs/MDN_page_layout_guide +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">这些指南补充了<a href="/en-US/docs/MDN/Contribute/Content/Style_guide">MDN 风格指南</a> 中关于 MDN 上各种页面类型的具体布局。这有助于让贡献者们创建的内容结构与 MDN 上其他页面保持一致。</span></p> +<p>{{LandingPageListSubpages}}</p> diff --git a/files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html b/files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html new file mode 100644 index 0000000000..1f40cc49b8 --- /dev/null +++ b/files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html @@ -0,0 +1,193 @@ +--- +title: MDN收录规则 +slug: MDN/Guidelines/Rules_Of_MDN_Documenting +translation_of: MDN/Guidelines/Does_this_belong_on_MDN +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p><span class="seoSummary">如果你正准备记录什么信息，你可能想知道是否要将这些信息放入MDN。 更进一步地，你可能想在你的源代码中维护文档，并将文档写入</span><a href="https://wiki.mozilla.org/">Mozilla wiki</a>，或者写入某Git仓库的readme文件中。<span class="seoSummary"> 本文的目的是帮助你确认你的内容是否适合MDN。</span></p> + +<p>文档是否应放入MDN主要取决于两点：</p> + +<ul> + <li>文档的主题（它是讲什么内容的？）</li> + <li>文档的类型（它是什么类型的文档？）</li> +</ul> + +<div class="note"> +<p>注意Mozilla的 <a href="https://www.mozilla.org/en-US/about/legal/terms/mozilla/">Websites & Communications Terms of Use</a> 所声明的条例在你使用MDN或对其做贡献时是生效的。检查这个文档，确保你知道在Mozilla的网站上什么是能发表的，什么是不能发表的。</p> +</div> + +<h2 id="哪些话题在MDN的范畴内？">哪些话题在MDN的范畴内？</h2> + +<p>MDN涉及了惊人的各种材料。总的来说，如果它是开放的面向Web的技术，或者是Mozilla的产品，我们就把它收录到MDN。但也有一小部分东西完全不属于MDN。这一节会告诉你如何确认你的文档是否属于MDN。</p> + +<p>这里有一些我们涉及的事物；虽然这不是一个完整的列表，但是可以给你一个大致的印象。</p> + +<h3 id="开放的Web标准与技术">开放的Web标准与技术</h3> + +<p>现在Web标准文档中受关注的是那些可以被Web开发者用于创建网站与App这些大众应用的功能。这指的是那些被众多浏览器所实现，要么是被标准接受，要么是正在向标准化发展的技术。即主要关注前端Web技术。后端的技术常常在别处有它们自己的文档，MDN不会去尝试取代它们。</p> + +<ul> + <li><a href="/en-US/docs/Web/HTML" title="HTML">HTML</a></li> + <li><a href="/en-US/docs/Web/CSS" title="CSS">CSS</a></li> + <li><a href="/en-US/docs/Web/JavaScript" title="en/JavaScript">JavaScript</a></li> + <li><a href="/en-US/docs/Web/SVG" title="SVG">SVG</a></li> + <li><a href="/en-US/docs/Web/API">Web APIs</a></li> + <li><a href="/en-US/docs/Web/API/WebGL_API" title="WebGL">WebGL</a></li> + <li>etc.</li> +</ul> + +<p>同时欢迎关注与Web开发有关的交互技术话题，比如：</p> + +<ul> + <li><a href="/en-US/docs/Web/Accessibility" title="Accessibility">Accessibility</a></li> + <li><a href="/en-US/docs/AJAX">AJAX</a></li> + <li><a href="/en-US/docs/Web/Guide/Graphics">Web graphics</a></li> + <li><a href="/en-US/docs/Apps">Open web apps</a></li> + <li><a href="/en-US/Apps/Tutorials/Games">Web-based games</a></li> +</ul> + +<div class="note"> +<p><strong>注意：</strong> MDN 涉及了非Mozilla但对Web开放的技术；举个例子，我们有关于WebKit格式的CSS属性的文档。</p> +</div> + +<h3 id="Mozilla_产品">Mozilla 产品</h3> + +<p>这个分类的文档包括如何作为开发者使用Mozilla的产品，以及如何向这些开源项目贡献。</p> + +<ul> + <li><a href="/en-US/docs/Mozilla/Firefox_OS">Firefox OS</a> + + <ul> + <li><a href="/en-US/docs/Mozilla/Firefox_OS/Building_and_installing_Firefox_OS">Building and installing Firefox OS</a></li> + <li><a href="en-US/Firefox_OS/Phone_guide">Firefox OS phones</a></li> + <li><a href="en-US/Firefox_OS/Developing_Firefox_OS">Contributing to the Firefox OS project</a></li> + <li><a href="en-US/Firefox_OS/Developing_Gaia">Developing Gaia</a></li> + <li>etc.</li> + </ul> + </li> + <li><a href="en-US/docs/Firefox">Firefox browser</a> + <ul> + <li><a href="/en-US/docs/Tools">Firefox Developer Tools</a></li> + <li><a href="/en-US/docs/Mozilla/Add-ons">Add-ons</a></li> + <li><a href="en-US/docs/Mozilla/Developer_guide/Build_Instructions">Building and configuring Firefox</a></li> + <li>etc.</li> + </ul> + </li> + <li><a href="/en-US/docs/Mozilla/Marketplace">Firefox Marketplace</a></li> + <li><a href="/en-US/docs/Mozilla">The Mozilla platform</a> + <ul> + <li><a href="/en-US/docs/Mozilla/Gecko">Gecko</a></li> + <li><a href="/en-US/docs/Mozilla/Projects/SpiderMonkey">SpiderMonkey</a></li> + <li>etc.</li> + </ul> + </li> +</ul> + +<h2 id="哪些话题不属于MDN？">哪些话题不属于MDN？</h2> + +<p>举一些不适合MDN的话题：</p> + +<ul> + <li>仅适用于某一非Mozilla浏览器的不开放的Web技术。</li> + <li>与Web或Mozilla产品无关的技术。</li> + <li>面向用户的文档；对于Mozilla产品来说，这些文档应属于 <a href="https://support.mozilla.org">Mozilla 技术支持</a> 。</li> +</ul> + +<h2 id="哪些类型在MDN的范畴内？">哪些类型在MDN的范畴内？</h2> + +<p>In general, MDN is for <em>product</em> documentation, not for <em>project</em> or <em>process</em> documentation (except <a href="/en-US/docs/MDN">about MDN itself</a>). So, if the document is about "how to use a thing" or "how a thing works" (where the "thing" is in one of the topic categories mentioned above), then it can go on MDN. But if it about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN. In that case, if the thing is being developed under the umbrella of Mozilla, then the <a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a> may be a good place for it.</p> + +<p>Here are some examples of types of documents that should <em>not</em> be placed on MDN<strong>:</strong></p> + +<ul> + <li>Planning documents</li> + <li>Design documents</li> + <li>Project proposals</li> + <li>Specifications or standards</li> + <li>Promotional material, advertising, or personal information{{ref("*")}}</li> +</ul> + +<h2 id="Advantages_to_documenting_on_MDN">Advantages to documenting on MDN</h2> + +<p>If you've determined that the documentation you want to write is appropriate in content and type for MDN, but you're still not sure whether MDN is the best place for it, read on. There are a lot of good reasons to create documentation on MDN.</p> + +<h3 id="Lots_of_writers_and_translators">Lots of writers and translators</h3> + +<p>The MDN community is big. Really big. It's big in the sort of way that makes big things look small. Seriously, we have a lot of people that participate in creating and maintaining content on MDN. With writers and editors on every continent (okay, I'm not sure about Antarctica, but otherwise), there's a lot of value to the sheer volume of writers:</p> + +<ul> + <li>We have a paid staff of writers whose <strong>mission</strong> is to make sure that our content is as good as possible.</li> + <li>We have a core community of volunteers who contribute substantial amounts of content and can help you.</li> + <li>The MDN team can work with you to ensure that your documentation project is adequately staffed.</li> + <li>The broader MDN community also contributes enormously; from typo fixes to editorial reviews of your content, they can save your bacon.</li> + <li>The {{IRCLink("mdn")}} channel offers a resource where you can talk to our writing community and get their advice, or recruit help with the production of or maintenance of your content.</li> + <li>Because we have contributors all over the world, there's always someone around, watching for problems and fixing them.</li> + <li>Our community of volunteers includes translators for many languages, who can help localize your documentation.</li> +</ul> + +<p>Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.</p> + +<h3 id="维护">维护</h3> + +<p>Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:</p> + +<dl> + <dt>Delete spam</dt> + <dd>Spam happens. We deal with it.</dd> + <dt>Copy editing</dt> + <dd>You don't have to worry if your writing isn't as clear or precise as you'd like. We'll turn your prose into something other people can read.</dd> + <dt>Consistency of style</dt> + <dd>We'll ensure that your content is stylistically consistent not just within itself, but with the other documentation around it.</dd> + <dt>Content management</dt> + <dd>Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.</dd> + <dt>Site and platform maintenance</dt> + <dd>MDN has both an IT team who keep the site up, running, and secure, and a platform development team who maintain and enhance the platform. You won't need to devote your own or additional resources to documentation infrastructure.</dd> +</dl> + +<h2 id="Cases_for_documenting_elsewhere">Cases for documenting elsewhere</h2> + +<p>There are also a few reasons you may be thinking about documenting your work somewhere other than MDN. Here are some of those reasons, and the pros and cons for each.</p> + +<h3 id="Plans_and_processes">Plans and processes</h3> + +<p>Documentation for plans, processes, and proposals should never be put on MDN. That's pretty simple. If your project is part of Mozilla, you can put them on the <a href="https://wiki.mozilla.org/Main_Page">Mozilla project wiki</a>.</p> + +<h3 id="The_project_is_on_Github">The project is on Github</h3> + +<p>Some of Mozilla's projects are hosted on Github, and Github offers its own wiki-like system for documentation. Some teams like to produce their documentation there. This is certainly fair and convenient if you're game to write your own docs; however, keep in mind that:</p> + +<ul> + <li>The MDN docs team will probably not be able to help you. We don't generally participate in documentation work off MDN; there are exceptions but they are rare.</li> + <li>Cross-linking your documentation with other relevant materials may be difficult or impossible.</li> + <li>The content will not have consistent style with other documentation.</li> + <li>Your documentation loses discoverability by not being among other (Web or Mozilla) documentation.</li> + <li>Github-hosted docs are generally not as attractive and/or readable as those hosted on MDN.</li> +</ul> + +<p>It's possible, of course, that these things don't bother you, or aren't a problem in your situation. Some teams don't mind keeping their own docs, or are working on code that has minimal documentation needs.</p> + +<h3 id="You_want_to_keep_docs_in-source">You want to keep docs in-source</h3> + +<p>Some teams like to have their documentation in the source tree. This is particularly common with project internals and library projects.</p> + +<p>This approach has a couple of advantages:</p> + +<ul> + <li>It lets the developers document their technology as they code it, helping to ensure that the docs stay up to date with the code.</li> + <li>Docs can be subject to the same development and release processes as the code, including versioning.</li> +</ul> + +<p>There are some drawbacks:</p> + +<ul> + <li>The MDN docs team can't help you; even if the code is within Mozilla's source repository, the system of reviews and check-ins make it impractical for the docs team to participate.</li> + <li>You don't have easy tools for cross-linking with other relevant documentation. Cross-linking provides both context and additional important information to your readers.</li> + <li>Your documentation loses discoverability by not being among other documentation.</li> + <li>Even if you use conversion tools (like JavaDoc) to create Web-readable documentation, it won't be as attractive as what we can do on MDN.</li> +</ul> + +<p>Still, this can be a viable option (possibly even a good option) for some types of projects, especially small ones or those that aren't expected to get much interest.</p> + +<p>{{endnote("*")}} It's OK to put a limited amount of personal information on your MDN profile page. User profiles should reflect a human being, not a business or organization. A moderate degree of self-promotion is OK, but link-spamming is not. Please <em>do not </em>use your profile to upload personal photos or other irrelevant files.</p> diff --git a/files/zh-cn/mdn/guidelines/style_guide/index.html b/files/zh-cn/mdn/guidelines/style_guide/index.html new file mode 100644 index 0000000000..285b2703cb --- /dev/null +++ b/files/zh-cn/mdn/guidelines/style_guide/index.html @@ -0,0 +1,784 @@ +--- +title: MDN Web 文档写作规范 +slug: MDN/Guidelines/Style_guide +tags: + - MDN + - MDN Meta + - MDN Web 文档 + - MDN 规范 + - 写作规范 + - 准则 + - 教程 + - 文档 + - 规范 +translation_of: MDN/Guidelines/Writing_style_guide +--- +<div>{{MDNSidebar}}</div> + +<p>{{IncludeSubnav("/zh-CN/docs/MDN")}}</p> + +<p><span class="seoSummary">为了提供更加组织化、标准化且易于阅读的文档，MDN Web 文档写作规范明确了文本的组织方式、拼写规则、固定格式等内容，不过这些内容只是指导性的而不是严格的规定，</span>因为比起格式我们对内容更感兴趣，所以没有必要在参与贡献之前强迫自己学习本规范。但是如果有一位勤劳的志愿者在之后编辑了你的文档使它更加符合本规范，也请不要感到惊讶或难过。</p> + +<p>如果你正在寻找一个特定类型的页面应该如何构建的相关细节，请参阅<a href="/zh-CN/docs/MDN/Contribute/Content/Layout" title="MDN页面布局指南">MDN Web 文档页面布局规范</a>。</p> + +<p>本规范主要适用于英文文档。 其他语言可能也有（也欢迎创建）相应的规范。 这些应该作为子页面发布在各个本地化小组的页面中。</p> + +<div class="note"> +<p>译注：本文的写作规范虽说是针对英文所写，但是其中的不少内容也适用于中文，可花点时间阅读一下。另外，中文翻译时的规范请参见《<a href="https://developer.mozilla.org/zh-CN/docs/Glossary_of_translation">翻译术语表和翻译规范</a>》。</p> +</div> + +<p>对于那些为MDN以外的站点内容所编写的规范，请参考 <a href="//www.mozilla.org/en-US/styleguide/" title="Mozilla 统一规范">Mozilla 统一规范</a>。</p> + +<h2 id="基础部分">基础部分</h2> + +<p>为了使文档保持更好的一致性，所有主流的写作规范指南都是从一些比较基本的写作规范开始的。以下几个小节所概述的这些基本规范内容应该会对你有很大帮助。</p> + +<h3 id="页面标题">页面标题</h3> + +<p>页面标题不仅会在搜索时用到，在页面顶部的面包屑路径中也会被用来表示文档的层级结构。页面标题（就是显示在页面顶部以及搜索结果中标题的部分）可以与页面URL“<em><locale>/docs/</em>”之后的“铭牌（slug）”部分不同.</p> + +<h4 id="文章标题和段落标题的大写规则"><strong>文章标题和段落标题的大写规则</strong></h4> + +<p>页面的标题和章节的标头应当使用语句式大写（只大写第一个单词的首字母以及专有名词的首字母），而不应该使用标题式大写：</p> + +<ul> + <li><strong class="correct">正确</strong>: "A new method for creating JavaScript rollovers"</li> + <li><strong class="incorrect">错误</strong>: "A New Method for Creating JavaScript Rollovers"</li> +</ul> + +<p>我们还有很多旧的页面是在这条规范确立之前就已经发布了的。所以只要你愿意，你随时可以更新它们的标题。我们也正在逐步完善它们。</p> + +<h4 id="标题和铭牌的选择">标题和铭牌的选择</h4> + +<p>页面的铭牌应该尽量简短，当创建一个新的层级时，新层级的铭牌最好只由一到两个单词组成。</p> + +<p>而页面的标题长度并没有什么严格的限制，只要合理并且表意明确即可。</p> + +<h4 id="创建新的子目录">创建新的子目录</h4> + +<p>当你要给某个新的主题或主体添加文章时，你通常需要创建一个引导页，然后再把要添加的文章作为子页面添加进去。引导页开篇应当用一两段话来描述一下当前主题或技术，然后添加一个子页面的目录列表，并简要描述每个页面的内容。你可以使用一些我们已经编写好的宏把相关的子页面自动插入到目录列表中。</p> + +<p>例如，<a href="/zh-CN/docs/Web/JavaScript">JavaScript</a>手册,其结构如下：</p> + +<ul> + <li><a href="/zh-CN/docs/Web/JavaScript/Guide" title="JavaScript/Guide">JavaScript/手册</a> - 主目录页</li> + <li><a href="/zh-CN/docs/Web/JavaScript/Guide/JavaScript_Overview" title="JavaScript/Guide/JavaScript_Overview">JavaScript/手册/JavaScript概述</a></li> + <li><a href="/zh-CN/docs/JavaScript/Guide/Functions" title="JavaScript/Guide/Functions">JavaScript/手册/函数</a></li> + <li><a href="/zh-CN/docs/JavaScript/Guide/Details_of_the_Object_Model" title="JavaScript/Guide/Details_of_the_Object_Model">JavaScript/手册/对象模型的细节</a></li> +</ul> + +<p>尽量避免把文章内容放置在层次结构的顶层，这会降低网站的访问速度，同时搜索和导航的效率也会下降。</p> + +<h3 id="文章内容的通用原则">文章内容的通用原则</h3> + +<p>在写任何文档时，知道该写多少是很重要的。如果你写的长篇大论，文章读起来就会冗长无味,更不会有人愿意使用它。保持文章内容适量很重要,原因有很多。这其中的原因就有：为了确保读者能够找到他们真正想要的信息，以及为搜索引擎提供足够的优质素材来对文章进行分析和排名。我们将在这里讨论前者（提供读者可能需要的信息）。如果想了解如何让文章更好地被搜索引擎分类和排名，查阅文章<a href="/zh-CN/docs/MDN/Contribute/Howto/Write_for_SEO">How to write for SEO on MDN</a>。</p> + +<p>我们的目标是在页面中包含读者可能需要的所有信息，但又不至于太过冗长。为了实现这个目标,我们给出了一些建议。</p> + +<h4 id="为读者着想">为读者着想</h4> + +<p>请记住，这些只是指导性的。其中某些建议并不适用于所有状况。当然你应该始终为你的读者着想。例如，在一篇介绍高级网络技术的文章中，通常不需要像介绍网络编程的文章那样包含过多的网络基本概念。</p> + +<h4 id="提供一个有用的简介">提供一个有用的简介</h4> + +<p>在开篇或第一个段落标题之前给出文章的简介，以使读者快速了解文章中是否包含他们感兴趣的内容。在指南或教程类的文章中，简介还应该让读者明白文章覆盖了哪些主题，以及文章期望读者能够从中了解到哪些知识。简介中应该包含文章中介绍和讨论的技术、API，并提供相关的链接，同时还应该提供可能会遇到的情况的提示。</p> + +<h5 id="示例：过于简短的简介">示例：过于简短的简介</h5> + +<p>下面这个例子中的简介太过于简短，很多信息都没有包含进来，比如“stroke text”是什么意思，文本会在哪里等。</p> + +<div class="example-bad"> +<p><strong><code>CanvasRenderingContext2D.strokeText()</code></strong> draws a string.</p> +</div> + +<h5 id="示例：过于冗长的简介">示例：过于冗长的简介</h5> + +<p>下面是上面那个简介的修改版，但是这次它又太过冗长了。其中包含了过多的细节，并且还包含了很多其他方法和属性，但实际上它应该将重点聚焦在 <code>strokeText()</code> 方法上，然后给出详细介绍它的文章的链接即可。</p> + +<div class="note"> +<p>译注：作为例子，内容并不重要，所以就不逐句翻译了。</p> +</div> + +<div class="example-bad"> +<p>When called, the Canvas 2D API method <strong><code>CanvasRenderingContext2D.strokeText()</code></strong>strokes the characters in the specified string beginning at the coordinates specified, using the current pen color. In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.</p> + +<p>The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.</p> + +<p>The placement of the text relative to the specified coordinates are determined by the context's <code>textAlign</code>, <code>textBaseline</code>, and <code>direction</code> properties. <code>textAlign</code> controls the placement of the string relative to the X coordinate specified; if the value is <code>"center"</code>, then the string is drawn starting at <code>x - (stringWidth / 2)</code>, placing the specified X-coordinate in the middle of the string. If the value is <code>"left"</code>, the string is drawn starting at the specified value of <code>x</code>. And if <code>textAlign</code> is <code>"right"</code>, the text is drawn such that it ends at the specified X-coordinate.</p> + +<p>(etc etc etc...)</p> + +<p>You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.</p> + +<p>You can call the <strong><code>fillText()</code></strong> method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.</p> +</div> + +<h5 id="示例：这次好多了">示例：这次好多了</h5> + +<p>下面这个简介比前两个要好很多。</p> + +<div class="example-good"> +<p>The {{domxref("CanvasRenderingContext2D")}} method <code><strong>strokeText()</strong></code>, part of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API">Canvas 2D API</a>, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.</p> + +<p>For more details and further examples, see {{SectionOnPage("/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Drawing_text">Drawing text</a>.</p> +</div> + +<h4 id="多提供一些示例">多提供一些示例</h4> + +<p>文章应该尽量多提供一些示例。实际上，大多数文章都应该包含不止一个例子。使用例子来说明每个参数的用途或每个可能的边界条件是很有必要的。同时还应该用例子来演示常见问题的解决方法，以及应该如何解决使用过程中可能碰到的坑。</p> + +<p>每个例子都应该先给出解释，说明它做了什么，以及读者在阅读或动手尝试之前需要了解的内容。</p> + +<p>另外，每段示例代码都应该就其工作原理给出说明。最好将一段较长的代码分解成多个较小的部分，并提供每个部分的说明，说明时注意细节的层次。如果代码很简单并且不直接涉及到当前 API，可以只给出一个简单的介绍，说明其用途，以及为何要把它放在这里；而如果代码比较复杂、或用到了当前的 API、或在技术上比较有创造性，那么你应该提供更详细的说明。</p> + +<p>如果使用的是在线演示的方式，则可以将 HTML、CSS、JavaScript 拆分到不同的 {{HTMLElement("pre")}} 中，它们在运行时会自动组合到一起，但使用这种方式每个里面都可以有自己的说明。因此这是一种很好很强大的方式。</p> + +<h4 id="过短的文章难以被搜索到">过短的文章难以被搜索到</h4> + +<p>如果文章过短，那么搜索引擎可能会难以甚至无法对其建立关键字索引。一般来说，文章的主体内容应该至少包含 250-300 个单词。但是也不要对内容确实很少的文章进行刻意的扩充，在可能的情况下尽量遵守该指导原则即可。</p> + +<h3 id="小节、段落和换行">小节、段落和换行</h3> + +<p>对于小节的标题，应使用从大到小的方式来定义级别：{{HTMLElement("h2")}}、{{HTMLElement("h3")}}、{{HTMLElement("h4")}} 这样，并且中间不要跳过某一级。因为 H1 已用于文章的标题，因此小节的标题应该从 H2 开始。如果你的文章中小节的层次超过了 3 到 4 级，那么你可能需要考虑将整篇文章拆分成几篇小的文章，然后用一个引导页给出这些文章的链接，并用 {{TemplateLink("Next")}}、{{TemplateLink("Previous")}}、{{TemplateLink("PreviousNext")}} 宏为它们创建导航。</p> + +<p>按下回车键（Enter 或 Return）可以开始一个新的段落。如果只是想换行而不是另起一段，可以按住 Shift 并敲下回车。</p> + +<p>不要创建只包含一个小节的子级别，如果只有一个小节，那么拆分主题就是没有意义的。至少包含两个小节，要么就不要拆分。</p> + +<p>不要让两个小节标题紧挨在一起，这样看起来很丑。每个小节标题的下面至少要放上一段对后面各子小节的简短说明，这会对阅读的人很有帮助。</p> + +<h3 id="列表">列表</h3> + +<p>列表的格式应该在所有文章中保持一致，并且应在列表中恰当使用标点和结构合理的句子。不管是哪种类型的列表，都需要对格式进行适当的调整。下面的内容说明了每种列表之间的不同。</p> + +<h4 id="无序列表">无序列表</h4> + +<p>无序列表可以以简洁且有效的方式对内容进行分组显示。每个条目都会以类似“•”的符号来标识。在无序列表中要注意正确使用标点，尤其是每句的最后不要遗漏掉句号。应该以标准写作方式来对待无序列表。</p> + +<p>下面是一个结构良好的无序列表的例子：</p> + +<div class="example-good"> +<p><em>在这个例子中需要包括:</em></p> + +<ul> + <li><em>一种情况，然后跟上一个简短的说明。</em></li> + <li><em>一种情况，然后跟上一个简短的说明。</em></li> + <li> + <p><em>另一种情况，并跟上一些解释和说明。</em></p> + </li> +</ul> +</div> + +<p>可以看到，每个条目的格式都是一致的：首先显示一个“•”符号，然后列出一种情况，然后写上逗号，并在逗号后面添加一些对当前情况的简单说明。</p> + +<h4 id="有序列表">有序列表</h4> + +<p>有序列表用序号来标识每个条目。同样要注意应该在有序列表中使用适当的格式，保持列表的清晰和简洁，这一点与无序列表是类似的。但是有序列表中的某些条目内容可能会很多，因此正确使用标点就更为重要了，因为难免会遇到必须使用复杂句子的情况。</p> + +<p>下面是一个结构良好的有序列表的例子：</p> + +<blockquote> +<p>为了创建一个好的有序列表，你需要：</p> + +<ol> + <li>以一个介绍性的标题开始，以引出后续的序列。我们可以在开始有序列表的序列之前提供这一内容。</li> + <li>开始创建各个序列，这些序列会用数字依次编号。这是有序列表的标准格式，能够很容易地被读者理解。有序列表中的某些条目内容可能会很多，因此正确使用标点是很重要的。</li> + <li>列表序列完成之后，应在后面再提供一段简短的总结。</li> +</ol> + +<p>这段内容就是一个总结。我们已经创建了一个简短的有序列表，解释了创建良好格式的有序列表应遵循的步骤。</p> +</blockquote> + +<p>有序列表基本都用来表示具有连续性关系的内容，因此应该先深入思考你要用这些内容达到什么目的，然后再去撰写。</p> + +<h3 id="文本格式和样式">文本格式和样式</h3> + +<p>可以使用“样式”下拉列表中的预定义样式来格式化你选定的内容。</p> + +<div class="note"> +<p>“Note”样式用来强调重要提示，就像这个。</p> +</div> + +<div class="warning"> +<p>类似地，“Warning”样式用来创建一个警告框。</p> +</div> + +<p>除非有特殊需要，否则请不要用 HTML 的 <code>style</code> 属性来手动给内容添加样式。如果你没有找到你需要的预定义样式，可以放置一个 {{IRCLink("mdn")}} 并寻求帮助。</p> + +<h3 id="示例代码的格式和样式">示例代码的格式和样式</h3> + +<div class="note"> +<p>这一小节只是讨论 MDN 文章中的示例代码的样式和格式问题，如果你想了解如何编写示例代码，请参考<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Guidelines/Code_samples">示例代码指南</a>。</p> +</div> + +<h4 id="缩进和换行符">缩进和换行符</h4> + +<p>每级缩进都使用两个空格来缩进，并在所有的示例中保持一致。对于代码块的起始语句，应将开大括号“{”与当前语句写在一行上，比如：</p> + +<pre class="brush: js notranslate">if (condition) { + /* handle the condition */ +} else { + /* handle the "else" case */ +} +</pre> + +<p>如果一行的代码很长，应在适当的地方换行以避免出现水平滚动条。下面是一个例子：</p> + +<pre class="brush: js notranslate">if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION + || class.YET_ANOTHER_CONDITION ) { + /* something */ +} + +var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"] + .createInstance(Components.interfaces.nsIToolkitProfileService); +</pre> + +<h4 id="内联代码格式">内联代码格式</h4> + +<p>对于函数名、变量名、方法名等，应使用“Inline Code”按钮（编辑器中显示为“<>”的按钮）将其设置为内联代码格式（内联代码使用的是 {{HTMLElement("code")}} 元素）。比如：<code>frenchText()</code> 函数。</p> + +<p>方法名后面应该加上小括号：<code>doSomethingUseful()</code>，这样会比较容易将方法与其他代码元素区分开来。</p> + +<h4 id="语法高亮">语法高亮</h4> + +<p><img alt="Screenshot of the 'Syntax Highlighter' menu." src="https://mdn.mozillademos.org/files/12682/Language%20list.png" style="border-style: solid; border-width: 1px; float: right; margin: 2px 4px;">对于整行或多行代码，此时别再使用 {{HTMLElement("code")}} 元素来格式化了，而应该对其进行语法高亮。点击语法高亮器按钮（图标是两个代码块），从语言下拉列表中选择一种合适的语言即可。见右图。</p> + +<p>下面的例子使用了 JavaScript 语法高亮：</p> + +<div class="line number2 index1 alt1"> +<pre class="brush: js notranslate">for (var i = 0, j = 9; i <= 9; i++, j--) + document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);</pre> +</div> + +<p>如果没有在下拉列表中找到你需要的语言，可以选择第一项“没有高亮”，此时代码显示的是不带高亮效果的普通样式：</p> + +<pre class="brush: plain notranslate">x = 42;</pre> + +<h4 id="语法定义">语法定义</h4> + +<p>如果你想插入一段语法定义，可以使用样式下拉列表中的“Syntax Box”选项。语法定义的样式与普通代码的样式会有所区别。</p> + +<h4 id="非代码区块">非代码区块</h4> + +<p>有些情况下需要用到 <code><pre></code> 区块而不是代码区块，此时不会进行语法高亮，也不会显示行号。比如你需要显示树形结构，就可以使用 <code><pre></code>：</p> + +<pre class="notranslate">root/ + + folder1/ + file1 + + folder2/ + file2 + file3 +</pre> + +<p>插入方法是要先点击”pre“按钮，然后输入想要的内容即可。</p> + +<h4 id="HTML_元素的样式">HTML 元素的样式</h4> + +<p>HTML 元素的样式有一套自己的规则。遵守这些规则可以让元素及其组件的描述方式保持统一，并且还可以保证能够正确链接到各元素的详细文档页面。</p> + +<dl> + <dt>元素名称</dt> + <dd>使用 {{TemplateLink("HTMLElement")}} 宏会生成一个指向该元素详情页的链接。比如，\{{HTMLElement("title")}} 会生成”{{HTMLElement("title")}}“。如果不想生成链接，就将元素名称用尖括号括起来，然后将其设置为内联代码样式，比如 <code><title></code>。</dd> + <dt>属性名称</dt> + <dd>请使用<strong>粗体</strong>。</dd> + <dt>属性定义</dt> + <dd>对正在定义的术语使用 {{TemplateLink("htmlattrdef")}} 宏（如 \{{htmlattrdef("type")}}），这样其他页面就可以使用 {{TemplateLink("htmlattrxref")}} 宏来链接到该页面了（例如 \{{htmlattrxref("attr","属性")}}）。</dd> + <dt>属性值</dt> + <dd>请使用内联代码样式，并且注意字符串两边不要加引号，除非是代码的语法要求加引号。举例：当将 <code><input></code> 元素的 <strong>type</strong> 属性设置为 <code>email</code> 或 <code>tel</code> 时……</dd> + <dt>为属性添加说明标签</dt> + <dd>请不要滥用 {{HTMLVersionInline(5)}} 这样的标签。比如，可以在某个第一次出现的属性名称旁边添加标签，但是不要在每次出现该属性的时候都添加一次。</dd> +</dl> + +<h3 id="拉丁文缩写">拉丁文缩写</h3> + +<h4 id="在补充说明的括号中">在补充说明的括号中</h4> + +<p>一般的拉丁文缩写（如：”etc.“、”i.e.“、”e.g.“）都可以用在起补充说明的括号里面。这时应在缩写中添加句号，后面加上逗号或其他恰当的标点。</p> + +<ul> + <li><span class="correct"><strong>正确</strong></span>：Web browsers (e.g., Firefox) can be used ...</li> + <li><span class="incorrect"><strong>错误</strong></span>：Web browsers e.g. Firefox can be used ...</li> + <li><span class="incorrect"><strong>错误</strong></span>：Web browsers, e.g. Firefox, can be used ...</li> + <li><span class="incorrect"><strong>错误</strong></span>：Web browsers, (eg: Firefox) can be used ...</li> +</ul> + +<h4 id="在一般句子中">在一般句子中</h4> + +<p>在普通的句子中（即括号的外面），请使用与缩写等价的英文单词或短语。</p> + +<ul> + <li><span class="correct"><strong>正确</strong></span>：... web browsers, and so on.</li> + <li><span class="incorrect"><strong>错误</strong></span>：... web browsers, etc.</li> + <li><span class="correct"><strong>正确</strong></span>：Web browsers such as Firefox can be used ...</li> + <li><span class="incorrect"><strong>错误</strong></span>：Web browsers e.g. Firefox can be used ...</li> +</ul> + +<h4 id="缩写、拉丁文原文和英文的对照表">缩写、拉丁文原文和英文的对照表</h4> + +<table> + <tbody> + <tr> + <th>缩写</th> + <th>拉丁文</th> + <th>英文</th> + </tr> + <tr> + <td>cf.</td> + <td><em>confer</em></td> + <td>compare</td> + </tr> + <tr> + <td>e.g.</td> + <td><em>exempli gratia</em></td> + <td>for example</td> + </tr> + <tr> + <td>et al.</td> + <td><em>et alii</em></td> + <td>and others</td> + </tr> + <tr> + <td>etc.</td> + <td><em>et cetera</em></td> + <td>and so forth, and so on</td> + </tr> + <tr> + <td>i.e.</td> + <td><em>id est</em></td> + <td>that is, in other words</td> + </tr> + <tr> + <td>N.B.</td> + <td><em>nota bene</em></td> + <td>note well</td> + </tr> + <tr> + <td>P.S.</td> + <td><em>post scriptum</em></td> + <td>postscript</td> + </tr> + </tbody> +</table> + +<div class="note"> +<p>在使用前请仔细思考使用拉丁文缩写是否真的能带来好处。上面列出的某些缩写很少用到，很多读者可能不知道其意思，还有一些读者可能会分不清其中的某些缩写。另外，如果你决定使用缩写，那么请确保你的用法是正确的。比如，一个很多人经常会犯的错误是将“e.g.”和“i.e.”弄混。</p> +</div> + +<h4 id="首字母缩写和一般缩写">首字母缩写和一般缩写</h4> + +<dl> + <dt>大写与句号</dt> + <dd>在这两种缩写中（包括国家和组织的缩写，如“US”、“UN”），请使用全大写且不要添加句号。</dd> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: XUL</li> + <li><span class="incorrect"><strong>错误</strong></span>: X.U.L.、Xul</li> + </ul> + </dd> + <dt>缩写展开</dt> + <dd>文章中第一次遇到某个缩写术语时，应该同时给出其展开形式，从而让不了解该缩写的读者能够知道它所指代的内容。如果不确定要不要展开那么就选择展开，或者更好的办法是将其链接到<a href="https://developer.mozilla.org/zh-CN/docs/Glossary">术语表</a>中的对应条目。</dd> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: XUL (XML User Interface Language) is Mozilla's XML-based language...</li> + <li><span class="incorrect"><strong>错误</strong></span>: XUL is Mozilla's XML-based language...</li> + </ul> + </dd> + <dt>缩写的复数形式</dt> + <dd>当需要使用复数形式的缩写时，直接在后面加上“s”即可，请务必不要加撇号。</dd> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: CD-ROMs</li> + <li><span class="incorrect"><strong>错误</strong></span>: CD-ROM's</li> + </ul> + </dd> + <dt>”Versus“、”vs.“和”v.“</dt> + <dd>推荐使用”vs.“。</dd> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: this vs. that</li> + <li><span class="incorrect"><strong>错误</strong></span>: this v. that</li> + <li><span class="incorrect"><strong>错误</strong></span>: this versus that</li> + </ul> + </dd> +</dl> + +<h3 id="大写">大写</h3> + +<p>在文章内容中请使用标准英文大写规则，比如对于”World Wide Web“需大写每个单词的首字母。如果”web“和”internet“是单独使用或作为修饰词使用，那么将其全小写也可以——这一指导原则是后来修改过的，所以在 MDN 中你也许会看到很多首字母大写的”Web“和”Internet“。当你编辑文章的时候遇到这种情况，可以随它去，也可以随手修改一下。但是仅仅只是为了修改一下大写的话就没必要专门去编辑一下了。</p> + +<p>对于键盘按键，应该使用普通的大写规则，而不是全大写。比如，是”Enter“而不是”ENTER“。</p> + +<h3 id="简写">简写</h3> + +<p>我们倾向于宽松的写作风格，所以你可以按你的喜好来决定是否使用简写（如”don't“、”can't“、”shouldn't“）。</p> + +<h3 id="名称复数">名称复数</h3> + +<p>请使用英文风格的复数形式，不要使用拉丁文或希腊文的形式。</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: syllabuses、octopuses</li> + <li><span class="incorrect"><strong>错误</strong></span>: syllabi、octopi</li> + </ul> + </dd> +</dl> + +<h3 id="连字符">连字符</h3> + +<p>当两个单词连起来组成另一个单词时，如果前一个单词的最后一个字母是元音字母，并且与后一个单词的第一个字母相同时，应使用连字符。</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: email、re-elect、co-op</li> + <li><span class="incorrect"><strong>错误</strong></span>: e-mail、reelect、coop</li> + </ul> + </dd> +</dl> + +<h3 id="使用性别中立的表述">使用性别中立的表述</h3> + +<p>在任何性别无关的场合使用性别中立的表述方式是一种比较好的做法，这样可以使你的文章具有普适性。举个例子，如果你正在写的是关于某个男人的行为，那么使用”他“来指代是没问题的；但如果内容并没有特指是男还是女，那么再使用”他“就不太恰当了。</p> + +<p>让我们再看几个例子：</p> + +<p class="summary">弹出一个对话框，让用户确认他是否允许网页使用他的网络摄像头。</p> + +<p class="summary">弹出一个对话框，让用户确认她是否允许网页使用她的网络摄像头。</p> + +<p>这两句话使用的都是特定性别的表述方式，我们可以将其修改为性别中立的代词：</p> + +<p class="summary">弹出一个对话框，让用户确认他们是否允许网页使用他们的网络摄像头。</p> + +<div class="note"> +<p>译注：这里原文为”they“和”their“，在英文中是性别中立的代词。而中文中如果上下文没有强调性别，则”他们“也具有性别中立性。</p> +</div> + +<div class="note"> +<p>MDN 允许使用这种通用性的语法（尽管在正式用法中这一点还存在争议）来弥补英语在表达中立性别时的不足。将第三人称复数的代词用来表示性别中立代词（即使用”they“、”them“、”their“、”theirs“）是可以接受的，也就是通常所说的”单数形式的‘they’“。</p> +</div> + +<p>你还可以同时写上两个性别：</p> + +<p class="summary">弹出一个对话框，让用户确认他或她是否允许网页使用他/她的网络摄像头。</p> + +<div class="note"> +<p>译注：中文里一般不这么用，所以如果在翻译中遇到这种情况，请简单翻译为”他“即可。”中文翻译规范“一文的”<a href="https://developer.mozilla.org/zh-CN/docs/Glossary_of_translation#误解：100_翻译_准确">误解：100% 翻译 = 准确</a>“一节中也提到了这个问题。</p> +</div> + +<p>或者使用复数形式的”users“：</p> + +<p class="summary">弹出一个对话框，让用户（译注：原文为”users“）确认他们是否允许网页使用他们的网络摄像头。</p> + +<p>当然，最好的方法还是重写句子，去掉其中的代词：</p> + +<p class="summary">弹出一个对话框，询问用户是否允许网页对网络摄像头的访问。</p> + +<p class="summary">弹出一个询问用户以获取网络摄像头访问权限的对话框。</p> + +<p>最后一种方法（译注：意指去除代词的方法）可能更好一些，因为它不但语法上更加正确，而且还能消除不同语言处理性别问题时所带来的复杂性，因为不同语言对性别的处理可能有不同的规则。因此这种方法无论是对读者（译注：意为阅读英语原文的非英语读者）还是翻译者来说都可以让翻译更简单。</p> + +<h3 id="数字和数词">数字和数词</h3> + +<h4 id="日期">日期</h4> + +<p>请用”January 1, 1990“这样的形式来表达日期（不包括代码中的日期）。</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: February 24, 2006</li> + <li><span class="incorrect"><strong>错误</strong></span>: February 24th, 2006、24 February, 2006、24/02/2006</li> + </ul> + </dd> +</dl> + +<p>或者你也可以使用”YYYY/MM/DD“的形式：</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: 2006/02/24</li> + <li><span class="incorrect"><strong>错误</strong></span>: 02/24/2006、24/02/2006、02/24/06</li> + </ul> + </dd> +</dl> + +<h4 id="年代">年代</h4> + +<p>请使用”1990s“这种形式来表示年代，但不要使用撇号：</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: 1990s</li> + <li><span class="incorrect"><strong>错误</strong></span>: 1990's</li> + </ul> + </dd> +</dl> + +<h4 id="数词的复数">数词的复数</h4> + +<p>数词的复数直接在后面加”s“，同样不要使用撇号：</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: 486s</li> + <li><span class="incorrect"><strong>错误</strong></span>: 486's</li> + </ul> + </dd> +</dl> + +<h4 id="逗号">逗号</h4> + +<p>应该仅在数字的位数大于等于 5 位时才使用逗号分隔符：</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: 4000、54,000</li> + <li><span class="incorrect"><strong>错误</strong></span>: 4,000、54000</li> + </ul> + </dd> +</dl> + +<h3 id="标点符号">标点符号</h3> + +<h4 id="连续逗号">连续逗号</h4> + +<p>请使用连续逗号。连续逗号（也叫牛津逗号）是在一个包含三个或以上单词或短语的序列中位于连词前的那个逗号。</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: I will travel on trains, planes, and automobiles.</li> + <li><span class="incorrect"><strong>错误</strong></span>: I will travel on trains, planes and automobiles.</li> + </ul> + </dd> +</dl> + +<div class="note"> +<p>译注：这种情况在翻译时应将逗号翻译为顿号。”中文翻译规范“一文的”<a href="https://developer.mozilla.org/zh-CN/docs/Glossary_of_translation#标点符号">标点符号</a>“一节中也提到了这个问题。</p> +</div> + +<div class="note"> +<p>这一点与 <a href="https://www.mozilla.org/en-US/styleguide/">Mozilla 统一规范</a>有冲突，后者要求不要使用连续逗号。MDN 是这一规则的特例。</p> +</div> + +<h3 id="拼写">拼写</h3> + +<p>如果一个单词具有多种拼写，请使用美国英语的拼写。一般来说，<a href="http://www.dictionary.com/">Dictionary.com</a> 上的第一个拼写是符合此要求的，除非单词本身即为其他变体形式或主要用于美国以外的国家中。例如，如果你去查”<a href="http://dictionary.reference.com/browse/honour">honour</a>“，你会看到一个标注”Chiefly British“，并在其后有一个指向美语标准形式的链接。请不要使用其他的拼写变体。</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: localize、honor</li> + <li><span class="incorrect"><strong>错误</strong></span>: localise、honour</li> + </ul> + </dd> +</dl> + +<h3 id="术语">术语</h3> + +<h4 id="HTML_元素">HTML 元素</h4> + +<p>请使用”元素“来表示 HTML 和 XML 元素，不要使用”标记“。另外，请在元素名称两边使用尖括号 ”<>“ 括起来，并使用 {{HTMLElement("code")}} 样式。当文章中第一次出现某个元素的时候，应该用 {{TemplateLink("HTMLElement")}} 宏创建一个指向该元素文档的链接（除非你正在撰写的恰好是该元素的文档页面）。</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: {{HTMLElement("span")}} 元素</li> + <li><span class="incorrect"><strong>错误</strong></span>: span 标记</li> + </ul> + </dd> +</dl> + +<h4 id="函数参数">函数参数</h4> + +<p>在 MDN 上推荐使用 <strong>parameters</strong> 来表示函数的参数，为了保持一致性，如果可能的话请尽量避免使用”arguments“。</p> + +<h4 id="描述用户的操作">描述用户的操作</h4> + +<p>在说明一系列操作步骤时，应使用祈使语气来描述用户的操作，并用 UI 组件的名称和其元素类型来标识操作对象。</p> + +<dl> + <dd> + <ul> + <li><font color="#008000"><strong>正确</strong></font>: 点击编辑按钮</li> + <li><span class="incorrect"><strong>错误</strong></span>: 点击编辑</li> + </ul> + </dd> +</dl> + +<h3 id="语态">语态</h3> + +<p>推荐使用主动语态，但被动语态也可以接受，只是可能会让文章看起来不太正式。建议选择一种并在文章中尽量保持统一。</p> + +<h2 id="Wiki_标记及用法">Wiki 标记及用法</h2> + +<h3 id="链接">链接</h3> + +<p>链接是 wiki 中最重要的功能元素之一。这里会介绍一些链接的基本内容，在我们的编辑器指南中的<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Editor/Links">在MDN中创建和编辑链接</a>这篇文章中有关于链接的详细介绍。</p> + +<p>我们鼓励适当的添加一些相关文章的链接，这样可以提高页面导航的效率和内容的易发现性。链接不但可以指向其他 MDN 页面（内部链接），也可以指向其他网站的页面（外部链接）。</p> + +<p>有两种创建链接的方式：点击编辑器工具栏中的“插入/编辑超链接”按钮（也可以按 <kbd>Ctrl</kbd>+<kbd>K</kbd> 键（在 Mac 上是 <kbd>Cmd</kbd>-<kbd>K</kbd> 键）），或者使用 MDN 强大的宏功能来自动创建或根据输入的内容创建链接。</p> + +<p>下面列出的指导意见可以帮助你确定创建链接时使用什么样的链接文本：</p> + +<ul> + <li>当可以使用宏来创建所需的链接时，请使用宏来创建。<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Editor/Links#Using_link_macros">使用宏来创建链接</a>不仅可以确保链接的正确性，而且在 MDN 改进了一个宏之后，所有使用该宏的地方都会自动更新。</li> + <li>对于 API 名称，请使用该 API 术语的完整名称来作为链接文本。要做到这一点，最方便的方法是<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Editor/Links#Linking_to_documentation_for_APIs">使用恰当的宏</a>来创建格式良好的链接。</li> + <li>如果要在某个术语上添加一个指向定义或介绍该术语的详情页面，请使用该术语的名称作为链接文本，不要擅自添加其他内容。例如： + <ul> + <li><font color="#008000"><strong>正确</strong></font>: 你可以使用 <a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript">JavaScript</a> 代码来创建动态网页程序。</li> + <li><span class="incorrect"><strong>错误</strong></span>: 你可以使用 <a href="https://developer.mozilla.org/zh-CN/docs/Web/JavaScript">JavaScript 代码</a>来创建动态网页程序。</li> + </ul> + </li> + <li>其他情况下，当链接指向的页面并不能用一个简单且确定的词来描述时，请尽量选择具有明确动作和目标的短语。例如： + <ul> + <li><font color="#008000"><strong>正确</strong></font>: 如果你希望<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Developer_guide">对 Firefox 项目做贡献</a>，首先你需要<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Developer_guide/Build_Instructions">下载并构建 Firefox</a>。</li> + <li><span class="incorrect"><strong>错误</strong></span>: <a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Developer_guide">如果你希望对 Firefox 项目做贡献</a>，首先你需要<a href="https://developer.mozilla.org/zh-CN/docs/Mozilla/Developer_guide/Build_Instructions">下载并构建</a> Firefox。</li> + </ul> + </li> +</ul> + +<h4 id="URL_语法">URL 语法</h4> + +<p>为了保险起见，应始终使用下面的语法来创建链接：</p> + +<ul> + <li><code>http://</code></li> + <li><code>https://</code></li> + <li><code>ftp://</code></li> + <li><code>mailto:</code></li> +</ul> + +<p>其他语法可能无法工作或者不受支持，并有可能会被编辑人员删掉。</p> + +<div class="note"> +<p>强调一下，不要使用 <code>about:</code> 和 <code>chrome://</code> 等语法，因为它们可能无法生效。类似地， <code>javascript:</code> 可能会被最新的浏览器阻止，<code>jar:</code> 同理。</p> +</div> + +<h3 id="页面标签">页面标签</h3> + +<p>标签用来提供与页面有关的元数据信息，或者用来标记当前页面在某方面仍需要完善。wiki 中的每个页面都应该包含标签。在<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Howto/Tag">如何合理地标记页面</a>这篇指南中有更多关于使用标签的信息。</p> + +<p>在编辑文章时，标签位于编辑器的底部，看起来是这样的：</p> + +<p><img alt="在 MDN 中为页面添加和删除标签" src="https://mdn.mozillademos.org/files/7859/tag-interface.png" style="border-style: solid; border-width: 1px; height: 167px; width: 863px;"></p> + +<p>要添加标签，点击标签列表最后的”新建标签……“按钮，然后输入要添加的标签名称。标签会随着你的输入显示自动完成提示。最后按下回车键来确认并提交新标签。可以为一篇文章添加任意多个标签。举个例子，一篇关于在 AJAX 编程中使用 JavaScript 的文章可能需要添加”JavaScript“和”AJAX“这两个标签。</p> + +<p>要删除一个标签，点击标签上的”X“图标即可。</p> + +<h4 id="标记页面的后续事项">标记页面的后续事项</h4> + +<p>标签还可以用于将文章标记为需要某些后续的工作，用来跟踪文章质量和内容方面的信息。</p> + +<h4 id="标记已废弃页面">标记已废弃页面</h4> + +<p>可使用下面的标签来标记不再使用的页面：</p> + +<ul> + <li>Junk（需删除）：用于因为不小心弄错了而创建的页面、或因为内容太差而准备删除的页面。具有该标签的页面随时会被删除。</li> + <li>Obsolete（已废弃）：用于技术已经作废或已被其他技术所取代，但是该技术仍然可用的文章。例如某个在 HTML 4.01 中依然可用但在 HTML5 中已经废弃的元素。你也可以使用 {{TemplateLink("obsolete_header")}} 宏在文章顶部显示一个醒目的提示。</li> + <li>Archive（存档）：用于技术已经废弃或已被其他技术所取代，并且已无法使用的文章。如果可能，请在文章顶部再添加一条提示，给读者提供新的技术文章的链接。例如，介绍如何使用 Mozilla CVS 仓库的文章中应该添加一条指向介绍使用 Mercurial 仓库的文章链接。（如果新技术的文章的页面还没有创建，可以使用 NeedsUpdate（需要更新）标签，并在 Talk 页面添加一条说明。）添加了”Archive“标签的页面最终都会从主内容区移到 MDN 的<a href="https://developer.mozilla.org/zh-CN/docs/Archive">存档</a>区。</li> +</ul> + +<h3 id="SEO_概要">SEO 概要</h3> + +<p>SEO 概要是对一篇文章的简短描述，它会在网页机器爬虫抓取到当前页面时告诉爬虫该文章的概要，当用户搜索到该页面时就会显示此概要信息。另外，在 MDN 内部通过宏来自动生成引导页的时候也会用到它。</p> + +<p>默认情况下，文章的第一段内容会被当成是 SEO 概要。但是你可以<a href="https://developer.mozilla.org/zh-CN/docs/Project:MDN/Contributing/Editor_guide/Editing#Formatting_styles">在编辑器中使用“SEO Summary“样式</a>来手动指定一段内容作为 SEO 概要。</p> + +<h3 id="引导页">引导页</h3> + +<p>引导页的层级位于网站层级的顶层，例如 <a href="https://developer.mozilla.org/zh-CN/docs/CSS">CSS</a> 和 <a href="https://developer.mozilla.org/zh-CN/docs/HTML">HTML</a> 的主页面就是引导页。引导页具有标准的格式，由以下 3 个部分组成：</p> + +<ul> + <li>一个简介（一般是一段），用来介绍当前页面所讨论的技术及其如何使用。见本文的 {{anch("Creating new subtrees", "创建新的子目录")}}。</li> +</ul> + +<div class="note"> +<p>译注：这里的链接原本是指向原文的”Writing a landing page overview“一节，但该节貌似已被删除了，所以链接已失效。这里我找到了一个与其内容相近的小节。</p> +</div> + +<ul> + <li>一个两列的列表，其中包含一些小节并提供一些指向其他文章的链接。见本文的 {{anch("Creating a page link list", "创建相关页面的链接列表")}}。</li> + <li>第三个是可选的”浏览器兼容性“一节，位于页面的底部。</li> +</ul> + +<h4 id="创建相关页面的链接列表">创建相关页面的链接列表</h4> + +<p>引导页中的链接列表部分有两列，其 HTML 代码的结构如下：</p> + +<pre class="brush: html notranslate"><div class="row topicpage-table"> + <div class="section"> + ... 左侧列 ... + </div> + <div class="section"> + ... 右侧列 ... + </div> +</div></pre> + +<p>左侧列的顶部是一个 <code><h2></code> 标题，用来说明此列的内容是当前主题所包含的文章列表（如”某某的文档和教程“），其下方则是具体的文章列表。该列的标题样式应使用 CSS 类 ”Documentation“，而下方的文章列表是一个 <code><dl></code> 列表，其中的每个 <code><dt></code> 都包含一个文章的链接和位于 <code><dd></code> 中的该目标文章的一两句话的说明。</p> + +<p>右侧列则包含一或多个小节，各小节按以下顺序排列：</p> + +<dl> + <dt>获取社区的帮助</dt> + <dd>该节用来提供当前主题相关的 Matrix 频道和邮件列表信息。标题需使用 CSS 类”Community“。</dd> + <dt>工具</dt> + <dd>可以帮助用户使用当前主题所介绍的技术的工具列表。标题需使用 CSS 类”Tools“。</dd> + <dt>相关主题</dt> + <dd>一些链接到其他相关技术的引导页链接。标题需使用 CSS 类”Related_Topics“。</dd> +</dl> + +<p><<<当引导页的标准完成时需要继续完善本节内容>>></p> + +<h2 id="插入图片">插入图片</h2> + +<p>在创建或编辑文章时，有时候使用图片会对文章内容有不少好处，特别是文章的技术性很强的时候。可以使用下面的方法来添加一个图片：</p> + +<ol> + <li>先添加一个图片附件到当前文章中（附件在编辑器的底部）</li> + <li>点击”图像“按钮，弹出对话框</li> + <li>在对话框中的附件下拉列表中，选择刚添加的图片</li> + <li>点击确定按钮</li> +</ol> + +<h2 id="其他参考资料">其他参考资料</h2> + +<h3 id="推荐样式指南">推荐样式指南</h3> + +<p>如果你在撰写过程中或在格式方面遇到了本文尚未提及的问题，我们建议你参考 <a href="http://www.economist.com/styleguide/introduction">Economist 网站的风格指南</a>，如果还是不能解决问题，还可参考<a href="https://www.amazon.com/Chicago-Manual-Style-16th/dp/0226104206">芝加哥论文格式</a>。</p> + +<h3 id="推荐词典">推荐词典</h3> + +<p>如果有拼写方面的问题，请参考 <a href="http://www.dictionary.com/">Dictionary.com</a>。本网站的拼写检查采用美国英语规则，因此请不要使用其他拼写规则（例如应该使用“color”而不是“colour”）。</p> + +<p>我们会继续扩充本指南，因此如果你遇到了本文未提及的问题，请通过 <a href="https://developer.mozilla.org/zh-CN/docs/Project:Community">MDC 邮件列表</a>或<a href="https://developer.mozilla.org/User:Sheppy">项目带头人</a>联系我们，让我们了解还需要加入哪些内容。</p> + +<h3 id="MDN">MDN</h3> + +<p>MDN 中<a href="https://developer.mozilla.org/zh-CN/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros">常用的宏</a>及其说明。</p> + +<h3 id="语言、语法和拼写">语言、语法和拼写</h3> + +<p>如果你对提高写作和编辑能力感兴趣，下面的资料会对你有所帮助：</p> + +<ul> + <li><a href="http://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction/dp/0060891548">更好的写作</a>（Amazon），作者 William Zinsser</li> + <li><a href="http://www.amazon.com/Style-Basics-Clarity-Grace-4th/dp/0205830765/">清晰与优雅的格式基础</a>（Amazon），作者 Joseph Williams 和 Gregory Colomb</li> + <li><a href="https://brians.wsu.edu/common-errors-in-english-usage/">使用英文时的常见错误</a></li> + <li><a href="http://www-personal.umich.edu/~jlawler/aue.html">英语语法 FAQ</a></li> + <li><a href="http://www.angryflower.com/bobsqu.gif">Bob 的撇号快速指南，你个笨蛋</a>（搞笑）</li> + <li><a href="http://www.amazon.com/Merriam-Websters-Concise-Dictionary-English-Usage/dp/B004L2KNI2">Merriam-Webster 的简明英语用法词典</a>（Amazon），虽是学术著作但很容易理解，基于实际例子并给出解释，对非英语国家的人很有帮助，特别是介词的使用方面。</li> + <li><a href="http://english.stackexchange.com/">StackExchange 网站的英语子站</a>，关于英语使用的问答网站。</li> +</ul> diff --git a/files/zh-cn/mdn/index.html b/files/zh-cn/mdn/index.html new file mode 100644 index 0000000000..f04f67d25f --- /dev/null +++ b/files/zh-cn/mdn/index.html @@ -0,0 +1,30 @@ +--- +title: MDN项目 +slug: MDN +tags: + - MDN + - 文档 +translation_of: MDN +--- +<div>{{MDNSidebar}}</div> + +<p><strong>Mozilla 开发者网络</strong>（MDN）是一个记录所有与开放 Web 技术、Mozilla 私有技术、Firefox OS 等相关的技术性文档的维基。我们欢迎各位志愿者的加入并帮助我们完善文档内容。您不必是程序员，也无需懂很多的技术。这里有许多不同的任务等待您去做，从简单的文章校对到错字修改、复杂的 API 文档编写等等。</p> + +<div class="summary"> +<p>MDN 的目标是为所有的开放 Web 技术、Mozilla 私有技术以及 Mozilla 私有项目提供技术文档，我们诚恳地期待您的加入！</p> +</div> + +<p>我们需要您的帮助！加入我们很简单，您不必担心权限问题，也不必担心犯错误。只要加入<a href="/zh-CN/docs/MDN/Community">MDN 社区</a>，我们就可以帮助您。下面的文章可以帮你快速入门。</p> + +<ul class="card-grid"> + <li><span><a href="/zh-CN/docs/MDN/Getting_started">初入 MDN</a></span> + + <p>刚来 MDN 吗？想帮助我们吗？看这篇！</p> + </li> + <li><span><a href="/zh-CN/docs/MDN/Contribute">为 MDN 做贡献</a></span> + <p>新手进阶必看。</p> + </li> + <li><span><a href="/zh-CN/docs/MDN/Promote">推广 MDN</a></span> + <p>如果您喜欢 MDN ，就帮我们推广它吧！</p> + </li> +</ul> diff --git a/files/zh-cn/mdn/kuma/index.html b/files/zh-cn/mdn/kuma/index.html new file mode 100644 index 0000000000..d506a15fbe --- /dev/null +++ b/files/zh-cn/mdn/kuma/index.html @@ -0,0 +1,24 @@ +--- +title: 'Kuma: MDN 的 wiki 平台' +slug: MDN/Kuma +tags: + - Kuma + - wiki + - 平台 +translation_of: MDN/Kuma +--- +<div>{{MDNSidebar}}{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p>Kuma 是驱动 MDN Web Docs 的 Django 程序。</p> + +<p>{{SubpagesWithSummaries}}</p> + +<h2 id="了解Kuma">了解Kuma</h2> + +<p>想要了解Kuma，你可以：</p> + +<ul> + <li>查看 <a href="https://github.com/mozilla/kuma">Github 上的 Kuma 项目</a>。</li> + <li>查看 <a href="https://github.com/mozilla/kuma/blob/master/CONTRIBUTING.md">贡献指南</a>。</li> + <li>如果需要的话，深入了解 <a href="http://kuma.readthedocs.org/en/latest/">Kuma 的完整文档</a>。</li> +</ul> diff --git a/files/zh-cn/mdn/mdn_product_advisory_board/index.html b/files/zh-cn/mdn/mdn_product_advisory_board/index.html new file mode 100644 index 0000000000..5407210821 --- /dev/null +++ b/files/zh-cn/mdn/mdn_product_advisory_board/index.html @@ -0,0 +1,22 @@ +--- +title: MDN 产品咨询委员会 +slug: MDN/MDN_Product_Advisory_Board +tags: + - MDN + - PAB + - 产品咨询委员会 +translation_of: MDN/MDN_Product_Advisory_Board +--- +<div>{{MDNSidebar}}</div><p>MDN Web Docs是基于wiki技术、也基于开源的Web开发文档平台，是Web开发人员的技术文档的可靠来源，允许几乎任何人编写和编辑内容。</p> + +<p>Mozilla对MDN产品咨询委员会的愿景是建立协作，帮助MDN社区将MDN作为最全面，完整和值得信赖的参考文献，将文档记录在现代浏览器和Web标准的最重要方面。</p> + +<p>产品咨询委员会将会从外部领导者提供建议，帮助MDN致力于提供HTML，CSS，JavaScript和Web API的中立、浏览器无关文档，并成为基于标准的Web开发的首要参考。</p> + +<h2 id="参见">参见</h2> + +<ul> + <li><a href="/zh-CN/docs/MDN/MDN_Product_Advisory_Board/Membership">Product Advisory Board Charter & Membership</a></li> + <li><a href="/en-US/docs/MDN/MDN_Product_Advisory_Board/Members">Product Advisory Board members</a></li> + <li><a href="https://www.dropbox.com/s/noj6vddhumhe9o0/MDN%20Product%20Advisory%20Board%20Interest%20Form.pdf?dl=0">Membership application</a></li> +</ul> diff --git a/files/zh-cn/mdn/mdn_product_advisory_board/members/index.html b/files/zh-cn/mdn/mdn_product_advisory_board/members/index.html new file mode 100644 index 0000000000..a1131e703f --- /dev/null +++ b/files/zh-cn/mdn/mdn_product_advisory_board/members/index.html @@ -0,0 +1,57 @@ +--- +title: Product Advisory Board Members +slug: MDN/MDN_Product_Advisory_Board/Members +tags: + - MDN + - PAB + - 产品顾问委员会 + - 会员 +translation_of: MDN/MDN_Product_Advisory_Board/Members +--- +<div>{{MDNSidebar}}</div><p>现任MDN产品咨询委员会成员:</p> + +<p><strong>Daniel Appelquist</strong><br> + Director of Developer Advocacy at Samsung Internet, Co-Chair of W3C's Technical Architecture Group</p> + +<p>Daniel Appelquist leads the Web Developer Advocacy team at Samsung Internet <<a href="https://samsunginter.net">https://samsunginter.net</a>>, Samsung's mobile and VR web browser. He has also been co-chair the <a href="https://w3.org/tag">W3C's Technical Architecture Group</a> since 2013. He has been working on the web for over 2 decades, first helping to create start-ups in the web publishing sphere and then (after moving to London from New York in '99) working on the convergence between web and mobile through many projects and initiatives. He has also led open standards strategy for the UK Government and remains a member of the <a href="https://www.gov.uk/government/groups/open-standards-board">UK Government Open Standards Board</a>. In between all this he's been an active community builder and event organizer.</p> + +<p><strong>Dominique Hazael-Massieux</strong><br> + W3C Web Technology Expert including <a href="https://www.w3.org/Telco/">Telecommunications Vertical champion</a>, <a href="https://www.w3.org/2011/04/webrtc/">Web Real-Time Communications Working Group</a>, <a href="https://www.w3.org/2009/dap/">Device and Sensors Working Group</a>.</p> + +<p>Dominique Hazael-Massieux is part of the W3C staff, where he leads W3C efforts in developer relationship. Dom has been working for W3C since 2000, and in addition to devrel, is currently involved in the standardization of WebRTC, device APIs and WebVR.</p> + +<p><strong>Meggin Kearney</strong><br> + Lead Technical Writer, Web Developer Relations at Google.</p> + +<p>Meggin leads the team that writes docs that help web developers succeed, including Web API documentation in MDN. A proud Chromium committer, she also co-built the Chrome extensions doc server. Meggin earned her undergraduate degree at the University of California, Berkeley. She lives in San Francisco, and is always looking for ways to support diversity and inclusion in the web developer community.</p> + +<p><strong>Patrick Kettner</strong><br> + Microsoft</p> + +<p>Patrick is a Program Manager at Microsoft, focusing on interoperability and new web technologies. A web developer by trade, he has committed in all major browsers and works every day to make web developers lives easier and more fun. Outside of work, he contributes to a number of open source projects, including maintaining Modernizr. He lives in Seattle with his wonderful partner Katrina, son Holden, and dog Baxter.</p> + +<p><strong>Chris Mills</strong><br> + Content Lead, MDN Web Docs at Mozilla</p> + +<p>Chris works at Mozilla as content lead for MDN, helping to pull together a strategy for what needs documenting in the short and long term. He also contributes a large number of beginner’s tutorials and reference articles covering DOM APIs, HTML and CSS features, web games, WebAssembly, and more.</p> + +<p class="m_2370283962379431175xmsonormal"><strong><span style="color: black; font-size: 12.0pt;">Erika Doyle Navara</span></strong><br> + <span style="color: black; font-size: 12.0pt;">Senior Dev Writer for Windows web documentation at Microsoft</span></p> + +<p class="m_2370283962379431175xmsonormal"><span style="color: black; font-size: 12.0pt;"> </span><span style="color: black; font-size: 12.0pt;">Erika Doyle Navara has been tinkering around the Microsoft browser engine room since 2006 when she started working on IE7. As a test engineer and technical writer, she helped organize Microsoft's contributions and browser data for the CSS 2.1, CSS3, SVG and HTML5 test suites at the W3C. She’s excited to continue championing cross-browser interoperability at MDN web docs.</span></p> + +<p><strong>Robert Nyman</strong><br> + Global Lead for Programs & Initiatives, Web Developer Relations, at Google.</p> + +<p>Robert Nyman is the Global Lead for Developer Feedback & Communities, Web Platform at Google. In his role, he works to make the web the best platform for developers. Prior to Google, Robert was a technical evangelist at Mozilla, focused on the Open Web and the company’s various products and initiatives. He lives in Stockholm, and has a passion for traveling and meeting people. He claims the title of “Most Well-Traveled Speaker” on Lanyrd, having presented in 42 countries.</p> + +<p><strong>Ali Spivak</strong></p> + +<p><strong>Mozilla开发商生态系统负责人，产品顾问委员会主席。</strong><br> + </p> + +<p>Ali是Mozilla开发商生态系统的负责人，之前在Mozilla负责开发者营销。 她管理MDN超过5年，致力于一个可互操作、跨平台互联网。 在Mozilla之前，她曾经在思科，Edmunds.com和许多创业公司管理Web产品。</p> + +<p><strong>Kadir Topal</strong></p> + +<p>Mozilla的MDN Web文档产品经理。</p> diff --git a/files/zh-cn/mdn/mdn_product_advisory_board/membership/index.html b/files/zh-cn/mdn/mdn_product_advisory_board/membership/index.html new file mode 100644 index 0000000000..e438d455b9 --- /dev/null +++ b/files/zh-cn/mdn/mdn_product_advisory_board/membership/index.html @@ -0,0 +1,127 @@ +--- +title: Product Advisory Board Charter & Membership +slug: MDN/MDN_Product_Advisory_Board/Membership +tags: + - MDN + - PAB + - 产品咨询委员会 + - 会员 + - 条款和条件 +translation_of: MDN/MDN_Product_Advisory_Board/Membership +--- +<div>{{MDNSidebar}}</div><h2 id="1.目的和目标">1.目的和目标</h2> + +<p>The primary purpose of the PAB is to provide advice, input, and feedback on content strategy, content prioritization, strategic direction, and platform/site features to MDN’s Product Manager and Content Lead. Mozilla will consider input and advice from the PAB; however PAB input and recommendations are non-binding. The primary objectives of the PAB are:</p> + +<ul> + <li>Provide feedback into content strategy and prioritization of standards documentation</li> + <li>Help define product strategy, roadmap, and priorities including: + <ul> + <li>Suggest and comment on Objectives and Key Results (OKRs)
</li> + <li>Suggest and comment on yearly and quarterly content roadmaps</li> + </ul> + </li> + <li>Make organizational and individual commitments to contribute to MDN based on the defined strategies, roadmaps and priorities</li> + <li>Represent and promote user requirements, ensuring that MDN continues to evolve and meet users’ needs and challenges</li> + <li>Suggest and give feedback on new opportunities</li> + <li>Provide feedback on recruiting and retaining contributors (both corporate and individual)</li> + <li>Share experience and best practices </li> +</ul> + +<h2 id="2.会员当选和终止">2.会员当选和终止</h2> + +<p>a. The PAB shall consist of 10 to 12 Members (as defined in the MDN Product Advisory Board Agreement and including those individuals representing a Member organization), to be selected by Mozilla.</p> + +<p>b. There are two types of membership: organizational and individual. Organizations who meet the membership criteria and are accepted as member organizations may nominate up to 2 individuals to serve as their representatives (“Member Representatives” as defined in the MDN Product Advisory Board Agreement) on the PAB.</p> + +<p>c. Organizations/individuals who wish to become PAB members must submit a MDN Product Advisory Board Interest Form. Membership will be subject to review and approval by Mozilla, and notification will be sent to the applicant within 30 days of application.</p> + +<p>d. Membership start dates will be based upon review meeting schedules; any new Members will begin their term on the PAB at the next scheduled review meeting.</p> + +<p>e. Members of the PAB will serve terms of 1 year, renewed automatically for up to 3 years (unless terminated by either party). At the end of the 1-year term, the PAB Member and Mozilla will review membership and decide whether to continue Member participation.</p> + +<p>f. Members may resign in writing, via email to the PAB mailing list. Member organizations can nominate replacements for resigned members before the start of the next review meeting.</p> + +<p>g. Mozilla may terminate a Member in the case of violation of the MDN Advisory Board Agreement, violation of the MDN PAB Code of Conduct, violation of the Antitrust Policy, or if the Member fails to participate in two consecutive review meetings without notice. At that time, a notice will be sent to the principal contact stating that they have been removed as a Member.</p> + +<h2 id="3.PAB_会员资格">3.PAB 会员资格</h2> + +<p>a. PAB Members have in-depth industry knowledge and expertise. Members will be knowledgeable about web standards, with the ability and experience to align MDN’s overall strategic goals and content plans with evolution of web standards, industry direction, and the needs of developers using MDN’s documentation.</p> + +<p>b. Membership in the PAB is limited to organizations and individuals who make significant contributions to MDN and/or the advancement, development, and implementation of web standards.</p> + +<p>c. Member organizations must play a significant role in the creation, implementation, or adoption of Web standards and guidelines. It is also preferred that PAB Member organizations be members of an established Web standards group, such as W3C. Member organizations may nominate up to 2 individual representatives to serve on the board.</p> + +<p>d. Individual Members of the PAB must have at least one of the following qualifications:</p> + +<ul> + <li>Plays a significant role in the creation, implementation, or adoption of Web standards;</li> + <li>Participates in a Web standards group dedicated to the development of specifications for features implemented in a Web browser or used in Web content that is sent to browsers. Participation in W3C or a similar standards group is preferred but not required. Individual Members may also meet this qualification by having served on a standards working group or as an invited expert on an established Web standards working group;</li> + <li>Is a member of a Web-focused Developer Relations team;</li> + <li>Works as part of a group doing technical documentation of Web standards; or</li> + <li>Makes significant, sustained contributions to MDN Web standards documentation as a volunteer.</li> +</ul> + +<h2 id="4._会员责任和承诺。">4. 会员责任和承诺。</h2> + +<p>a. Members are expected to provide feedback and responses in a timely manner, and attend a minimum number of review meetings. Participation is welcome from all over the world. Members’ expectations include:</p> + +<p>Provide feedback on scheduling annual and quarterly meetings;</p> + +<ul> + <li>Attend annual meeting;</li> + <li>Attend at least 2 quarterly reviews per year;</li> + <li>Review proposals and provide feedback;</li> + <li>Join the PAB mailing list;</li> + <li>and Agree not to promote a specific corporate or individual agenda, particularly in the creation or editing of content on MDN.</li> +</ul> + +<p>b. Members may be required to provide personal information and material (bios, etc.) for analyst, press, and/or trade publications and press releases.</p> + +<p>c. All Members must sign the MDN Product Advisory Board Agreement and agree to the MDN PAB Code of Conduct and Antitrust Policy.</p> + +<h2 id="5._MDN_PAB_会员权利。">5. MDN PAB 会员权利。</h2> + +<p>It is anticipated that PAB membership will have the following benefits:</p> + +<ul> + <li>Impact content strategy and priorities for MDN;</li> + <li>Influence the strategic direction of MDN; Have advance knowledge of MDN plans and development;</li> + <li>Make suggestions for features and platform improvements to grow MDN audience and contribution; and</li> + <li>Provide feedback and technical reviews of content.</li> +</ul> + +<h2 id="6._常规和指定会议。">6. 常规和指定会议。</h2> + +<p>a. Members will be invited to the following meetings:</p> + +<ul> + <li>Annual Product Strategy review meetings to take place between October and December of each calendar year;</li> + <li>Quarterly content strategy and prioritization review meetings (“Quarterly Reviews); and</li> + <li>Ad-hoc product review/check-in meetings, which can be initiated by Mozilla or any Member as needed (“Ad Hoc Meetings”).</li> +</ul> + +<p>b. Annual Product Strategy review meetings will review the previous year’s progress and make recommendations for MDN’s strategy and objectives for the following year.</p> + +<p>c. Annual Product Strategy review meetings can take place in Mozilla headquarters or worldwide office, the offices of a Member, or external locations, as determined by vote of the PAB. Virtual attendance will be accommodated for Members who are unable to attend in person.</p> + +<p>d. Quarterly Reviews and Ad-Hoc Meetings will primarily be held via video/conference call, although in-person attendance will be possible at the discretion of Members.</p> + +<p>e. Ad-Hoc Meeting dates will depend upon the work in development. Review points will have a specific emphasis such as coordination around product release dates and major features or new specs and standards reaching broad release that require more in-depth coordination and planning beyond the Quarterly Review.</p> + +<h2 id="7._时间承诺和成本。">7. 时间承诺和成本。</h2> + +<p>a. Members are asked to make a commitment to the PAB for at least 12 months.</p> + +<p>b. Members are asked to commit the time to prepare for, attend (sometimes in person), and participate in regularly scheduled and ad-hoc PAB meetings.</p> + +<p>c. Costs for participant travel and living expenses or other involvement are to be paid by the individual board member or the sponsoring organization.</p> + +<p> </p> + +<h2 id="参见">参见</h2> + +<ul> + <li><a href="/en-US/docs/MDN/MDN_Product_Advisory_Board/Members">Product Advisory Board members</a></li> + <li>Membership application</li> +</ul> diff --git a/files/zh-cn/mdn/structures/compatibility_tables/index.html b/files/zh-cn/mdn/structures/compatibility_tables/index.html new file mode 100644 index 0000000000..fdcf1d1408 --- /dev/null +++ b/files/zh-cn/mdn/structures/compatibility_tables/index.html @@ -0,0 +1,500 @@ +--- +title: 兼容性表格 +slug: MDN/Structures/Compatibility_tables +tags: + - MDN Meta + - 兼容性表格 + - 指南 + - 浏览器兼容性 +translation_of: MDN/Structures/Compatibility_tables +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p class="summary"><span class="seoSummary">MDN 为我们的开放网页文档提供了兼容性表格的标准格式; 它是对比所有浏览器之间，包含 DOM，HTML，CSS，JavaScript，SVG 等技术的文档。</span>本文将介绍如何使用我们的功能将兼容性数据添加到MDN页面。</p> + +<div class="warning syntaxbox"> +<p><strong>重要</strong>: <strong><em>数据的生成方式已经发生了变更</em></strong>。过去，我们的表格直接嵌入在页面中，而且数据是手动填写的。这样效率很低，难以维护，而且使得数据不够灵活，不便更新。所以我们正在把我们的兼容性表格迁移到一个数据 repo 中（<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>）并且改为使用程序化的方式生成它。<br> + <br> + 本指南中，我们撰写了关于如何向 MDN 添加新的兼容性数据的文档，但是我们仍然保留了旧的方法来保证旧文档的兼容性表格可用：正如你所见，手动输入的表格依然存在于 MDN 上。如果你有必要使用旧方法的话，可以参考这篇文章：<a href="/en-US/docs/MDN/Contribute/Structures/Old_compatibility_tables">Old compatibility tables</a>。</p> +</div> + +<div class="note"> +<p><strong>注意：</strong>如果您需要本指南任何步骤的帮助，欢迎您在<a href="https://discourse.mozilla-community.org/c/mdn">MDN论坛</a>上与我们联系。</p> +</div> + +<h2 id="如何访问_data_repo">如何访问 data repo</h2> + +<p>数据存储在一个 GitHub repo 中，到 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 查看。想要访问它，你必须拥有一个 GitHub 账号，fork浏览器兼容数据仓库到你自己的账户，然后克隆你的fork到你的本地机器。</p> + +<h2 id="选择要贡献的数据类型">选择要贡献的数据类型</h2> + +<p>首先，确定一下你想为何种 Web 技术贡献兼容性数据。可以是一个 HTML 元素、CSS 属性、JS 语法或者 JS API 接口。我们鼓励您贡献 API 接口的数据, 因为已经有人在贡献 HTML、JS 和 CSS 的数据了。你可以在表格 <a href="https://docs.google.com/spreadsheets/d/1ivgyPBr9Lj3Wvj5kyndT1rgGbX-pGggrxuMtrgcOmjM/edit#gid=926663640">Browser Compat Data migration</a> 中查看各个需要添加兼容性数据的 Web 技术的数据状态。</p> + +<p>电子表格的使用步骤如下:</p> + +<ol> + <li>直接挑选一个还未开始或者还未完成数据录入的功能点，在“Who”一栏中填入你的名字, 最好能够和你的MDN用户名保持一致，以便我们在需要联系你的时候能够查找到你的邮件地址.</li> + <li>如果该功能点不在表格上，那么你可以参照现有的格式在合适的位置上加一行。注意要使用同等的粒度（例如，HTML以标签元素为单位、CSS以选择器或者属性值为单位、JS以对象为单位、JS API以特定的接口为单位）</li> + <li>当你已经开始录入数据的时候，把对应状态栏的下拉选项置于“In progress”（进行中）状态。</li> + <li>一旦添加完数据，并且向主仓库提交了一个拉取请求（pull request），那么把对应状态栏的下拉选项置于“PR done”状态。</li> + <li>当你的数据已经成功合并到主分支，或者已经添加到npm包里面的时候，请尽量更新对应的状态栏到相应的状态。</li> + <li>当你更新了你的功能文档页面，并且使用新的脚步命令使其可以在每一个页面都可以动态的生成合适的数据表格的时候，你就需要在电子表格中修改对应功能的状态为“Article updated”（文章已更新）。这意味着你已经完成了这一功能的所有数据录入工作。</li> +</ol> + +<h2 id="准备添加数据">准备添加数据</h2> + +<p>在添加新数据之前，你应该保证您的 fork 是主 repo 的最新版本（它们应包含相同的内容）。在您的 fork 里添加一个包含您的更改的分支，然后把它pull到您本地的仓库，这样你就可以开始贡献了：</p> + +<p>下面是更新您的分支的一个简单方法：</p> + +<h3 id="将浏览器兼容信息的主_repo_添加到远端服务器列表中">将浏览器兼容信息的主 repo 添加到远端服务器列表中</h3> + +<p>在您的终端或命令行中进入您的fork的本地仓库，用以下命令将（服务器上的）主 repo 添加到远端服务器列表中（您只需执行以下命令一次）：</p> + +<pre class="brush: bash notranslate">git remote add upstream https://github.com/mdn/browser-compat-data.git</pre> + +<p><span id="result_box" lang="zh-CN">如果您不确定自己是否做到了这一点</span>， 您可以检查您仓库已经在用的远端服务器列表：</p> + +<pre class="brush: bash notranslate">git remote -v</pre> + +<h3 id="让您的分支与服务器上的内容同步">让您的分支与服务器上的内容同步</h3> + +<p><span id="result_box" lang="zh-CN"><span>现在，只要您想更新您</span></span><span lang="zh-CN"><span>的分支，</span></span><span id="result_box" lang="zh-CN"><span>您</span></span><span lang="zh-CN"><span>就可以这样做：</span></span></p> + +<ol> + <li> + <p>确定您已切换到在主分支：</p> + + <pre class="brush: bash notranslate">git checkout master</pre> + </li> + <li> + <p>使用以下命令来获取服务器上最新的内容：</p> + + <pre class="brush: bash notranslate">git fetch upstream</pre> + </li> + <li> + <p>用rebase将主仓库的内容合并到您的master分支中：</p> + + <pre class="brush: bash notranslate">git rebase upstream/master</pre> + </li> + <li> + <p>将来自主 repo 的更新 push 回您自己的 repo 中：</p> + + <pre class="brush: bash notranslate">git push -f</pre> + </li> +</ol> + +<h3 id="创建您用来工作的分支：">创建您用来工作的分支：</h3> + +<p>接下来，打开您在服务器上的fork（它的地址可能是<code>https://github.com/<em>your-username</em>/browser-compat-data</code>）并且创建一个新分支来存储您的改动。步骤如下：</p> + +<ol> + <li>点击"Branch: Master"按钮；</li> + <li>在"Find or create a branch..."文本输入框中输入一个新的分支名；</li> + <li>点击下方出现的"Create branch <em>name-of-branch</em> from Master"按钮。</li> +</ol> + +<p>举个例子，如果您想补充WebVR API的信息，您可以创建一个名为“webvr”的分支.</p> + +<h3 id="切换到新分支">切换到新分支</h3> + +<p>此时，回到您的终端或命令行，用以下命令将您的新分支同步到您本地的fork中：</p> + +<pre class="brush: bash notranslate">git pull</pre> + +<p>现在用以下命令切换到您的新分支</p> + +<pre class="brush: bash notranslate">git checkout <em>-b name-of-branch</em></pre> + +<p>现在您可以开始进行您对浏览器兼容信息的补充和修改了。</p> + +<h2 id="添加数据">添加数据</h2> + +<p>为添加新的数据，您需要新建文件以存储您的兼容性数据。对于不同技术的数据，您需要创建的文件也有所不同：</p> + +<ul> + <li><a href="/zh-CN/docs/Web/HTML/">HTML</a>：被包含在 <a href="https://github.com/mdn/browser-compat-data/tree/master/html/elements">browser-compat-data/html/elements</a> 中，每个HTML元素对应一个文件。文件需要以元素的小写的名称命名，例如<code>div.json</code>。</li> + <li><a href="/zh-CN/docs/CSS">CSS</a>：每个CSS属性或选择器对应一个文件。它们被包含在对应的目录中（请参考 <a href="https://github.com/mdn/browser-compat-data/tree/master/css">browser-compat-data/css</a>）。文件需要以CSS特性的小写的名称命名，如<code>background-color.json</code>或者<code>hover.json</code>。</li> + <li><a href="/zh-CN/docs/JavaScript">JS</a>：被包含在 <a href="https://github.com/mdn/browser-compat-data/tree/master/javascript/builtins">browser-compat-data/javascript/builtins</a> 中，每个JavaScript对象对应一个文件。文件要以JavaScript对象的准确名称命名，保留其大小写，如 <code>Date.json</code> 或 <code>InternalError.json</code>。</li> + <li><a href="/zh-CN/docs/Web/API">API</a>：API中的每个接口对应一个文件。它们在 <a href="https://github.com/mdn/browser-compat-data/tree/master/api">browser-compat-data/api</a> 中。每个文件要以接口的准确名称命名，保留其大小写，例如WebVR API的文件为<code>VRDisplay.json</code>，<code>VRDisplayCapabilities.json</code>，等等。</li> +</ul> + +<div class="note"> +<p><strong>注意：您会留意到，该仓库还包含了<a href="/en-US/Add-ons/WebExtensions">浏览器拓展</a>和</strong><a href="/en-US/docs/Web/HTTP">HTTP</a><strong>的数据。</strong>These data sets are basically finished as they stand, but more features may need to be added in the future.</p> +</div> + +<p>你创建的每个文件都需要跟随定义在我们repo的schema中的这些模板的规定。你可以参考<a href="https://github.com/mdn/browser-compat-data/blob/master/compat-data-schema.md">详细的模板描述</a>。</p> + +<h3 id="基本的兼容性数据的结构">基本的兼容性数据的结构</h3> + +<p>让我们来看一下如下例子。一个CSS属性JSON文件需要以下的结构：</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "border-width": { + "__compat": { + ... + } + } + } + } +}</pre> + +<p>首先有一个<code>css</code>对象，其中包含了一个<code>properties</code>对象。每个您要设定兼容性数据的特性都对应一个<code>properties</code>对象中的成员。而每一个这些成员都有一个<code>__compat</code>成员，<code>__compat</code>成员中则是实际的数据。</p> + +<p>以上的数据能在 <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">browser-width.json</a> 文件中找到——可将这与 <a href="/zh-CN/docs/Web/CSS/border-width#Browser_compatibility">MDN上渲染后的浏览器兼容性</a> 相比较。</p> + +<p>对于其他类型特性，写法是类似的，但对象的名称不同：</p> + +<ul> + <li>对于CSS选择器，它与CSS属性的写法基本相同，不同之处在于顶级对象结构是是 <code>css.selectors</code> 而不是<code>css.properties</code>. 请以 <a href="https://github.com/mdn/browser-compat-data/blob/master/css/selectors/cue.json">cue.json</a> 作为参考示例。</li> + <li>对于HTML数据，它的写法基本相同，不同之处在于顶级对象结构是<code>html.elements</code>。请以<code>article.json</code>作为参考示例。</li> + <li>JS内置对象对应的顶级结构是<code>javascript.builtins</code>；请以 <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Array.json">Array.json</a> 作为参考示例。</li> +</ul> + +<div> +<p>在一个HTML、CSS和JS页面中，通常您只需要有一个特性。API则有些不同——它们总是包含多个子特性 （参见下边的 {{anch("Sub-features")}}）。</p> + +<h3 id="一个特性中的基础结构">一个特性中的基础结构</h3> + +<p>在一个特性的<code>__compat</code>成员中，您需要包含以下成员：</p> + +<ul> + <li><code>mdn_url</code>: MDN上这个特性的页面的URL。注意，这个URL不可以带上本地化文件夹名称，例如：是 <code>/docs/...</code> 而不是 <code>/docs/en-US/...</code> （或者其他）。本地化文件夹名称会在页面加载时被添加。</li> + <li><code>support</code>: 所有不同浏览器对这个特性的浏览器支持的信息。</li> + <li><code>status</code>: Contains members reporting the standards track status of this feature.</li> +</ul> + +<p>浏览器成员名称在架构里被定义（参见 <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#browser-identifiers">浏览器标识符</a>）。你应该使用现有定义的标识符的完整列表。如果你希望添加其他浏览器，请先联系我们，因为这可能会产生广泛的影响，不应该在未经认真考虑就这么做。</p> + +<p>在一个基本的浏览器兼容数据文件中，你只需要在浏览器标识符成员仲包含"version_added" （以下我们会说到{{anch("Advanced cases")}}）。其他你可能使用的值还包括： </p> + +<ul> + <li>一个版本号：如果你知道一个浏览器开始支持这个特性的准确版本，用一个字符串表述版本号，例如“47”。 </li> + <li><code>true</code>: 如果一个浏览器支持这个特性，但你不知道准确的版本号，取值用<code>true</code>。</li> + <li><code>false</code>: 如果一个浏览器支持这个特性，取值用 <code>false</code>。</li> + <li><code>null</code>: 如果一个浏览器支持这个特性，取值用 <code>null</code>。</li> +</ul> + +<p>在 <code>status</code> 成员中，包含三个子成员：</p> + +<ul> + <li> <code>"experimental"</code>: 如果这个特性是<a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">试验性</a>的，取值为 <code>true</code> ，否则为 <code>false</code> 。</li> + <li><code>"standard_track"</code>: 如果这个特性是个在某些规范里的标准的属性（最常见的是W3C/WHATWG，但有其他规范如Khronos或TC39等），取值为<code>true</code> ，否则为 <code>false</code> 。</li> + <li><code>"deprecated"</code>: 如果这个特性已经<a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">过时</a>，取值为<code>true</code> ，否则为 <code>false</code> 。</li> +</ul> + +<p>作为例子，以下是 <a href="/en-US/docs/Web/CSS/border-width#Browser_compatibility">border-width</a> 特性的数据 (参见 <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a>) ：</p> + +<pre class="brush: json notranslate">"__compat": { + "mdn_url": "https://developer.mozilla.org/docs/Web/CSS/border-width", + "support": { + "chrome": { + "version_added": "1" + }, + "webview_android": { + "version_added": "2" + }, + "edge": { + "version_added": true + }, + "edge_mobile": { + "version_added": true + }, + "firefox": { + "version_added": "1" + }, + "firefox_android": { + "version_added": "1" + }, + "ie": { + "version_added": "4" + }, + "ie_mobile": { + "version_added": "6" + }, + "opera": { + "version_added": "3.5" + }, + "opera_android": { + "version_added": "11" + }, + "safari": { + "version_added": "1" + }, + "safari_ios": { + "version_added": "3" + } + }, + "status": { + "experimental": false, + "standard_track": true, + "deprecated": false + } +}</pre> + +<h4 id="添加描述说明">添加描述说明</h4> + +<p>There is a fourth, optional, member that can go inside the __compat member — <code>description</code>. This can be used to include a human-readable description of the feature. You should only include this if it is hard to see what the feature is from glancing at the data. For example, it might not be that obvious what a constructor is from looking at the data structure, so you can include a description like so:</p> + +<pre class="brush: json notranslate">{ + "api": { + "AbortController": { + "__compat": { + ... + }, + "AbortController": { + "__compat": { + "mdn_url": "https://developer.mozilla.org/docs/Web/API/AbortController/AbortController", + "description": "<code>AbortController()</code> constructor", + "support": { + ... + } + } + } + + ... etc. + } + } +}</pre> + +<h3 id="子特性">子特性</h3> + +<p>In a page where the compat table has more than one row, you'll need multiple subfeatures inside each feature to define the information for each row. This can happen, for example, when you've got the basic support for a feature stored in one row, but then the feature also has a new property or value type that was addded much later in the specification's life and is only supported in a couple of browsers.</p> + +<p>As an example, see the <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/background-color.json">compat data</a> and <a href="/en-US/docs/Web/CSS/background-color">corresponding MDN page</a> for the <code>background-color</code> property. The basic support exists inside the <code>__compat</code> object as explained above, then you have an additional row for browsers' support for "alpha channel for hex values", which contains its own <code>__compat</code> object.</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "background-color": { + "__compat": { + ... + }, + "alpha_ch_for_hex": { + "__compat": { + ... + }, + } + } + } + } +}</pre> + +<p>For an API, you've got the top two levels defined as <code>api.<em>name-of-the-interface</em></code>, then a top-level <code>__compat</code> section to define the overall browser compatibility of the interface, then a sub-feature for each of the methods, properties, and constructors contained inside the interface. The basic structure looks like this:</p> + +<pre class="brush: json notranslate">{ + "api": { + "VRDisplay": { + "__compat": { + ... + }, + "cancelAnimationFrame": { + "__compat": { + ... + } + }, + "capabilities": { + "__compat": { + ... + } + }, + + ... etc. + + } + } +}</pre> + +<p>See <a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a> for a full example.</p> +</div> + +<h2 id="添加数据：高级场景">添加数据：高级场景</h2> + +<p>There are some advanced features that you'll want to include in browser compat data. The aim of this section is to list the most common ones, providing an example of each to show how you can implement them in your own compat data.</p> + +<h3 id="Including_a_footnote">Including a footnote</h3> + +<p>Often compat tables will include footnotes related to certain entries that explain useful details or strange behavior that developers will find useful. As an example, the Chrome Android entry for {{domxref("VRDisplay.capabilities")}} (see also <a href="https://github.com/mdn/browser-compat-data/blob/master/api/VRDisplay.json">VRDisplay.json</a>) (at the time of writing) had a footnote "<span class="pl-s">Currently supported only by Google Daydream." To include this in the capabilities data, we added a "notes" submember inside the relevant "chrome_android" submember; it would look like this:</span></p> + +<pre class="brush: json notranslate">"chrome_android": { + "version_added": true, + "notes": "Currently supported only by Google Daydream." +}</pre> + +<h3 id="包含浏览器厂商的前缀">包含浏览器厂商的前缀</h3> + +<p>If a feature is supported behind a vendor prefix in one or more browsers, you'll want to make that clear in the browser compat data. 例如您可能有一个特性在Firefox浏览器中要用<code>-moz-</code>前缀才被支持，要在兼容性数据中指明这一点，您需在对应的"firefox"子成员中增加一个"prefix"子成员。它看起来是这样的：</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": true, + "prefix": "-moz-" +}</pre> + +<h3 id="Including_browser_preferences_or_flags">Including browser preferences or flags</h3> + +<p>Some features may be supported in a browser, but they are experimental and turned off by default. If a user wants to play with this feature they need to turn it on using a preference/flag.</p> + +<p>To represent this in the compat data, you need to add the "flags" submember inside the relevant browser identifier submember. The value of "flags" is an array of objects each of which contains of three members:</p> + +<ul> + <li>"type": The type of flag or pref this is. The most common value is "preference", which is set inside the browser (for example, using <code>about:config</code> in Firefox, or <code>chrome://flags</code> in Chrome), but you might also sometimes use a value of <span class="pl-s"><span class="pl-pds">"</span>compile_flag<span class="pl-pds">", which is a preference set when the browser build is compiled.</span></span></li> + <li>"name": This is a string representing the name of the preference that needs to have a value set on it. For example, "Enable Experimental Web Platform Features" is a preference that exists in Chrome, found in <code>chrome://flags</code>.</li> + <li>"value_to_set": This is a string representing the value that needs to be set on the preference, for example "true".</li> +</ul> + +<p>So to add a preference/flag to the Chrome support for a feature, you'd do something like this:</p> + +<pre class="brush: json notranslate">"chrome": { + "version_added": "50", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] +},</pre> + +<p>If a feature is behind two or more flags, you can add additional objects to the "flags" array, like in this case, for example:</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": "57", + "flags": [ + { + "type": "preference", + "name": "dom.streams.enabled", + "value_to_set": "true" + }, + { + "type": "preference", + "name": "javascript.options.streams", + "value_to_set": "true" + } + ] +},</pre> + +<h3 id="包含特性不再被支持的版本">包含特性不再被支持的版本</h3> + +<p>有时一个特性在浏览器的某个版本被加进去，然后又因为该特性过时而被被移除掉。这可以在"version_removed"子成员中体现。该子成员是一个代表特性被移除的版本的字符串。例如：</p> + +<pre class="brush: json notranslate">"firefox": { + "version_added": "35", + "version_removed": "47", +},</pre> + +<h3 id="Including_multiple_support_points_for_the_same_browser_entry">Including multiple support points for the same browser entry</h3> + +<p>Sometimes you'll want to add multiple support data points for the same browser inside the same feature.</p> + +<p>As an example, the {{cssxref("text-align-last")}} property (see also <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/text-align-last.json">text-align-last.json</a>) was added to Chrome in version 35, supported behind a pref.</p> + +<p>The support mentioned above was then removed in version 47; also in version 47, support was added for <code>text-align-last</code> enabled by default.</p> + +<p>To include both of these data points, you can make the value of the "chrome" submember an array containing two support information objects, rather than just a single support information object:</p> + +<pre class="brush: json notranslate">"chrome": [ + { + "version_added": "47" + }, + { + "version_added": "35", + "version_removed": "47", + "flags": [ + { + "type": "preference", + "name": "Enable Experimental Web Platform Features", + "value_to_set": "true" + } + ] + } +],</pre> + +<div class="note"> +<p><strong>Note</strong>: You should put the most current or important support point first in the array — this makes the data easier to read for people who just want to scan it for the latest info.</p> +</div> + +<h3 id="包含一个可选的名字">包含一个可选的名字</h3> + +<p>Occasionally browsers will support a feature under a different name to the name defined in its specification. This might be for example because a browser added experimental support for a feature early, and then the name changed before the spec stabilized.</p> + +<p>To include such a case in the browser compat data, you can include a support information point that specifies the alternative name inside an "alternative_name" member.</p> + +<div class="note"> +<p><strong>Note</strong>: The alternative name might not be an exact alias — it might have differing behaviour to the standard version.</p> +</div> + +<p>Let's look at an example. The {{cssxref("border-top-right-radius")}} property (see also <a href="https://github.com/mdn/browser-compat-data/blob/2a0cc3f6bb17aa4345441bed47a059dffd847793/css/properties/border-top-right-radius.json">border-top-right-radius.json</a>) was supported in Firefox:</p> + +<ul> + <li>From version 4 onwards with the standard name <code>border-top-right-radius</code>.</li> + <li>From version 49 onwards with a <code>-webkit-</code> prefix, for browser compatibility purposes.</li> + <li>From version 1 onwards with the alternative name <code>-moz-border-radius-topright</code>. Support for this alias was removed in version 12.</li> +</ul> + +<p>To represent this in the data, we used the following JSON:</p> + +<pre class="brush: json notranslate">"firefox": [ + { + "version_added": "4", + "notes": "Prior to Firefox 50.0, border styles of rounded corners were always rendered as if <code>border-style</code> was solid. This has been fixed in Firefox 50.0." + }, + { + "prefix": "-webkit-", + "version_added": "49", + "notes": "From Firefox 44 to 48, the <code>-webkit-</code> prefix was available with the <code>layout.css.prefixes.webkit</code> preference. Starting with Firefox 49, the preference defaults to <code>true</code>." + }, + { + "alternative_name": "-moz-border-radius-topright", + "version_added": "1", + "version_removed": "12" + } +],</pre> + +<h2 id="将变更推送回主仓库">将变更推送回主仓库</h2> + +<p>在您添加完您的兼容性数据之后，您应该先用以下命令测试一下：</p> + +<ul> + <li><code>npm run lint</code> — 测试所有兼容性数据以确保JSON的格式和书写风格正确，例如正确的缩进和没有遗漏逗号等等。该命令会打印出一个很长的文件名和测试结果的列表；if an error is found, the linter will throw an error on the file it is found in, giving you useful debugging info like line number, error message, etc.</li> + <li><code>npm run show-errors</code> — validates the JSON against the data schema, and highlights errors such as invalid browser version numbers being used.</li> + <li><code>npm run render 'dotted.path.to.feature'</code> — allows you to preview the markup for the compat table for a data file in the repo. As an example, <code>npm run render 'css.properties.background'</code> shows the table markup for the {{cssxref("background")}} property.</li> +</ul> + +<p>If it is looking OK, you then need to commit it and push it back up to your remote fork on GitHub. You can do this easily with terminal commands like this:</p> + +<pre class="brush: bash notranslate">git add . +git commit -m 'adding compat data for name-of-feature' +git push</pre> + +<p>Now go to your remote fork (i.e. <code>https://github.com/<em>your-username</em>/browser-compat-data</code>) and you should see information about your push at the top of the files list (under "Your recently pushed branches"). You can create a pull request (starting the process of pushing this to the main repo) by pressing the "Compare & pull request" button, then following the simple prompts on the subsequent screen.</p> + +<p>At this point, you just need to wait. A reviewer will review your pull request, and merge it with the main repo, OR request that you make changes. If changes are needed, make the changes and submit again until the PR is accepted.</p> + +<h2 id="将数据插入MDN页">将数据插入MDN页</h2> + +<p>Once your new data has been included in the main repo, you can start dynamically generating browser compat tables based on that data on MDN pages using the \{{Compat}} macro. This takes a single parameter, the dot notation required to walk down the JSON data and find the object representing the feature you want to generate the compat table for.</p> + +<p>Above the macro call, to help other contributors finding their way, you should add a hidden text that is only visible in MDN contributors in edit mode:</p> + +<pre class="brush: html notranslate"><div class="hidden"> +<p>此页面上的兼容性表格由结构化数据生成。如果你想贡献数据，可以看看 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>并向我们发送 pull request.</p> +</div></pre> + +<p>As an example, on the {{httpheader("Accept-Charset")}} HTTP header page, the macro call looks like this: \{{Compat("http.headers.Accept-Charset")}}. If you look at the <a href="https://github.com/mdn/browser-compat-data/blob/master/http/headers/accept-charset.json">accept-charset.json</a> file in the repo, you'll see how this is reflected in the JSON data.</p> + +<p>As another example, The compat table for the {{domxref("VRDisplay.capabilities")}} property is generated using \{{Compat("api.VRDisplay.capabilities")}}. The macro call generates the following table (and corresponding set of notes):</p> + +<hr> +<div class="hidden"> +<p>此页面上的兼容性表格由结构化数据生成。 如果您想贡献数据，可以看看 <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> 并向我们发送 pull request。</p> +</div> + +<p>{{Compat("api.VRDisplay.capabilities")}}</p> + +<div class="note"> +<p><strong>注意</strong>: 文件名通常与给予JSON结构内的接口的标签相匹配，但事实并非总是如此。 当宏调用生成表时，他们遍历所有文件，直到找到相关的JSON使用，所以文件名不是关键。 说到这一点，你应该始终尽可能直观地命名它们。</p> +</div> diff --git a/files/zh-cn/mdn/structures/index.html b/files/zh-cn/mdn/structures/index.html new file mode 100644 index 0000000000..aee298c70e --- /dev/null +++ b/files/zh-cn/mdn/structures/index.html @@ -0,0 +1,18 @@ +--- +title: 文档结构 +slug: MDN/Structures +tags: + - Landing + - MDN Meta + - NeedsTranslation + - Structures + - TopicStub +translation_of: MDN/Structures +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/zh-CN/docs/MDN")}}</div> + +<p>在MDN里有各式各样的重复使用的文档结构，来使MDN文章中的内容有一致性的表现。这里的文章描述了这些结构。因此作为一名MDN的作者，你可以确认、应用并修改成适合于你写、编辑或翻译的文档。</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/zh-cn/mdn/structures/live_samples/index.html b/files/zh-cn/mdn/structures/live_samples/index.html new file mode 100644 index 0000000000..0b50a1b8f7 --- /dev/null +++ b/files/zh-cn/mdn/structures/live_samples/index.html @@ -0,0 +1,213 @@ +--- +title: 运行实例 +slug: MDN/Structures/Live_samples +tags: + - Guide + - Intermediate + - MDN Meta + - NeedsTranslation + - Structures + - TopicStub +translation_of: MDN/Structures/Live_samples +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">MDN 支持将文章中的示例代码转化为运行实例。运行实例可以包括 HTML、CSS、 JavaScript 的任意组合。</span>注意，“运行”的实例是<em> 非交互性 </em>的。它们仅仅由代码示例生成，只是用来展示示例的输出效果。本文在JavaScript语法的基础上说明了该系统的集体使用。</p> + +<h2 id="运行实例系统如何工作">运行实例系统如何工作</h2> + +<p>运行实例系统将所有代码整合为一个集合，再将这个集合融合到一个 HTML 文件中，然后在 内联框架{{HTMLElement("iframe")}} 中渲染这个文件。一个运行实例由两个部分构成：</p> + +<ul> + <li>一个代码块组成的集合</li> + <li>一个调用（创建的框架或链接）该代码块结果的宏</li> +</ul> + +<p>一个代码块的集合，在此上下文中，以行级或块级元素（类似 {{HTMLElement("div")}} ）的 id作为标识。</p> + +<ul> + <li>如果这个 id 属于一个块级元素，该集合将包含该块元素包含范围内的所有代码。</li> + <li>如果这个编号属于一个行级元素，该集合将包含本行级元素之后到下个同级行级元素之前的所有代码。请注意，子元素下的代码块也会被包含，如果不希望这样的效果，可以使用块级元素的id。</li> +</ul> + +<p>宏使用一个特殊的 URL 来取得一个分组中的代码示例：<code>http://<em>url-of-page</em>$samples/<em>group-id</em></code>。 <code>group-id</code> 指代码所在行级或者块级元素的id。用来展示运行结果的框架(或页面)会运行在沙盒中，在安全条件下实现任何想在网络上实现的功能。当然，在实践中，代码需要针对于包含它的页面，否则会被社区编辑移除。</p> + +<div class="note"> +<p><strong>注意：</strong><strong>必须</strong>使用宏来展示运行实例的输出。为保安全，MDN 编辑器将会移除直接使用 <code><iframe></code> 标签的地方。</p> +</div> + +<p>每个包含示例代码的 {{HTMLElement("pre")}} 段落都有一个 class 指示它由何种语言写成（HTML、CSS 或 JavaScript）。这些 class 的值是“brush: html”、“brush: css”或“brush: js”。这些 class 必须与代码匹配以被维基正确使用。一般情况下，当你在使用编辑器工具栏的语法高亮时候，这些属性会被自动添加。</p> + +<p>运行实例系统由很多可用选项，我们会分解开来讲解。</p> + +<h3 id="运行实例宏">运行实例宏</h3> + +<p>你可以用两种宏来展示实例：</p> + +<ul> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a></code></span> 将一个运行实例嵌入到页面中</li> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> 创建一个链接，在新的页面中打开运行实例</li> +</ul> + +<p>在很多情况下，可以很便捷地使用以上两种宏 <span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a></code></span> 或 <span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> 。只要代码示例可以通过一个行级元素的id 或一个块级元素的id 的区分开，就可以简单的插入宏来实现功能。</p> + +<h4 id="页内运行实例宏">页内运行实例宏</h4> + +<pre class="syntaxbox notranslate"> \{{EmbedLiveSample(<em>block_ID</em>, <em>width</em>, <em>height</em>, <em>screenshot_URL</em>, <em>page_slug</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>必需。包含示例代码的元素的 id 。保证 ID正确的最好的办法是在内容表中查看 URL。</dd> + <dt>width</dt> + <dd>可选。创建的 {{HTMLElement("iframe")}} 元素的宽度，以 <code>px</code> 为单位。若忽略该项，系统会使用一个合理的默认宽度。请注意，如果需要指定该项，那么<strong>必须</strong>同时指定高度。</dd> + <dt>height</dt> + <dd>可选。创建的 {{HTMLElement("iframe")}} 元素的高度，以 <code>px</code> 为单位。若忽略该项，系统会使用一个合理的默认高度。请注意，如果需要指定该项，那么<strong>必须</strong>同时指定宽度。如果仅仅指定了高度和宽度中的一个，那么系统会应用默认尺寸。</dd> + <dt>screenshot_URL</dt> + <dd>可选。截屏 URL 显示了运行实例的效果。对于用户浏览器尚未支持的新技术很有用，他们就可以看到结果的快照。如果指定该项，截屏会带着相关标题显示在运行实例之后。</dd> + <dt>page_slug</dt> + <dd>可选。包含示例的页面的代称。若忽略该项，示例将会从宏所在页面拉取。</dd> +</dl> + +<ol> +</ol> + +<h4 id="链接运行实例宏">链接运行实例宏</h4> + +<pre class="syntaxbox notranslate"> \{{LiveSampleLink(<em>block_ID</em>, <em>link_text</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>必需。根据标题或段落的 ID 识别示例。保证正确使用 ID 最好的办法是在页面的目录中查找 URL。</dd> + <dt>link_text</dt> + <dd>链接地址文本。</dd> +</dl> + +<h2 id="使用运行实例系统">使用运行实例系统</h2> + +<p>以下部分描述了一些运行实例系统的常见用例。</p> + +<p>在所有这些用例中，必须点击编辑器的“<strong>保存更改</strong>”（将关闭编辑模式）才能看到运行实例。“预览变更”功能不可展示运行实例。</p> + +<h3 id="将片段转为运行实例">将片段转为运行实例</h3> + +<p>一个常见的用例是将 MDN 中已有代码片段转为运行实例。</p> + +<h4 id="准备代码示例">准备代码示例</h4> + +<p>第一步是添加代码片段，或根据内容和标记确认已有片段可以成为运行实例。代码片段必须组成一个完整可运行的示例。比如，如果已有 <code>CSS</code> 片段，那么需要添加一段 <code>HTML</code>。</p> + +<p>每段代码都需要包含在正确标记其语言的 {{HTMLElement("pre")}} 块中，每块中只能包含一种语言。多数情况下，这些步骤都没问题，不过再检查一遍总是好的。工具栏中<strong> <code>PRE</code> </strong>图标旁的按钮是一个提供选择语法的下拉框（语法高亮）。该选项除了设置语法高亮以外，还标记了代码片段在运行实例系统中的语言。</p> + +<div class="note"> +<p><strong>注意：</strong>每种语言的代码可以分布在几个 {{HTMLElement("pre")}} 块里，所有代码会被连接起来。这个特性允许一块代码对应一块简介。这样有利于制作教程，比如代码间夹杂着大量的注释。</p> +</div> + +<p>所以确认代码块被正确标记为其所用语言，然后你可以继续了。</p> + +<div class="note"> +<p><span style="font-size: 14px; line-height: 21px;"><strong>注意：</strong></span>当向MDN中粘贴内容时，请注意在粘贴带样式的内容时，可能会带来不需要的样式（比如复制高亮代码）。请尽量避免粘贴带样式的内容，在必须的情况下，请在源码模式中删除不需要的样式，或者使用“粘贴为纯文本”。</p> +</div> + +<h4 id="插入运行实例宏">插入运行实例宏</h4> + +<p>当代码准备好并被正确标记之后，需要插入宏来创建 <code>iframe</code>。</p> + +<ol> + <li>点击“<strong>插入运行实例框架</strong>”按钮（<img alt="" src="https://mdn.mozillademos.org/files/5383/insert-live-sample-btn.png" style="height: 18px; width: 19px;">），将会打开一个对话框可以配置。<img alt="" src="https://mdn.mozillademos.org/files/5385/sample-finder.png" style="height: 358px; width: 405px;"></li> + <li> + <p>在 <strong>Document</strong> 下方，输入包含实例的文章标题。默认是当前正被编辑的文章，但是可以被更改为 MDN 中的其它文章。这项特性允许在不同的页面中重用实例。（如果输入文字，将会出现一个部分匹配输入内容文章列表，可以从中选取需要的文章。）</p> + </li> + <li>在 <strong>Sections in Document</strong> 选项中，选取需要将包含实例的部分。</li> + <li>点击 <strong>OK</strong> 按钮，生成并将宏插入到文章中，宏调用代码看起来是这样的：<br> + <strong>\{{ EmbedLiveSample('Live_sample_demo') }}</strong></li> +</ol> + +<h3 id="增加新的运行实例">增加新的运行实例</h3> + +<p>在编辑一个新的一页需要插入运行实例时，编辑器做更多工作。</p> + +<ol> + <li>点击 <strong>Insert Code Sample Template</strong> 按钮（<img alt="" src="/files/4265/live-sample-button.png" style="height: 19px; width: 21px;">），将会出现这样的对话框。<br> + <img alt="" src="https://mdn.mozillademos.org/files/5387/insert-live-sample-template.png" style="height: 155px; width: 251px;"></li> + <li>输入运行实例的标题，请确保标题对于当前页面是有意义的。</li> + <li>点击 <strong>OK</strong>。会创建一个新的标题，还有一个空的代码框，可以输入 HTML、CSS 或 JavaScript。</li> + <li>删除不需要的标题的代码框。</li> + <li>输入代码</li> +</ol> + +<h2 id="Live_sample_demo" name="Live_sample_demo">查找需要更新的示例</h2> + +<p>当查询实例的时候，有三种可能的更新方式。</p> + +<ul> + <li>将一个非运行实例转为运行实例</li> + <li>解决运行实例的缺陷或错误</li> + <li>在技术有变更时，提升或更新运行实例</li> +</ul> + +<div class="note"> +<p><strong>注意：</strong>如果发现包含需要更新到运行实例系统的文章，请为文章增加标签“ NeedsLiveSample ”。</p> +</div> + +<h3 id="查找需要转为运行实例的示例">查找需要转为运行实例的示例</h3> + +<p>MDN 上有很多老版本的并且使用运行实例系统的示例。我们希望可以将多数示例更新到运行实例。这将会提升网站的一致性和可用性。在访问 MDN 时，你一定经常看到这些例子。然而，很难如果你想要找到某个特定的例子来更新，不过有一些方法可以试一试。</p> + +<ul> + <li>查询<a href="/en-US/docs/tag/NeedsLiveSample" title="/en-US/docs/tag/NeedsLiveSamples">带“NeedsLiveSample”的页面</a>。这些页面被用户标记为需要更新。如果发现需要被更新到运行实例的页面但是没时间理科更新的话，你也需要将该页面加上这个标记。</li> + <li>浏览可能包含示例的文档。比如 <a href="/en-US/docs/Web/JavaScript/Guide" title="/en-US/docs/Web/JavaScript/Guide">JavaScript Guide</a>、<a href="/en-US/docs/Web/HTML" title="/en-US/docs/Web/HTML">HTML documentation</a> 和 <a href="/en-US/docs/Web/CSS/Reference" title="/en-US/docs/Web/CSS/Reference">CSS reference</a>。</li> + <li>查看类似“<a href="/en-US/search?q=example" title="/en-US/search?q=example">example</a>”或“<a href="/en-US/search?q=sample" title="/en-US/search?q=sample">sample</a>”的关键词的搜索结果页面。</li> +</ul> + +<h2 id="Live_sample_demo" name="Live_sample_demo">运行实例演示</h2> + +<p>这部分是使用“插入运行实例模板”按钮插入运行实例标题和代码块的结果。每种语言可以有不止一个代码块。同样也不需要有特定的顺序，所有代码会被混合匹配。</p> + +<p>可以选取删除任何部分。如果不需要脚本，那么删掉脚本的标题和代码块就可以了。同样，也可以删掉其余任何代码块。</p> + +<p>代码模板插入之后，可以增加一些代码，也可以加入一些注释。</p> + +<h3 id="HTML">HTML</h3> + +<p>这段 HTML 代码创建了一个段落和几个 <code>DIV</code> 可以展示信息。</p> + +<pre class="brush: html notranslate"><p>A simple example of the live sample system in action.</p> +<div class="box"> + <div id="item">Hello world!</div> +</div> +</pre> + +<h3 id="CSS">CSS</h3> + +<p>这段 CSS 代码为信息增加样式。</p> + +<pre class="brush: css notranslate">.box { + width: 200px; + height: 100 px; + border-radius: 6px; + background-color: #ffaabb; +} + +#item { + width: 100%; + font-weight: bold; + text-align: center; + font-size: 2em; +} +</pre> + +<h3 id="JavaScript">JavaScript</h3> + +<p>这段代码很简单，只是增加了一个点击事件来弹出信息。</p> + +<pre class="brush: js notranslate">var el = document.getElementById('item'); +el.onclick = function() { + alert('Owww, stop poking me!'); +} +</pre> + +<p>这里通过<code>\{{EmbedLiveSample('Live_sample_demo')}}</code>来展示上面实例运行的结果。</p> + +<p>{{EmbedLiveSample('Live_sample_demo')}}</p> + +<p>这是使用外链宏<code>\{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</code>来展示实例运行的结果。</p> + +<p>{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}的集合</p> diff --git a/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html b/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html new file mode 100644 index 0000000000..d0ca0069fb --- /dev/null +++ b/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html @@ -0,0 +1,31 @@ +--- +title: A simple demo of a live code sample +slug: MDN/Structures/Live_samples/Simple_live_sample_demo +translation_of: MDN/Structures/Live_samples/Simple_live_sample_demo +--- +<div>{{MDNSidebar}}</div><h2 id="The_example">The_example</h2> + +<p id="Simple_example_of_a_live_demo">This is a very simple example showing you how to do a live demo in MDN. For more information, see <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">Live samples</a>.</p> + +<pre class="brush: html notranslate"><form> + <label>Try me<input type="text" name="name"></label> + <input type="submit" value="go"> +</form></pre> + +<pre class="brush: css notranslate">form { + border-radius: 10px; + background: powderblue; +}</pre> + +<pre class="brush: js notranslate">var f = document.querySelector('form'); + +f.addEventListener('submit', function(ev) { + ev.preventDefault(); + document.querySelectorAll('input')[1].value = 'sending'; +}, false);</pre> + +<p>{{ EmbedLiveSample('The_example', '', '', '') }}</p> + +<p> </p> + +<p> </p> diff --git a/files/zh-cn/mdn/structures/macros/custom_macros/index.html b/files/zh-cn/mdn/structures/macros/custom_macros/index.html new file mode 100644 index 0000000000..3809bb2094 --- /dev/null +++ b/files/zh-cn/mdn/structures/macros/custom_macros/index.html @@ -0,0 +1,222 @@ +--- +title: 常用的宏 +slug: MDN/Structures/Macros/Custom_macros +tags: + - CSS + - 参考 + - 宏 + - 结构 +translation_of: MDN/Structures/Macros/Commonly-used_macros +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见<a href="/en-US/docs/MDN/Contribute/Content/Macros">使用宏</a>和<a href="/en-US/docs/MDN/Contribute/Editor/Links#Using_link_macros">使用链接宏</a>。</span>对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见<a href="/en-US/docs/MDN/Contribute/Structures/Macros/Other">其它宏</a>。这里也有一份 <a href="/en-US/docs/templates">MDN 上所有宏的完整列表</a>。</p> + +<p>对于适合你使用的样式，另见 <a href="/en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide">CSS 样式指南</a>。</p> + +<h2 id="链接">链接</h2> + +<h3 id="创建一个单独的超链接">创建一个单独的超链接</h3> + +<p id="To_another_MDN_page_or_its_section_(anch_SectionOnPage_manch_Link_LinkItem_LinkItemDL)">通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的<strong>链接</strong>按钮创建链接。</p> + +<ul> + <li>{{TemplateLink("Glossary")}} 宏创建一个链接指向 MDN <a href="/en-US/docs/Glossary">术语汇编（glossary）</a>里的一个具体的术语词条。这个宏接受一个必须的和两个可选的参数： + + <ol> + <li>术语的名称（比如 "HTML"）。</li> + <li>代替术语名称显示在文章中的文本（此项应当尽可能少地使用）。{{optional_inline}}</li> + <li>如果这个参数是明确的并且是非零的，一般用于术语汇编链接的自定义样式将不适用。{{optional_inline}}</li> + </ol> + + <p>示例：</p> + + <ul> + <li>\{{Glossary("HTML")}} 生成 {{Glossary("HTML")}}</li> + <li>\{{Glossary("CSS", "Cascading Style Sheets")}} 生成 {{Glossary("CSS", "Cascading Style Sheets")}}</li> + <li>\{{Glossary("HTML", "", 1)}} 生成 {{Glossary("HTML", "", 1)}}</li> + </ul> + </li> +</ul> + +<h3 id="链接到参考文档页面">链接到参考文档页面</h3> + +<p>有各种宏用来链接到 MDN 上特定参考区域里的页面。</p> + +<ul> + <li>{{TemplateLink("cssxref")}} 链接到 <a href="/en-US/docs/CSS_Reference" title="en-US/docs/CSS_Reference">CSS 参考</a>里的一个页面。<br> + 示例： <code>\{{cssxref("cursor")}}</code>，显示为：{{ cssxref("cursor") }} 。</li> + <li>{{TemplateLink("domxref")}} 链接到 DOM 参考里的页面；如果你在结尾列入了圆括号，这个模板会像一个函数名那样显示这个链接。例如，<span class="plain"><span class="nowiki">\{{domxref("document.getElementsByName()")}}</span></span> 显示为 {{ domxref("document.getElementsByName()") }} <code>而 \{\{domxref("Node")\}\}</code> 显示为 {{ domxref("Node") }} 。</li> + <li>{{TemplateLink("event")}} 链接到 DOM 事件参考，例如：\{{event("change")}} 显示为 {{event("change")}} 。</li> + <li>{{TemplateLink("HTMLElement")}} 链接到 HTML 参考里的一个 HTML 元素。</li> + <li>{{TemplateLink("htmlattrxref")}} 链接到一个 HTML 属性。如果你只指定属性名，它将是一个全局属性的描述。如果你指定一个属性名和一个元素名，它将是一个具体元素的一个属性名。例如，<code>\{\{htmlattrxref("lang")\}\} </code>将创建链接：{{htmlattrxref("lang")}} 。<code>\{\{htmlattrxref("type","input")\}\}</code> 将创建链接：{{htmlattrxref("type","input")}} 。</li> + <li>{{TemplateLink("jsxref")}} 链接到 <a href="/en-US/docs/Web/JavaScript/Reference" title="en-US/docs/Web/JavaScript/Reference">JavaScript 参考</a>里的一个页面。</li> + <li>{{TemplateLink("SVGAttr")}} 链接到一个特定的 SVG 属性。例如，<code>\{\{SVGAttr("d")\}\}</code> 创建这样的链接： {{SVGAttr("d")}} 。</li> + <li>{{TemplateLink("SVGElement")}} 链接到 SVG 参考里的一个 SVG 元素。</li> +</ul> + +<h3 id="链接到漏洞和互联网中继聊天（IRC）">链接到漏洞和互联网中继聊天（IRC）</h3> + +<ul> + <li>漏洞 + <ul> + <li>通过使用下面的语法 {{TemplateLink("bug")}} 可以让你轻松地链接到 bugzilla.mozilla.org 上的一个漏洞（页面）：<code>\{\{Bug(123456)\}\}</code> 。这将显示：{{ Bug(123456) }} 。</li> + <li>{{TemplateLink("WebkitBug")}} 插入一条指向 WebKit 漏洞数据库中一个漏洞的链接。例如：<code>\{\{WebkitBug(31277)\}\}</code> 插入 {{ WebkitBug(31277) }} 。</li> + </ul> + </li> + <li>{{TemplateLink("IRCLink")}} 插入一条指向特定 IRC 频道的链接，它带有一个提示框标明它是做什么的以及它需要一个 IRC 客户端。</li> +</ul> + +<h3 id="用于多页面指南的导航帮助">用于多页面指南的导航帮助</h3> + +<p>{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。</p> + +<h2 id="代码示例">代码示例</h2> + +<h3 id="实样">实样</h3> + +<ul> + <li>{{TemplateLink("EmbedLiveSample")}} 让你嵌入一个如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样（Live samples）</a>中描述的代码示例结果到页面上。</li> + <li>{{TemplateLink("LiveSampleLink")}} 创建一个链接指向一个包含（当前）页面上如<a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">实样</a>中描述的代码示例结果。</li> +</ul> + +<h3 id="附上的示例文件">附上的示例文件</h3> + +<ul> + <li>{{TemplateLink("Embed_text")}} 模板允许你嵌入一份附加的文本文件到你的文章主体部分中。这将有助于你让代码段既可下载又能显示在文章内容中。你可以为语法高亮选择地指定一种语言。如果你不指定一种（语言），该文本将无格式化嵌入。第一个参数是被嵌入附件的文件名；第二个（参数），如果支持的话，是用于语法高亮的语言，比如 "javascript", "svg" 或 "cpp" 。</li> + <li>{{TemplateLink("EmbedSVG")}} 嵌入一个附带 XML 文件作为一张 SVG 图像到页面当中。指定附带的 SVG 文件的文件名。你可以和 {{TemplateLink("Embed_text")}} 一同使用来展示源码和相同文件的渲染输出。</li> +</ul> + +<h2 id="侧边栏组">侧边栏组</h2> + +<p>There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。</p> + +<ul> + <li>{{TemplateLink("CSSRef")}} 生成 CSS 参考页面的侧边栏。</li> + <li>{{TemplateLink("HTMLRef")}} 生成 HTML 参考页面的侧边栏。</li> + <li>{{TemplateLink("APIRef")}} 生成 Web API 参考页面的侧边栏。</li> +</ul> + +<p>（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）</p> + +<h2 id="通用格式化">通用格式化</h2> + +<h3 id="API_文档的行内指示器">API 文档的行内指示器</h3> + +<p>{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常当描述一个对象的属性或一个函数的参数的列表。</p> + +<p>用法: <code>\{{optional_inline()}}</code> 或 <code>\{{ReadOnlyInline()}} 。</code>示例：</p> + +<dl> + <dt><code>isCustomObject</code> {{ReadOnlyInline()}}</dt> + <dd>如果为真，指示该对象是一个自定义对象。</dd> + <dt>parameterX {{ optional_inline() }}</dt> + <dd>Blah blah blah...</dd> +</dl> + +<h2 id="状态和兼容性指示器">状态和兼容性指示器</h2> + +<h3 id="没有附加参数的行内指示器">没有附加参数的行内指示器</h3> + +<h4 id="非标准的">非标准的</h4> + +<p>{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。</p> + +<h5 id="语法"><strong>语法</strong></h5> + +<p><code>\{{non-standard_inline}}</code></p> + +<h5 id="示例">示例</h5> + +<ul> + <li>图标：{{non-standard_inline}}</li> +</ul> + +<h4 id="实验性的">实验性的</h4> + +<p>{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。</p> + +<h5 id="语法_2">语法</h5> + +<p><code>\{{experimental_inline}}</code></p> + +<h5 id="示例_2"><code>示例</code></h5> + +<ul> + <li>图标：{{experimental_inline}}</li> +</ul> + +<h3 id="提供明确技术的指示器">提供明确技术的指示器</h3> + +<p>在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。</p> + +<h4 id="不赞成的">不赞成的</h4> + +<p>{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。<strong>注意：</strong>“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。</p> + +<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p> + +<h5 id="语法_3">语法</h5> + +<p><code>\{{deprecated_inline}}</code> <code>或 \{{deprecated_inline("gecko5")}}</code></p> + +<h5 id="示例_3">示例</h5> + +<ul> + <li>图标：{{deprecated_inline}}</li> + <li>徽标：{{deprecated_inline("gecko5")}}</li> +</ul> + +<h4 id="已废弃的">已废弃的</h4> + +<p>{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。</p> + +<p>不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。</p> + +<h5 id="语法_4">语法</h5> + +<p><code>\{{obsolete_inline}}</code> 或<code> \{{obsolete_inline("js1.8.5")}}</code></p> + +<h5 id="示例_4">示例</h5> + +<ul> + <li>图标：{{obsolete_inline}}</li> + <li>徽标：{{obsolete_inline("js1.8.5")}}</li> +</ul> + +<h3 id="模板徽标">模板徽标</h3> + +<p>这些宏大多数被用于 <a href="/en-US/docs/WebAPI">WebAPI</a> 页面。见 {{anch("Creating new badges")}} 关于创建一个新徽标的信息。</p> + +<h3 id="页面或区域标头指示">页面或区域标头指示</h3> + +<p>这些模板与上述内联模板具有相同的语义。 模板应直接放置在参考页面的主页标题（或面包屑导航，如果可用）的下面。 它们也可以用于标记页面上的某个部分。</p> + +<ul> + <li>{{TemplateLink("non-standard_header")}}: <code>\{{Non-standard_header()}}</code> {{ Non-standard_header() }}</li> + <li>{{TemplateLink("SeeCompatTable")}} 应该被放置在介绍实验性功能或兼容性的区域。 示例: <code>\{{SeeCompatTable()}}</code> {{ SeeCompatTable() }}</li> + <li>{{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header()}}</code> {{ Deprecated_header() }}</li> + <li>{{TemplateLink("deprecated_header")}} 搭配变量: <code>\{{deprecated_header("gecko5")}}</code> {{ Deprecated_header("gecko5") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li> + <li>{{TemplateLink("obsolete_header")}}: <code>\{{obsolete_header()}}</code> {{ Obsolete_header() }}</li> + <li>{{TemplateLink("obsolete_header")}} 搭配变量: <code>\{{obsolete_header("gecko30")}}</code> {{ Obsolete_header("gecko30") }} 不要在与浏览器无关的任何区域中使用该参数 (HTML, APIs, JS, CSS, …).</li> + <li>{{TemplateLink("secureContext_header")}}: <code>\{{SecureContext_Header}}</code> {{SecureContext_Header}}</li> +</ul> + +<h3 id="指示一个功能在Web_workers中可用">指示一个功能在Web workers中可用</h3> + +<p> {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在<a href="/en-US/docs/Web/API/Web_Workers_API">Web worker</a> 上下文中可用。</p> + +<h2 id="版本信息宏">版本信息宏</h2> + +<p>这些宏被用来指示这个语段只与一个产品的特定版本有关。</p> + +<ul> + <li>{{TemplateLink("gecko_minversion_inline")}}: 示例: {{ gecko_minversion_inline("9.9") }}</li> + <li>{{TemplateLink("fx_minversion_inline")}}:示例: {{ fx_minversion_inline("9.9") }}</li> +</ul> + +<ol> +</ol> + +<ol> +</ol> diff --git a/files/zh-cn/mdn/structures/macros/index.html b/files/zh-cn/mdn/structures/macros/index.html new file mode 100644 index 0000000000..4ddb72e576 --- /dev/null +++ b/files/zh-cn/mdn/structures/macros/index.html @@ -0,0 +1,48 @@ +--- +title: Macros +slug: MDN/Structures/Macros +tags: + - Guide + - Kuma + - KumaScript + - MDN Meta + - Structures +translation_of: MDN/Structures/Macros +--- +<div>{{MDNSidebar}}</div> + +<p><a href="/en-US/docs/Project:MDN/Kuma" title="/en-US/docs/Project:MDN/Kuma">Kuma</a> 平台为 MDN 提供了强大的宏系统——<a href="/en-US/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript</a>，使得 MDN 能够自动地去做各种东西。本文提供一些信息以便大家知道如何使用 MDN 上的文章内的宏。</p> + +<p>鉴于本文只是 KumaScript 的简介，<a href="/zh-CN/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript 指南</a>提供了更深入的内容。</p> + +<h2 id="宏是如何实现的">宏是如何实现的</h2> + +<p>MDN使用的Macros(宏)是基于<a href="http://nodejs.org/" title="http://nodejs.org/">Node.js</a>执行环境，并在服务端执行运行。这里包括了大量的代码库，另外对此还提供了丰富的wiki说明文档内容。如果你希望能学习到更多的内容，可以查看 <a href="/en-US/docs/Project:MDN/Kuma/KumaScript_guide" title="/en-US/docs/Project:MDN/Kuma/KumaScript_guide">KumaScript 指南</a>， <a href="/en-US/docs/Project:MDN/Kuma/KumaScript_reference" title="/en-US/docs/Project:MDN/Kuma/KumaScript_reference">KumaScript reference</a> 则提供了更多关于这些代码库和KumaScript的API的实现机理。</p> + +<h2 id="在文章中使用宏">在文章中使用宏</h2> + +<p>要实际使用宏，只需将对宏的调用括在一对双括号中，其参数（如果有）括在括号中;如下：</p> + +<pre class="notranslate">\{{macroname(parameter-list)}}</pre> + +<p>关于宏调用的一些注意事项：</p> + +<ul> + <li>宏名称区分大小写，但有些尝试是为了纠正常见的大写错误;即使宏名称在其中使用大写，您也可以使用全部小写，并且您可以将名称通常以小写字母开头的宏大写。</li> + <li>参数以逗号分隔</li> + <li>如果没有参数，您可以完全省略括号; <code>\{{macroname()}}</code> 和 <code>\{{macroname}}</code> 完全相同。</li> + <li>数字参数可以是引号，也可以不是。这取决于您（但是，如果您的版本号中包含多个小数，则需要在引号中）</li> + <li>如果您遇到错误，请仔细检查您的代码。如果仍然无法弄清楚发生了什么，请参阅<a href="/en-US/docs/MDN/Kuma/Troubleshooting_KumaScript_errors">Troubleshooting KumaScript errors</a>以获取帮助。</li> +</ul> + +<p>宏被高度缓存;对于任何一组输入值（参数和环境值，例如运行宏的URL），结果都会被存储和重用。这意味着宏仅在输入发生变化时才实际运行。</p> + +<div class="note"> +<p><strong>注意:</strong> 您可以通过在浏览器中强制刷新页面（即转移重新加载）来强制重新评估页面上的所有宏。</p> +</div> + +<p>宏可以像插入更大的文本块或从MDN的另一部分交换内容一样简单，也可以通过搜索站点的各个部分，设置输出样式和添加链接来构建整个内容索引。</p> + +<p>您可以在<a href="/en-US/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="/en-US/docs/Project:MDN/Contributing/Custom_macros">Commonly-used macros</a>页面上阅读我们最常用的宏;另外，这里有<a href="https://developer.mozilla.org/en-US/docs/templates" title="https://developer.mozilla.org/en-US/docs/templates">complete list of all macros</a>。大多数宏都有内置的文档，作为顶部的注释。</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/zh-cn/mdn/user_guide/writing/index.html b/files/zh-cn/mdn/user_guide/writing/index.html new file mode 100644 index 0000000000..5b2c6762f3 --- /dev/null +++ b/files/zh-cn/mdn/user_guide/writing/index.html @@ -0,0 +1,64 @@ +--- +title: 写作内容 +slug: MDN/User_guide/Writing +tags: + - 写作内容 +translation_of: Archive/Meta_docs/Writing_content +--- +<p>在MDN上经常会有一些东西需要加进来和更新。不管是一个全新出彩API的文档或者一个旧API的细微修改，你会找到很多可以出力的机会。关于怎么使用编辑器，和我们为了自动化结构与内容格式使用的宏系统的细节，请参看<a href="/en-US/docs/Project:MDN/Contributing/Editor_guide" style="line-height: 1.5;" title="/en-US/docs/Project:MDN/Contributing/Editor_guide">MDN editor guide</a>。</p> +<h2 id="编辑一个已经存在的页面">编辑一个已经存在的页面</h2> +<p>如果你找到一个想去修正的页面，简单点击右上方的“编辑”按钮。这会打开一个 <span style="line-height: 1.5;">WYSIWYG编辑器来帮助你修改页面内容。</span></p> +<p>有很多原因你会去编辑一个已经存在的页面：</p> +<ul> + <li>你发现一个错误或者错字。</li> + <li>你想把某件事重述让人更容易理解。</li> + <li>页面的布局或者格式混乱。</li> + <li>API的文档发生了变化，文档需要相应作出更新。</li> + <li>你想要增加一些信息，关于一个API在多个浏览器的性能表现差异。</li> + <li>你想要增加或者改进一个代码范例</li> + <li>文章是一个存根，或者仅仅丢失了一些重要的细节。</li> +</ul> +<h2 id="增加一个新页面">增加一个新页面</h2> +<p>这是个大的任务！<span style="line-height: 1.5;">在MDN上</span><span style="line-height: 1.5;">添加一个新的页面会让Web爱上你，拥抱你。这里有一些显而易见的原因，包括给未文档化的API做文档，增加一个新的教程或者?做一个主题的指南。</span></p> +<p>当你登陆后，按以下步骤去创建一个新的页面在MDN上:</p> +<dl> + <dt> + 点击一个 "missing page" 链接</dt> + <dd> + 当你浏览MDN的时候，你会偶然发现有些链接的页面还不存在。很多时候，当我们创建文章，我们会把需要创建的页面链接加进去，即使它们还没做好。这有助于我们跟踪那些最终需要完成的事，虽然有时候会花一些时间回过去完成它们。你可以随意去做！只要点击这些链接，你会直接进入新网页的编辑器。</dd> + <dt> + </dt> + <dt> + 创建一个子页面</dt> + <dd> + 在每篇文章的最右上角是“This Page“下拉菜单。菜单里面有”New sub-page“选项。点击这个选项会打开一个页面编辑器，在这个新的页面在站点层次上的父页面是你选择”New sub-page“那个页面。只需填写标题和标签，就可以开始写正文了。</dd> + <dt> + 创建一个副本</dt> + <dd> + 你也可以克隆一个已经存在的页面，使用“This page“下拉菜单的”Clone this page“选项。点击该选项会复制当前页面，其父页面和当前页面完全相同。接着页面上会打开编辑器，你就可以设置页面的标题和标签，然后编辑页面的内容。给一个现有站点参考区域增加一个新的页面，通常是一个好的方式。比如，这会给你内容布局的样式。</dd> + <dt> + 创建一个链接到还没存在的页面，然后点击它</dt> + <dd> + 这有点儿混合模式。因为每个页面应该被某处链接到，你可以从给一个新的文章创建一个已有页面的链接开始，然后保存页面。你可以点击你刚刚插入的链接，接着在打开的编辑器中写新的文章。</dd> +</dl> +<p> </p> +<p> </p> +<div class="note"> + <p><b>注意：如果你没有登录，当你想要查看未存在的文章时，会跳出404错误提示，而不是跳出新页面的编辑器。</b></p> +</div> +<h2 id="寻找信息">寻找信息</h2> +<p style="margin-left: 40px;">有很多信息没有出现在这里。有时候这些信息你很难搜寻到，但你恰好很需要用到，这里有一些提示来帮助你。</p> +<dl> + <dt> + 模块化所有者列表</dt> + <dd> + Mozilla的项目在一个“模块所有者”基础上进行；每一个重要的组件都有一个或者多个所有者负责它的进展。这些所有者往往是信息的最好来源--至少是个好的方式找到对的人来讨论。</dd> + <dt> + Mozilla源交叉参考</dt> + <dd> + MXR（Mozilla cross-reference的缩写）能让你得到所有Mozilla工程的源代码（有些事例除外，比如Firefox OS是托管在Github上）。代码和有关评论常常是信息的重要资源。</dd> + <dt> + Mozilla wiki</dt> + <dd> + The Mozilla wiki（常被称作“wikimo“）是过程和设计的一些笔记，草稿，计划和初步的方案等。尽管看起来一团糟，但也是宝贵的知识库。</dd> +</dl> |