diff options
Diffstat (limited to 'files/fr/mdn/structures')
| -rw-r--r-- | files/fr/mdn/structures/exemples_live/index.html | 250 | ||||
| -rw-r--r-- | files/fr/mdn/structures/index.html | 17 | ||||
| -rw-r--r-- | files/fr/mdn/structures/macros/commonly-used_macros/index.html | 224 | ||||
| -rw-r--r-- | files/fr/mdn/structures/macros/index.html | 40 | ||||
| -rw-r--r-- | files/fr/mdn/structures/tables_de_compatibilité/index.html | 503 |
5 files changed, 1034 insertions, 0 deletions
diff --git a/files/fr/mdn/structures/exemples_live/index.html b/files/fr/mdn/structures/exemples_live/index.html new file mode 100644 index 0000000000..7645a89375 --- /dev/null +++ b/files/fr/mdn/structures/exemples_live/index.html @@ -0,0 +1,250 @@ +--- +title: Exemples live +slug: MDN/Structures/Exemples_live +tags: + - Débutant + - Guide + - MDN + - MDN Meta +translation_of: MDN/Structures/Live_samples +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">MDN permet de transformer les exemples présentés dans les articles en exemples dit "live" qui permettent aux lecteurs de les voir en action. Les exemples live peuvent inclure du HTML, CSS et JavaScript. A noter, les exemples lives <em>ne sont pas intéractifs</em>; néanmoins, ils assurent que le code de sortie affiché pour un exemple est bien le même que défini par l'exemple, parce que la sortie est générée par le code d'exemple.</span></p> + +<h2 id="Comment_le_système_dexemples_lives_fonctionne-t-il">Comment le système d'exemples lives fonctionne-t-il ?</h2> + +<p>Le système d'exemple live rassemble tout le code existant et le fusionne dans un fichier HTML, puis affiche ce fichier dans une {{HTMLElement("iframe")}}. Un exemple live est composé de deux parties : </p> + +<ul> + <li>Un groupe qui comporte tout le code de l'exemple</li> + <li>La macro (crée l'<em>iframe</em> ou le lien qui) affiche le résultat du bloque de code</li> +</ul> + +<p>A "group" of code blocks, in this context, is identified by the ID of a heading or a block element (such as a {{HTMLElement("div")}}).</p> + +<ul> + <li>If the ID belongs to a block element, the group includes all the code blocks within the enclosing block element whose ID is used. </li> + <li>If the ID belongs to a heading, the group includes all the code blocks that are after that heading and before the next heading of the same heading level. Note that code blocks under subheadings of the specified heading are all used; if this is not the effect you want, use an ID on a block element instead.</li> +</ul> + +<p>The macro uses a special URL to fetch the sample code for a given group: <code>http://<em>url-of-page</em>$samples/<em>group-id</em></code>, where <code>group-id</code> is the ID of the heading or block where the code is located. The resulting frame (or page) is sandboxed, secure, and technically may do anything that works on the Web. Of course, as a practical matter, the code must contribute to the point of the page that contains it; random stuff running on MDN will be removed by the editor community.</p> + +<div class="note"> +<p><strong>Note:</strong> You <strong>must</strong> use the macro for presenting the live sample's output. MDN's editor will strip out any direct use of the <code><iframe></code> element in order to ensure security.</p> +</div> + +<p>Each {{HTMLElement("pre")}} block containing code for the sample has a class on it that indicates whether it's HTML, CSS, or JavaScript code; these are "brush: html", "brush: css", and "brush: js". These classes must be on the corresponding blocks of code so that the wiki can use them correctly; fortunately, these are added for you automatically when you use the syntax highlighter features in the editor's toolbar.</p> + +<p>The live sample system has lots of options available, and we'll try to break things down to look at them a bit at a time.</p> + +<h3 id="Live_sample_macros">Live sample macros</h3> + +<p>There are two macros that you can use to display live samples:</p> + +<ul> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a> </code></span>embeds a live sample into a page</li> + <li><span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> creates a link that opens the live sample in a new page</li> +</ul> + +<p>In many cases, you may be able to add the <span class="templateLink"><code><a href="/en-US/docs/Template:EmbedLiveSample">EmbedLiveSample</a></code></span> or <span class="templateLink"><code><a href="/en-US/docs/Template:LiveSampleLink">LiveSampleLink</a></code></span> macro to pages with little or no additional work! As long as the sample can be identified by a heading's ID or is in a block with an ID you can use, simply adding the macro should do the job.</p> + +<h4 id="EmbedLiveSample_macro">EmbedLiveSample macro</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>Required: The ID of the heading or enclosing block to draw the code from. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents.</dd> + <dt>width</dt> + <dd>The width of the {{HTMLElement("iframe")}} to create, specified in <code>px</code>. This is optional; a reasonable default width will be used if you omit this. Note that if you want to use a specific width, you <em>must</em> also specify the height parameter.</dd> + <dt>height</dt> + <dd>The height of the {{HTMLElement("iframe")}} to create, specified in <code>px</code>. This is optional; a reasonable default height will be used if you omit this. Note that if you want to use a specific height, you <em>must</em> also specify the width parameter. If you use only one of them, the default frame size is used.</dd> + <dt>screenshot_URL</dt> + <dd>The URL of a screenshot that shows what the live sample should look like. This is optional, but can be useful for new technologies that may not work in the user's browser, so they can see what the sample would look like if it were supported by their browser. If you include this parameter, the screenshot is shown next to the live sample, with appropriate headings.</dd> + <dt>page_slug</dt> + <dd>The slug of the page containing the sample; this is optional, and if it's not provided, the sample is pulled from the same page on which the macro is used.</dd> +</dl> + +<ol> +</ol> + +<h4 id="LiveSampleLink_macro">LiveSampleLink macro</h4> + +<pre class="syntaxbox notranslate"> \{{LiveSampleLink(<em>block_ID</em>, <em>link_text</em>)}}</pre> + +<dl> + <dt>block_ID</dt> + <dd>The ID of the heading or enclosing block to draw the code from. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents.</dd> + <dt>link_text</dt> + <dd>A string to use as the link text.</dd> +</dl> + +<h2 id="Using_the_live_sample_system">Using the live sample system</h2> + +<p>The sections below describe a few common use cases for the live sample system.</p> + +<p>In all of these cases, to see the results of the live sample, you must click <strong>Save Changes</strong> in the editor (which takes you out of edit mode). Because of the reflexive, <a href="http://www.imdb.com/title/tt1375666/?ref_=nv_sr_1"><em>Inception</em></a>-like nature of live samples, the <strong>Preview Changes</strong> functionality is <em>not</em> able to display live samples.</p> + +<h3 id="Turning_snippets_into_live_samples">Turning snippets into live samples</h3> + +<p>One common use case is to take existing code snippets already shown on MDN and turn them into live samples.</p> + +<h4 id="Prepare_the_code_samples">Prepare the code samples</h4> + +<p>The first step is to either add code snippets or ensure that existing ones are ready to be used as live samples, in terms of the content and in terms of their mark-up. The code snippets, taken together, must comprise a complete, runnable example. For example, if the existing snippet shows only CSS, you might need to add a snippet of HTML for the CSS to operate on.</p> + +<p>Each piece of code must be in a {{HTMLElement("pre")}} block, with a separate block for each language, properly marked as to which language it is. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. Next to the <strong>PRE</strong> icon in the toolbar is a drop-down menu icon (tooltip: Syntax Highlighter) with the various languages that MDN does syntax highlighting for. Setting the language for the block for syntax highlighting also correlates it with a language for the purposes of the live sample system.</p> + +<div class="note"> +<p><strong>Note:</strong> You may have more than one block for each language; they are all concatenated together. This lets you have a chunk of code, followed by an explanation of how it works, then another chunk, and so forth. This makes it even easier to produce tutorials and the like that utilize live samples interspersed with explanatory text.</p> +</div> + +<p>So make sure the {{HTMLElement("pre")}} blocks for your HTML, CSS, and/or JavaScript code are each configured correctly for that language's syntax highlighting, and you're good to go.</p> + +<div class="note"> +<p><strong>Note:</strong> When pasting content into MDN, please be aware that if pasting styled content (including, for example, syntax highlighting in code being copied from another site) that you may be bringing along unwanted and unneeded additional styles or classes. Please be careful not to do this; if necessary, review your edit in source mode to remove these unnecessary styles and classes (or check it before pasting, or use the "Paste as plain text" option instead).</p> +</div> + +<h4 id="Insert_the_live_sample_macro">Insert the live sample macro</h4> + +<p>Once the code is in place and properly configured to identify each block's language, you need to insert the macro that creates the iframe.</p> + +<ol> + <li>Click the <strong>Insert Live Code Sample iFrame</strong> button in the toolbar; it looks like this: <img alt="" src="https://mdn.mozillademos.org/files/5383/insert-live-sample-btn.png" style="height: 18px; width: 19px;">. This opens a dialog box for configuring your live sample frame:<img alt="" src="https://mdn.mozillademos.org/files/5385/sample-finder.png" style="height: 358px; width: 405px;"></li> + <li>Under <strong>Document</strong>, enter the title of the article that contains the sample you wish to embed. By default, it's the article you're currently editing, but you can choose an article elsewhere on MDN, too. This makes it possible to reuse samples on multiple pages if needed. (If you type new text in this field, a menu of partially matching pages appears; select the title of the page you want.)</li> + <li>In the <strong>Sections in Document</strong> menu, select the section in the article that contains the code blocks of the sample you want to embed.</li> + <li>Click the <strong>OK</strong> button to generate and insert the macro call that creates the sample frame for you. The macro call looks something like this:<br> + <strong>\{{ EmbedLiveSample('Live_sample_demo') }}</strong></li> +</ol> + +<h3 id="Adding_a_new_live_sample">Adding a new live sample</h3> + +<p>If you're writing a new page, and want to insert code that you want to present as a live sample, even more of the work can be done for you by the editor! </p> + +<ol> + <li>Click the <strong>Insert Code Sample Template</strong> button in the toolbar, which looks like this: <img alt="" src="/files/4265/live-sample-button.png" style="height: 19px; width: 21px;">. This presents a simple dialog asking you to name your live sample:<br> + <img alt="" src="https://mdn.mozillademos.org/files/5387/insert-live-sample-template.png" style="height: 155px; width: 251px;"></li> + <li>Enter the title of the sample; this is used as the heading for the sample. Make sure that your title makes sense within the context of the page you're on.</li> + <li>Click <strong>OK</strong>. A new heading with the title you entered is created, with sub-headings and empty code blocks for HTML, CSS, and JavaScript.</li> + <li>Delete any headings and code blocks you don't need.</li> + <li>Enter the code that makes up your sample in the appropriate code blocks</li> + <li><a href="#conventions">Check conventions</a></li> +</ol> + +<h3 id="Using_the_Sample_Finder">Using the Sample Finder</h3> + +<p>As mentioned above, the Sample Finder is activated by clicking the<strong> Insert Live Code Sample iFrame</strong> icon. Unfortunately the the Sample Finder may produce a macro that is NOT usable without editing. There are two problem areas that should be carefully checked and edited if necessary.</p> + +<ol> + <li><strong>Document </strong>field. This field will search as you type and present a list of documents that match your string. But the list presented will NOT include the sub-page. For example, say you are working on the subpage for <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@counter-style/negative">Negative </a>under the main page <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@counter-style">@counter-style</a>. The Sample Finder search will not find Negative but will find the main page @counter-style. When @counter-style is selected the field background turns green. See below for the issue this creates.</li> + <li><strong>Sections in Document</strong>. The pull-down menu Sections in Document may not show the section that you need. Just pick one, say Examples, and it can be fixed with a simple edit.</li> +</ol> + +<p>Here is what the Sample Finder produced:</p> + +<pre class="notranslate"><code>\{{ EmbedLiveSample('Examples', '', '', '', 'Web/CSS/@counter-style') }}</code></pre> + +<p>This macro will not work. The block_ID is Examples and it should be Example in this case (check the source ID for this section to verify which block_ID you need to use. Similarly the page_slug is @counter-style and it should be @counter-style/negative. These corrections can be done directly in the page with Edit active.</p> + +<p>After editing the macro now looks like this:</p> + +<pre class="notranslate"><code>\{{ EmbedLiveSample('Example', '', '', '', 'Web/CSS/@counter-style/negative') }}</code></pre> + +<p>This edited macro will work correctly. If the macro is working correctly you will see the <strong>Open in CodePen</strong> button. A thumbnail of the example should appear above the Open in CodePen button. If the button is there but there isn't a thumbnail, just wait a few minutes. It may take some time for the server to generate it.</p> + +<h2 id="Live_sample_demo" name="Live_sample_demo">Finding samples that need updating</h2> + +<p>When looking for existing samples to update, there are three main kinds of updating you may wish to do:</p> + +<ul> + <li>Turn an existing non-live example snippet into a live sample.</li> + <li>Correct bugs in an existing live sample.</li> + <li>Improve an existing live sample, or update a sample based on technology changes.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong><strong>:</strong> If you find an article that has samples in need of being updated to use the live sample system, please add the tag "NeedsLiveSample" to the page.</p> +</div> + +<h3 id="Finding_samples_to_turn_into_live_samples">Finding samples to turn into live samples</h3> + +<p>MDN has lots of older examples that don't yet use the live sample system. Our goal is to update most or all of these to be live samples. This will improve consistency and usability. You will almost certainly find many of these as you use MDN on a daily basis; however, how can you find them if you're specifically looking for them to update? Unfortunately, there's not an easy way to do that. But there are some guidelines you can follow to help track them down:</p> + +<ul> + <li>Start by looking at this <a href="/en-US/docs/tag/NeedsLiveSample" title="/en-US/docs/tag/NeedsLiveSamples">list of pages tagged with "NeedsLiveSample"</a>. These are pages that users have marked as needing updating. You should add this tag yourself, if you see a page that needs to be updated to use live samples but don't have time to fix right away.</li> + <li>Browse through documentation trees that are likely to include examples, such as the <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>, and <a href="/en-US/docs/Web/CSS/Reference" title="/en-US/docs/Web/CSS/Reference">CSS reference</a>.</li> + <li>Search for terms like "<a href="/en-US/search?q=example" title="/en-US/search?q=example">example</a>" or "<a href="/en-US/search?q=sample" title="/en-US/search?q=sample">sample</a>" and look through the results for pages to update.</li> +</ul> + +<h2 id="Live_sample_demo" name="Live_sample_demo">Live sample demo</h2> + +<p>This section is the result of using the live sample template button to create not only the main heading ("Live sample demo"), but also subheadings for our HTML, CSS, and JavaScript content. You're not limited to one block of each; in addition, they don't even need to be in any particular order. Mix and match!</p> + +<p>You may choose to delete any of these you wish; if you don't need any script, just delete that heading and its {{HTMLElement("pre")}} block. You can also delete the heading for a code block ("HTML", "CSS", or "JavaScript"), since these are not used by the live sample macro.</p> + +<p>Now that the template has been inserted, we can put in some code, and even some explanatory text.</p> + +<h3 id="HTML">HTML</h3> + +<p>This HTML creates a paragraph and some blocks to help us position and style a message.</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>The CSS code styles the box as well as the text inside it.</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>This code is very simple. All it does is attach an event handler to the "Hello world!" text that makes an alert appear when it is clicked.</p> + +<pre class="brush: js notranslate">var el = document.getElementById('item'); +el.onclick = function() { + alert('Owww, stop poking me!'); +} +</pre> + +<h3 id="Result">Result</h3> + +<p>Here is the result of running the code blocks above via<code> \{{EmbedLiveSample('Live_sample_demo')}}</code>:</p> + +<p>{{EmbedLiveSample('Live_sample_demo')}}</p> + +<p>Here is a link that results from calling these code blocks via <code>\{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</code>:</p> + +<p>{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}</p> + +<h2 id="Conventions_regarding_live_samples"><a id="conventions" name="conventions">Conventions regarding live samples</a></h2> + +<div class="note"> +<p><strong>Note:</strong> This is currently (Feb. 2016) under discussion on the dev-mdc mailing list (see <a href="https://groups.google.com/forum/#!topic/mozilla.dev.mdc/49oqJAHFnWQ">this thread</a>). Any input is welcome. If this note persists after some month (Apr. 2016), please reach the author of the first email in this thread for updating this page.</p> +</div> + +<dl> + <dt>Orders of code blocks</dt> + <dd>When adding a live sample, the code blocks should be sorted so that the first one corresponds to the main language for this sample (if there is one). For example, when adding a live sample for the HTML Reference, the first block should be HTML, when adding a live sample for the CSS Reference, it should be CSS and so on.</dd> + <dt>Naming of headings</dt> + <dd>When there is no ambiguity (e.g. the sample is under a "Examples" section), headings should be straightforward with the sole name of the corresponding language: HTML, CSS, JavaScript, SVG, etc. (see above). Headings like "HTML Content" or "JavaScript Content" should not be used. However if such a short heading makes content unclear, one can use a more thoughtful title.</dd> + <dt>Using a "Result" block</dt> + <dd>After the different code blocks, please use a last "Result" block before using the <code>EmbedLiveSample</code> macro (see above). This way, the semantic of the example is made clearer for both the reader and any tools that would parse the page (e.g. screen reader, web crawler).</dd> +</dl> diff --git a/files/fr/mdn/structures/index.html b/files/fr/mdn/structures/index.html new file mode 100644 index 0000000000..5e605bea37 --- /dev/null +++ b/files/fr/mdn/structures/index.html @@ -0,0 +1,17 @@ +--- +title: Document structures +slug: MDN/Structures +tags: + - Landing + - MDN Meta + - Structures + - TopicStub +translation_of: MDN/Structures +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p>Tout au long de MDN, il existe diverses structures de document qui sont utilisées à plusieurs reprises, pour fournir une présentation cohérente des informations dans les articles MDN. Voici des articles décrivant ces structures, afin que, en tant qu'auteur MDN, vous puissiez les reconnaître, les appliquer et les modifier selon les besoins pour les documents que vous écrivez, modifiez ou traduisez.</p> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/fr/mdn/structures/macros/commonly-used_macros/index.html b/files/fr/mdn/structures/macros/commonly-used_macros/index.html new file mode 100644 index 0000000000..39f5a08225 --- /dev/null +++ b/files/fr/mdn/structures/macros/commonly-used_macros/index.html @@ -0,0 +1,224 @@ +--- +title: Commonly-used macros +slug: MDN/Structures/Macros/Commonly-used_macros +translation_of: MDN/Structures/Macros/Commonly-used_macros +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">Cette page présente un grand nombre de macros à usage général créées pour une utilisation avec MDN. Pour avoir des informations sur l'utilisation de ces macros, voir <a href="https://developer.mozilla.org/fr/docs/MDN/Contribute/Structures/Macros" title="/fr/docs/MDN/Contribute/Content/Macros"> Utilisation des macros </a> et <a href="/fr/docs/MDN/Contribute/Editor/Links#Using_link_macros" title="/fr/docs/MDN/Contribute/Editor/Links#Using_link_macros"> Utiliser les liens macros </a>.</span> Voir <a href="/fr/docs/MDN/Contribute/Structures/Macros/Other" title="/fr/docs/MDN/Contribute/Structures/Macros/Other"> les autres macros </a> pour avoir des informations sur les macros qui sont rarement utilisées, ou utilisées dans des contextes spécifiques, ou obsolètes. Il y a aussi une liste complète de <a href="/fr/docs/templates" title="/fr/docs/templates">toutes les macros MDN</a>.</p> + +<p>Voir aussi le<a href="/fr/docs/MDN/Contribute/Guidelines/CSS_style_guide" title="/fr/docs/MDN/Contribute/Guidelines/CSS_style_guide"> Guide style CSS </a> pour l'utilisation des styles disponibles.</p> + +<h2 id="Linking">Linking</h2> + +<h3 id="Création_dun_lien_hypertexte_unique">Création d'un lien hypertexte unique</h3> + +<p id="To_another_MDN_page_or_its_section_(anch_SectionOnPage_manch_Link_LinkItem_LinkItemDL)">En général, vous ne devez pas utiliser des macros pour créer des liens arbitraires. Utilisez le <strong> Lien </strong> dans l'interface de l'éditeur pour créer des liens.</p> + +<ul> + <li>La macro {{TemplateLink("Glossary")}} crée un lien vers une entrée du<a href="https://developer.mozilla.org/fr/docs/Glossaire"> glossaire</a> MDN. Cette macro accepte un paramètre obligatoire et deux optionnels: + + <ol> + <li>Le nom d'un terme (comme "HTML").</li> + <li>Le texte à afficher dans l'article au lieu du nom du terme (ce qui devrait être rarement utilisé). {{optional_inline}}</li> + <li>Si ce paramètre est spécifié et est non nul, le style personnalisé normalement appliqué aux liens glossaire n'est pas appliquée. {{optional_inline}}</li> + </ol> + + <p>Examples:</p> + + <ul> + <li>\{{Glossary("HTML")}} yields {{Glossary("HTML")}}</li> + <li>\{{Glossary("CSS", "Cascading Style Sheets")}} yields {{Glossary("CSS", "Cascading Style Sheets")}}</li> + <li>\{{Glossary("HTML", "", 1)}} yields {{Glossary("HTML", "", 1)}}</li> + </ul> + </li> +</ul> + +<h3 id="Liens_vers_des_pages_avec_références">Liens vers des pages avec références</h3> + +<p>Il existe différentes macros pour des liens vers des pages dans les zones de référence spécifiques MDN.</p> + +<ul> + <li>{{TemplateLink("cssxref")}} links to a page in the <a href="/en-US/docs/CSS_Reference" title="en-US/docs/CSS_Reference">CSS Reference</a>. Example: <code>\{{cssxref("cursor")}}</code>, results in: {{ cssxref("cursor") }}.</li> + <li>{{TemplateLink("domxref")}} links to pages in the DOM reference; if you include parentheses at the end, the template knows to display the link to look like a function name. For example, <span class="plain"><span class="nowiki">\{{domxref("document.getElementsByName()")}}</span></span> results in {{ domxref("document.getElementsByName()") }} while <code>\{\{domxref("Node")\}\}</code> results in {{ domxref("Node") }}.</li> + <li>{{TemplateLink("event")}} links to pages in the DOM Event reference, for example: \{{event("change")}} results in {{event("change")}}.</li> + <li>{{TemplateLink("HTMLElement")}} links to an HTML element in the HTML Reference.</li> + <li>{{TemplateLink("htmlattrxref")}} links to an HTML attribute, either a global attribute description if you only specify the attribute name or an attribute associated with a specific element if you specify an attribute name and an element name. For example, <code>\{\{htmlattrxref("lang")\}\} </code>will create this link: {{htmlattrxref("lang")}}.<code> </code> <code>\{\{htmlattrxref("type","input")\}\}</code> will create this link: {{htmlattrxref("type","input")}}.</li> + <li>{{TemplateLink("jsxref")}} links to a page in the <a href="/en-US/docs/Web/JavaScript/Reference" title="en-US/docs/Web/JavaScript/Reference">JavaScript Reference</a>.</li> + <li>{{TemplateLink("SVGAttr")}} links to a specific SVG attribute. For example, <code>\{\{SVGAttr("d")\}\}</code> creates this link: {{SVGAttr("d")}}.</li> + <li>{{TemplateLink("SVGElement")}} links to an SVG element in the SVG Reference.</li> +</ul> + +<h3 id="Liens_vers_des_bugs_et_des_IRC">Liens vers des bugs et des <a href="https://fr.wikipedia.org/wiki/Internet_Relay_Chat">IRC</a></h3> + +<ul> + <li>Bugs + <ul> + <li>{{TemplateLink("bug")}} allows you to link to a bug on bugzilla.mozilla.org easily using this syntax: <code>\{\{Bug(123456)\}\}</code>. This gives you: {{ Bug(123456) }}.</li> + <li>{{TemplateLink("WebkitBug")}} inserts a link to a bug in the WebKit bug database. For example, <code>\{\{WebkitBug(31277)\}\}</code> inserts {{ WebkitBug(31277) }}.</li> + </ul> + </li> + <li>{{TemplateLink("IRCLink")}} inserts a link to the specified IRC channel, complete with a tooltip that says that's what it does and that an IRC client is needed.</li> +</ul> + +<h3 id="Aides_à_la_navigation_pour_les_guides_multi-pages">Aides à la navigation pour les guides multi-pages</h3> + +<p>{{TemplateLink("Previous")}}, {{TemplateLink("Next")}}, and {{TemplateLink("PreviousNext")}} provide navigation controls for articles which are part of sequences. For the single-way templates, the only parameter needed is the wiki location of the previous or next article in the sequence. For {{TemplateLink("PreviousNext")}}, the two parameters needed are the wiki locations of the appropriate articles. The first parameter is for the previous article and the second is for the next article.</p> + +<h2 id="Exemples_de_code">Exemples de code</h2> + +<h3 id="Live_samples">Live samples</h3> + +<ul> + <li>{{TemplateLink("EmbedLiveSample")}} lets you embed the output of a code sample on a page, as described in <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">Live samples</a>.</li> + <li>{{TemplateLink("LiveSampleLink")}} creates a link to a page containing the output of a code sample on a page, as described in <a href="/en-US/docs/MDN/Contribute/Structures/Live_samples">Live samples</a>.</li> +</ul> + +<h3 id="Fichiers_exemples_attachés">Fichiers exemples attachés</h3> + +<ul> + <li>{{TemplateLink("Embed_text")}} template lets you embed an attached text file into the body of your article. This is helpful if you want to have code snippets that are both downloadable but also displayed within the article's content. You may optionally specify a language for syntax highlighting; if you don't specify one, the text is embedded unformatted. The first parameter is the filename of the attachment to embed; the second, if provided, is the language for the syntax highlighter to apply, such as "javascript", "svg", or "cpp".</li> + <li>{{TemplateLink("EmbedSVG")}} embeds an attached XML file as an SVG image, in place on the page. Specify the filename of the attached SVG file. You can use this in tandem with {{TemplateLink("Embed_text")}} to show the source and then the rendered output of the same file.</li> +</ul> + +<h2 id="Génération_de_sidebar_barre_latérale">Génération de sidebar (barre latérale)</h2> + +<p>Modèles pour presque toutes les grandes collection de pages. Ils permettent généralement de revenir à la page principale de référence/Guide/tutoriel et de mettre l'article dans la catégorie appropriée.</p> + +<ul> + <li>{{TemplateLink("CSSRef")}} generates the sidebar for CSS reference pages.</li> + <li>{{TemplateLink("HTMLRef")}} generates the sidebar for HTML reference pages.</li> + <li>{{TemplateLink("APIRef")}} generates the sidebar for Web API reference pages.</li> +</ul> + +<h2 id="La_mise_en_forme_à_usage_général">La mise en forme à usage général</h2> + +<h3 id="Inline_indicators_for_API_documentation">Inline indicators for API documentation</h3> + +<p>{{TemplateLink("optional_inline")}} and {{TemplateLink("ReadOnlyInline")}} are used in API documentation, usually when describing the list of properties of an object or parameters of a function.</p> + +<p>Usage: <code>\{{optional_inline()}}</code> or <code>\{{ReadOnlyInline()}}</code>. Example:</p> + +<dl> + <dt><code>isCustomObject</code> {{ReadOnlyInline()}}</dt> + <dd>Indicates, if <code>true</code>, that the object is a custom one.</dd> + <dt>parameterX {{ optional_inline() }}</dt> + <dd>Blah blah blah...</dd> +</dl> + +<h2 id="Status_and_compatibility_indicators">Status and compatibility indicators</h2> + +<h3 id="Inline_indicators_with_no_additional_parameters">Inline indicators with no additional parameters</h3> + +<h4 id="Non-standard">Non-standard</h4> + +<p>{{TemplateLink("non-standard_inline")}} inserts an in-line mark indicating the API has not been standardized and is not on a standards track.</p> + +<h5 id="Syntax"><strong>Syntax</strong></h5> + +<p><code>\{{non-standard_inline}}</code></p> + +<h5 id="Examples">Examples</h5> + +<ul> + <li>Icon: {{non-standard_inline}}</li> +</ul> + +<h4 id="Experimental">Experimental</h4> + +<p>{{TemplateLink("experimental_inline")}} inserts an in-line mark indicating the API is not widely implemented and may change in the future.</p> + +<h5 id="Syntax_2">Syntax</h5> + +<p><code>\{{experimental_inline}}</code></p> + +<h5 id="Examples_2"><code>Examples</code></h5> + +<ul> + <li>Icon: {{experimental_inline}}</li> +</ul> + +<h3 id="Inline_indicators_that_support_specifying_the_technology">Inline indicators that support specifying the technology</h3> + +<p>In these macros the parameter (when specified) should be one of the strings "html", "js", "css", or "gecko", followed by the version number.</p> + +<h4 id="Deprecated">Deprecated</h4> + +<p>{{TemplateLink("deprecated_inline")}} inserts an in-line deprecated mark to discourage the use of an API that is officially deprecated. <strong>Note:</strong> "Deprecated" means that the item should no longer be used, but still functions. If you mean that it no longer works at all, use the term "obsolete."</p> + +<p>Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).</p> + +<h5 id="Syntax_3">Syntax</h5> + +<p><code>\{{deprecated_inline}}</code> or<code> \{{deprecated_inline("gecko5")}}</code></p> + +<h5 id="Examples_3">Examples</h5> + +<ul> + <li>Icon: {{deprecated_inline}}</li> + <li>Badge: {{deprecated_inline("gecko5")}}</li> +</ul> + +<h4 id="Obsolete">Obsolete</h4> + +<p>{{TemplateLink("obsolete_inline")}} inserts an in-line obsolete mark to prevent the use of, for example, a function, method or property which is officially obsolete.</p> + +<p>Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).</p> + +<h5 id="Syntax_4">Syntax</h5> + +<p><code>\{{obsolete_inline}}</code> or<code> \{{obsolete_inline("js1.8.5")}}</code></p> + +<h5 id="Examples_4">Examples</h5> + +<ul> + <li>Icon: {{obsolete_inline}}</li> + <li>Badge: {{obsolete_inline("js1.8.5")}}</li> +</ul> + +<h3 id="Template_badges">Template badges</h3> + +<p>These macros are mostly used on the <a href="/en-US/docs/WebAPI">WebAPI</a> page. See {{anch("Creating new badges")}} for information on creating a new badge.</p> + +<h3 id="Page_or_section_header_indicators">Page or section header indicators</h3> + +<p>These templates have the same semantics as their inline counterparts described above. The templates should be placed directly underneath the main page title (or breadcrumb navigation if available) in the reference page. They can also be used to mark up a section on a page.</p> + +<ul> + <li>{{TemplateLink("non-standard_header")}}: <code>\{{Non-standard_header()}}</code> {{ Non-standard_header() }}</li> + <li>{{TemplateLink("SeeCompatTable")}} should be used on pages that provide a "Browser compatibility" section. Example: <code>\{{SeeCompatTable()}}</code> {{ SeeCompatTable() }}</li> + <li>{{TemplateLink("deprecated_header")}}: <code>\{{deprecated_header()}}</code> {{ Deprecated_header() }}</li> + <li>{{TemplateLink("deprecated_header")}} with parameter: <code>\{{deprecated_header("gecko5")}}</code> {{ Deprecated_header("gecko5") }} Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).</li> + <li>{{TemplateLink("obsolete_header")}}: <code>\{{obsolete_header()}}</code> {{ Obsolete_header() }}</li> + <li>{{TemplateLink("obsolete_header")}} with parameter: <code>\{{obsolete_header("gecko30")}}</code> {{ Obsolete_header("gecko30") }} Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).</li> +</ul> + +<h3 id="Indicating_that_a_feature_is_available_in_web_workers">Indicating that a feature is available in web workers</h3> + +<p>The {{TemplateLink("AvailableInWorkers")}} macro inserts a localised note box indicating that a feature is available in a <a href="/en-US/docs/Web/API/Web_Workers_API">Web worker</a> context.</p> + +<h2 id="Version_information_macros">Version information macros</h2> + +<p>These macros are used to indicate that content is relevant only to specific versions of a product.</p> + +<ul> + <li>{{TemplateLink("gecko_minversion_inline")}}: For example: {{ gecko_minversion_inline("100.9") }}</li> + <li>{{TemplateLink("fx_minversion_inline")}}: For example: {{ fx_minversion_inline("100.9") }}</li> +</ul> + +<p>These macros are not shown when the specified version is lower than current gecko release.</p> + +<ul> + <li>{{TemplateLink("gecko_minversion_inline")}}(9.9): {{ gecko_minversion_inline("9.9") }}</li> + <li>{{TemplateLink("fx_minversion_inline")}}(9.9): {{ fx_minversion_inline("9.9") }}</li> +</ul> + +<ol> +</ol> + +<p> </p> + +<ol> +</ol> + +<p> </p> diff --git a/files/fr/mdn/structures/macros/index.html b/files/fr/mdn/structures/macros/index.html new file mode 100644 index 0000000000..19060b70d8 --- /dev/null +++ b/files/fr/mdn/structures/macros/index.html @@ -0,0 +1,40 @@ +--- +title: Macros +slug: MDN/Structures/Macros +translation_of: MDN/Structures/Macros +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">La plate-forme <a href="/fr/docs/projet:MDN/Kuma" title="/fr/docs/projet:MDN/Kuma">Kuma</a> sur laquelle MDN travail, fournit un système de macro, <a href="/docs/fr/projet:MDN/Kuma/KumaScript_guide" title="/docs/fr/projet: MDN/Kuma/KumaScript_guide">KumaScript</a>, ce qui permet de faire une grande variété de choses automatiquement. Cet article fournit des informations sur la façon d'invoquer les macros MDN dans les articles.</span></p> + +<p>Le <a href="/docs/fr/projet:MDN/Kuma/KumaScript_guide" title="/fr/docs/projet:MDN/Kuma/KumaScript_guide ">Guide KumaScript</a> offre un regard en profondeur sur la façon d'utiliser des macros MDN, cette section est plus qu'un bref aperçu. Si vous avez déjà lu la section ci-dessus sur {{SectionOnPage ("/docs/fr/projet:MDN/Contribuer/Editor_guide/Links", "Utiliser les liens macros")}}, vous êtes un peu familiers avec le concept.</p> + +<h2 id="Comment_les_macros_sont-elle_mises_en_œuvre">Comment les macros sont-elle mises en œuvre</h2> + +<p>Macros sur MDN sont mis en œuvre en utilisant le serveur exécuté <a href="/fr/docs/Web/JavaScript">JavaScript</a> code, interprété à l'aide de <a>Node.js</a>. En plus de cela, nous avons un certain nombre de bibliothèques, que nous avons mis en place pour fournir des services et des fonctionnalités orientées wiki, les macros interagissent avec la plate-forme wiki et avec son contenu. Si vous voulez en apprendre davantage, consultez le <a href="/docs/fr/projet:MDN/Kuma/KumaScript_guide">guide KumaScript</a>; le <a href="/docs/fr/projet:MDN/Kuma/KumaScript_reference">KumaScript reference</a> fournit des détails sur les bibliothèques et autres API KumaScript que nous avons mis en œuvre.</p> + +<h2 id="Utiliser_une_macro_dans_le_contenu">Utiliser une macro dans le contenu</h2> + +<p>Pour réellement utiliser une macro, vous placez simplement l'appel à la macro dans une paire de doubles acolades, avec ses paramètres, le cas échéant, entre parenthèses:</p> + +<pre class="notranslate">\{{macroname(parameter-list)}}</pre> + +<p>Quelques notes sur les appels de macro:</p> + +<ul> + <li>Les noms de macros sont sensibles à la casse, mais une tentative est faite pour corriger ces erreurs communes; vous pouvez utiliser tout en minuscules, même si le nom de la macro utilise des majuscules en son sein, et vous pouvez débuter par une majuscule une macro dont le nom commence normalement par une lettre minuscule.</li> + <li>Les paramètres sont séparés par des virgules.</li> + <li>Si il n'y a pas de paramètres, vous pouvez laisser les parenthèses ou les enlever; <code>\{{macroname()}} </code> et <code>\{{macroname}}</code> sont identiques.</li> + <li>Les paramètres numériques peuvent être entre guillemets, ou non (cependant, si vous avez un numéro de version avec plusieurs décimales, il doit être entre guillemets).</li> + <li>Si vous obtenez des erreurs, consultez votre code attentivement. Si vous ne pouvez toujours pas à comprendre ce qui se passe, voir <a href="/fr/docs/MDN/Kuma/Troubleshooting_KumaScript_errors">Dépannage des erreurs KumaScript</a>.</li> +</ul> + +<p>Les macros sont mis en cache; pour tout ensemble de valeurs d'entrée (les paramètres et les valeurs environnementales telles que l'URL pour laquelle la macro a été exécutée), les résultats sont stockés et réutilisés. Cela signifie que la macro est que effectivement parcourue que lorsque les entrées changent.</p> + +<div class="note"> +<p><strong>Remarque:. </strong> Vous pouvez forcer toutes les macros d'une page à être réévalué avec un shift-reload.</p> +</div> + +<p>Les macros peuvent être aussi simple que d'insérer un plus grand bloc de texte ou d'échange dans le contenu d'une autre partie du MDN, ou aussi complexe que la construction de tout un index du contenu en cherchant dans des parties du site, coiffer la sortie, et en ajoutant des liens.</p> + +<p>Vous pouvez lire sur nos macros les plus couramment utilisés sur le <a href="/fr/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros">couramment utilisés</a>; aussi, il y a un <a href="https://developer.mozilla.org/fr/docs/templates">la liste complète de toutes les macros</a> ici. La plupart des macros ont intégré dans la documentation eux, comme des commentaires en haut.</p> + +<p>{{EditorGuideQuicklinks}}</p> diff --git a/files/fr/mdn/structures/tables_de_compatibilité/index.html b/files/fr/mdn/structures/tables_de_compatibilité/index.html new file mode 100644 index 0000000000..cb334e51c4 --- /dev/null +++ b/files/fr/mdn/structures/tables_de_compatibilité/index.html @@ -0,0 +1,503 @@ +--- +title: Tables de compatibilité +slug: MDN/Structures/Tables_de_compatibilité +tags: + - Compatibilité + - Documentation + - Guide + - MDN + - Navigateurs +translation_of: MDN/Structures/Compatibility_tables +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">MDN a un format standard pour les tables de compatibilité de notre documentation du web ouvert ; c'est-à-dire la documentation de technologies comme le DOM, HTML, CSS, JavaScript, SVG etc. partagées par tous les navigateurs. Cet article explique comment utiliser nos fonctionnalités pour ajouter des données de compatibilité aux pages MDN.</p> + +<div class="warning"> +<p><strong>Important </strong>: <strong><em>La façon dont les données sont générées a changé</em></strong>. Historiquement, nos tables ont été insérées sur la page et les données ont été renseignées manuellement. Ceci est inefficace, rend la maintenance difficile et rend les données inflexibles. Par conséquent, nous migrons les données de notre navigateur pour les stocker dans un référentiel de données (voir <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>) et générer les tables par programme.<br> + <br> + Dans ce guide, nous documentons la nouvelle façon d'ajouter des données aux tables de compatibilité pour MDN, mais nous avons conservé la documentation à l'ancienne, car vous pourrez voir des tables manuelles sur MDN pendant un moment. Si vous avez besoin de la documentation ancienne, voyez notre article <a href="https://developer.mozilla.org/fr/docs/MDN/Contribute/Structures/Old_compatibility_tables">Anciennes tables de compatibilité</a>.</p> +</div> + +<div class="note"> +<p><strong>Note </strong>: Si vous avez besoin d'aide sur les étapes de ce guide, n'hésitez pas à nous contacter sur le <a href="https://discourse.mozilla-community.org/c/mdn">forum de discussion MDN</a> (en).</p> +</div> + +<h2 id="Comment_accéder_au_dépôt_de_données">Comment accéder au dépôt de données</h2> + +<p>Les données sont stockées dans un dépôt de GitHub — voir <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>. Pour y accéder, vous devez obtenir un compte GitHub, réaliser une branche du browser-compat-data sur votre propre compte, puis cloner votre branche sur votre machine locale.</p> + +<h2 id="Choisir_une_fonctionnalité_pour_y_ajouter_des_données">Choisir une fonctionnalité pour y ajouter des données</h2> + +<p>Tout d'abord, cherchez une fonctionnalité pour laquelle vous souhaitez ajouter des données de navigateur. Cela peut être un élément HTML, une propriété CSS, une fonctionnalité du langage JS ou une interface d'API JS, par exemple. Nous aimerions vous encourager à travailler sur les fonctionnalités de l'API, car nous avons déjà des personnes travaillant sur HTML, JS et CSS. Vous pouvez trouver le statut des fonctionnalités qui ont besoin de leurs données en ajoutant au dépôt sur notre tableur <a href="https://docs.google.com/spreadsheets/d/1ivgyPBr9Lj3Wvj5kyndT1rgGbX-pGggrxuMtrgcOmjM/edit#gid=926663640">Browser Compat Data migration</a> (<em>migration des données des tables de compatibilité des navigateurs</em>).</p> + +<p>Le processus d'utilisation est le suivant :</p> + +<ol> + <li>Allez-y et choisissez une fonctionnalité qui n'est pas déjà travaillée ou complète. Inscrivez votre nom dans la colonne "Who" (<em>qui</em>), de préférence avec votre nom d'utilisateur MDN afin que nous puissions trouver votre adresse e-mail et vous contacter si nécessaire.</li> + <li>Si la fonctionnalité sur laquelle vous souhaitez travailler n'est pas déjà répertoriée dans la feuille de calcul, ajoutez-y des lignes à un emplacement approprié, en copiant le format qui s'y trouve déjà. Vous devez également utiliser la même granularité (par exemple, par élément pour HTML, par propriété ou sélecteur pour CSS, par objet pour JS, par interface pour API).</li> + <li>Une fois que vous avez commencé à ajouter des données, mettez le statut "In progres" (<em>En cours</em>).</li> + <li>Une fois que vous avez ajouté les données et soumis une demande d'extraction au dépôt principal, attribuez le statut "PR done".</li> + <li>Au fur et à mesure que vos données sont fusionnées au rapport, ajoutées au paquet npm, mettez à jour le statut si nécessaire.</li> + <li>Une fois que vous avez mis à jour les pages de documentation pour votre fonctionnalité afin d'utiliser la nouvelle macro pour générer dynamiquement la table de données appropriée sur chaque page, définissez l'état sur "Article mis à jour". À ce stade, vous avez terminé.</li> +</ol> + +<h2 id="Préparation_à_lajout_de_données">Préparation à l'ajout de données</h2> + +<p>Avant d'ajouter de nouvelles données, vous devez vous assurer que votre branche est à jour avec le dépôt principal (le même contenu), créer une nouvelle branche dans votre embranchement pour contenir vos ajouts, puis récupérer cette branche dans votre clone local pour pouvoir commencer à y travailler :</p> + +<p>Regardons un moyen simple de nous assurer que votre fourche est à jour :</p> + +<h3 id="Ajout_dun_remote_au_dépôt_principal_navigateur-compat-données">Ajout d'un "remote" au dépôt principal navigateur-compat-données</h3> + +<p>Accédez à votre clone local de la branche dans votre terminal / ligne de commande, et ajoutez un"remote" pointant vers le dépôt principal (en amont) comme ceci (vous n'avez besoin de le faire qu'une seule fois):</p> + +<pre class="brush: bash notranslate">git remote add upstream https://github.com/mdn/browser-compat-data.git</pre> + +<p>Si vous n'êtes pas sûr d'y être parvenu, vous pouvez vérifier quels "remotes" votre dépôt utilise.</p> + +<pre class="brush: bash notranslate">git remote -v</pre> + +<h3 id="Mise_à_jour_de_votre_branche_avec_le_contenu_du_remote">Mise à jour de votre branche avec le contenu du "remote"</h3> + +<p>Maintenant, chaque fois que vous voulez mettre à jour votre branche, vous pouvez le faire en :</p> + +<ol> + <li> + <p>Vous assurant que vous êtes dans la branche maîtresse :</p> + + <pre class="brush: bash notranslate"> <code class="language-bash">git checkout master</code></pre> + </li> + <li> + <p>Allant chercher le contenu du dépôt à jour avec la commande suivante :</p> + + <pre class="brush: bash notranslate"> <code class="language-bash">git fetch upstream</code></pre> + </li> + <li> + <p>Rebasant le contenu de votre branche maîtresse avec le contenu du dépôt principal :</p> + + <pre class="brush: bash notranslate"> <code class="language-bash">git rebase upstream/master</code> </pre> + </li> + <li> + <p>poussant ces mises à jour de votre branche distante en utilisant ce :</p> + + <pre class="brush: bash notranslate"> <code class="language-bash">git push -f</code> +</pre> + </li> +</ol> + +<h3 id="Création_dune_nouvelle_branche_pour_y_travailler">Création d'une nouvelle branche pour y travailler</h3> + +<p>Ensuite, allez sur votre fourche distante (elle doit être à <code>https://github.com/<em>your-username</em>/browser-compat-data</code>) et créer une nouvelle branche <span class="short_text" id="result_box" lang="fr"><span>pour stocker vos modifications pour cet ajout de données</span></span>. Ceci peut être fait en:</p> + +<ol> + <li>Cliquant sur le bouton "Branch: Master".</li> + <li>Saisissant le nom de votre nouvelle branche dans le champ texte "Find or create a branch...".</li> + <li>Cliquant sur le bouton "Create branch <em>name-of-branch</em> from Master" qui vient d'être généré.</li> +</ol> + +<p>Par exemple, si vous vouliez ajouter des données pour l'API WebVR, vous devriez créer une branche nommée "webvr".</p> + +<h3 id="Aller_sur_la_nouvelle_branche">Aller sur la nouvelle branche</h3> + +<p>A ce stade, retournez dans votre terminal / ligne de commande, et mettez à jour la copie de votre fourche locale pour inclure votre nouvelle branche en utilisant la commande suivante:</p> + +<pre class="brush: bash notranslate">git pull</pre> + +<p>Maintenant allez sur votre nouvelle branche en utilisant:</p> + +<pre class="brush: bash notranslate">git checkout <em>-b name-of-branch</em></pre> + +<p>Vous devriez maintenant être prêt à ajouter vos données!</p> + +<h2 id="Ajouter_les_données">Ajouter les données</h2> + +<p>Pour ajouter les données, vous devez créer un ou des nouveaux fichiers pour y stocker les données de compatibilité. Les fichiers que vous devez créer diffèrent, selon la technologie sur laquelle vous travaillez:</p> + +<ul> + <li>HTML: Un fichier par élément HTML, contenu dans <a href="https://github.com/mdn/browser-compat-data/tree/master/html/elements">browser-compat-data/html/elements</a>. Le fichier doit être nommé avec le nom de l'élément, tout en minuscules, ex. <code>div.json</code>.</li> + <li>CSS: Un fichier par propriété ou sélecteur CSS, contenu dans le répertoire approprié (voir <a href="https://github.com/mdn/browser-compat-data/tree/master/css">browser-compat-data/css</a>). Le fichier doit être nommé avec le nom de la fonctionnalité, tout en minuscules, ex. <code>background-color.json</code>, ou <code>hover.json</code>.</li> + <li>JS: Un fichier par objet JS, contenu dans <a href="https://github.com/mdn/browser-compat-data/tree/master/javascript/builtins">browser-compat-data/javascript/builtins</a>. Le fichier doit être nommé avec le nom de l'objet, en respectant la casse, ex. <code>Date.json</code> ou <code>InternalError.json</code>.</li> + <li>APIs: un fichier par interface contenu dans l'API, mis dans <a href="https://github.com/mdn/browser-compat-data/tree/master/api">browser-compat-data/api</a>. Chaque fichier doit être nommé avec le nom exact de l'interface, en respectant la casse, ex. L'API WebVR a <code>VRDisplay.json</code>, <code>VRDisplayCapabilities.json</code>, etc.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: Vous remarquerez que le dépôt contient aussi des données pour les <a href="/fr/Add-ons/WebExtensions">Extensions de navigateurs</a> et pour <a href="/fr/docs/Web/HTTP">HTTP</a>. <span id="result_box" lang="fr"><span>Ces ensembles de données sont esssentiellement finis en l'état, mais il faudra peut-être ajouter d'autres fonctionnalités à l'avenir.</span></span></p> +</div> + +<p>Chaque fichier que vous créez doit suivre le modèle défini dans le schéma contenu dans notre dépôt; vous pouvez voir la <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md">description détaillée du schema ici</a>.</p> + +<h3 id="Structure_basique_des_données_de_compatibilité">Structure basique des données de compatibilité</h3> + +<p>Prenons un exemple. Les fichiers JSON de propriété CSS ont par exemple besoin de la structure de base suivante:</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "border-width": { + "__compat": { + ... + } + } + } + } +}</pre> + +<p>Vous avez l'objet <code>css</code>, à l'intérieur duquel vous avez l'objet <code>properties</code>. A l'intérieur de l'objet <code>properties</code>, vous avez besoin d'un membre pour chacunes des fonctionnalités dont vous voulez définir les données. Chacun de ces membres a un membre <code>__compat</code>, à l'intérieur duquel les données vont.</p> + +<p>Les données ci-dessus se trouvent dans le fichier <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a> — <span id="result_box" lang="fr"><span>comparez les à la </span></span> <a href="/fr/docs/Web/CSS/border-width#Compatibilit%C3%A9_des_navigateurs">table de support de border-width disponible sur MDN</a>.</p> + +<p>D'autres types de fonctionnalités fonctionnent sur le même principe, mais avec des noms d'objets différents:</p> + +<ul> + <li>Les sélecteurs CSS fonctionnent essentiellement de la même manière que les proprités CSS, sauf que la structure de l'objet de plus haut niveau est <code>css.selectors</code> à la place de <code>css.properties</code>. Voir <a href="https://github.com/mdn/browser-compat-data/blob/master/css/selectors/cue.json">cue.json</a> pour un exemple.</li> + <li>Les données HTML fonctionnent essentiellement de la même manière, sauf que la structure de l'objet de plus haut niveau est <code>html.elements</code>. Voir <code>article.json</code> pour un exemple.</li> + <li>La structure d'objet de plus haut niveau pour les objets intégrés JS est <code>javascript.builtins</code>; voir <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Array.json">Array.json</a> pour un exemple.</li> +</ul> + +<div> +<p>Dans les pages HTML, CSS, et JS, vous n'avez normalement besoin que d'une seule fonctionnalité. Les interfaces d'API fonctionnent légèrement différement — elles ont toujours de multiples sous caractéristiques (voir {{anch("Sub-features")}}, ci-dessous).</p> + +<h3 id="Structure_de_base_à_lintérieur_dune_fonctionnalité">Structure de base à l'intérieur d'une fonctionnalité</h3> + +<p>Dans un membre <code>__compat</code>, vous devez inclure les membres suivants:</p> + +<ul> + <li><code>mdn_url</code>: Contient l'URL de la page de référence pour cette fonctionnalité sur MDN. Notez qu'elle doit être écrit sans le répertoire de la locale, ex. <code>/docs/...</code> et non <code>/docs/en-US/...</code> (ou autre). Il est ajouté par une macro lorsque les données sont mises sur la page, à des fins de localisation.</li> + <li><code>support</code>: <span id="result_box" lang="fr"><span>Contient des membres indiquant les informations de support du navigateur pour cette fonctionnalité, dans les différents navigateurs que nous souhaitons indiquer.</span></span></li> + <li><code>status</code>: Contient des membres indiquant l'état de suivi des normes pour cette fonctionnalité.</li> +</ul> + +<p>Les noms des membres pour le navigateur sont définis dans le schéma (voir <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#browser-identifiers">Browser identifiers</a>). Vous devez utiliser la liste complète des identifiants actuellement définis. Si vous souhaitez ajouter un navigateur, parlez-nous en d'abord, <span id="result_box" lang="fr"><span>car cela pourrait avoir un impact important et ne devrait pas être fait sans une réflexion approfondie.</span></span></p> + +<p>Dans un fichier de base de compatibilité de navigateur, vous n'avez qu'à inclure "version_added" dans les membres de l'identifiant de navigateur (nous reviendrons plus tard sur {{anch("Advanced cases")}}). <span id="result_box" lang="fr"><span>Les différentes valeurs que vous pouvez inclure sont les suivantes:</span></span></p> + +<ul> + <li>Un numéro de version: Si vous connaissez la version exacte à partir de laquelle le navigateur supporte cette fonctionnalité, utilisez une chaîne de caractères représentant ce nombre, ex. "47".</li> + <li><code>true</code>: Si un navigateur supporte la fonctionnalité mais que vous ne connaissez pas la version exacte, utilisez la valeur <code>true</code>. Ceci équivaut à l'appel de la macro <code>\{{CompatVersionUnknown}}</code> dans les anciennes tables manuelles.</li> + <li><code>false</code>: Si un navigateur ne supporte pas la fonctionnalité, utilisez la valeur <code>false</code>. Ceci équivaut à l'appel de la macro <code>\{{CompatNo}}</code> dans les anciennes tables manuelles.</li> + <li><code>null</code>: Si vous ne savez pas si un navigateur supporte ou non une fonctionnalité, utilisez la valeur <code>null</code>. Ceci équivaut à l'appel de la macro <code>\{{CompatUnknown}}</code> dans les anciennes tables manuelles.</li> +</ul> + +<p>A l'intérieur du membre <code>status</code>, vous inclurez trois sous-membres:</p> + +<ul> + <li> "experimental": Ceci doit être mis à <code>true</code> si la fonctionnalité est <a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">expérimentale</a>, ou <code>false</code> dans les autres cas.</li> + <li>"standard_track": Ceci doit être mis à <code>true</code> si la fonctionnalité est en cours de standardisation (le plus souvent W3C/WHATWG, mais il y a aussi d'autres efforts de standardisation tels que Khronos, TC39, etc.) ou <code>false</code> dans les autres cas.</li> + <li>"deprecated": Ceci doit être mis à <code>true</code> si la fonctionnalité est <a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">dépréciée</a>, ou <code>false</code> dans les autres cas.</li> +</ul> + +<p>Les données pour la propriété <a href="/fr/docs/Web/CSS/border-width#Compatibilité des navigateurs">border-width</a> (voir aussi <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a>) sont présentées ci-dessous à titre d'exemple:</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="Ajouter_une_description">Ajouter une description</h4> + +<p>Il y a un quatrième membre, optionnel, qui peut être placé à l'intérieur du membre __compat — <code>description</code>. Ceci peut être utilisé pour inclure une description, compréhensible par les humains, de cette fonctionnalité. Vous ne devez l'inclure que s'il est difficile de voir de quoi il s'agit en ne regardant que les données. Par exemple, il peut ne pas être évident qu'il s'agit d'un constructeur en ne regardant que la structure des données, vous pouvez donc ajouter une description comme:</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="Sub-features">Sub-features</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="Adding_data_Advanced_cases">Adding data: Advanced cases</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="Including_a_vendor_prefix">Including a vendor prefix</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. imagine you had a feature that was supported with a <code>-moz-</code> prefix in Firefox. To specify this in the compat data, you'd need to add a "prefix" submember inside the relevant "firefox" submember. It would look something like this:</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="Including_a_version_where_support_was_removed">Including a version where support was removed</h3> + +<p>Sometimes a feature will be added in a certain browser version, but then removed again as the feature is deprecated. This can be easily represented using the "version_removed" submember, which takes as its value a string representing the version number it was removed on. For example:</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="Including_an_alternative_name">Including an alternative name</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="Pushing_a_change_back_to_the_main_repo">Pushing a change back to the main repo</h2> + +<p>Once you are finished with adding your compat data, you should first test it using the following commands:</p> + +<ul> + <li><code>npm run lint</code> — tests all the compat data to make sure the JSON is valid, and is written in the correct style, for example correct indentation, no missing commas, etc. It will print out a long list of file names and test results; 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="Inserting_the_data_into_MDN_pages">Inserting the data into MDN pages</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>The compatibility table on this page is generated from structured data. +If you'd like to contribute to the data, please check out +<a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> +and send us 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>The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> +</div> + +<p>{{Compat("api.VRDisplay.capabilities")}}</p> + +<div class="note"> +<p><strong>Note</strong>: The filenames often match the labels given to the interfaces inside the JSON structures, but it is not always the case. When the macro calls generate the tables, they walk through all the files until they find the relevant JSON to use, so the filenames are not critical. Saying that, you should always name them as intuitively as possible.</p> +</div> |