diff options
Diffstat (limited to 'files/ko/mdn/structures')
| -rw-r--r-- | files/ko/mdn/structures/api_references/api_reference_sidebars/index.html | 114 | ||||
| -rw-r--r-- | files/ko/mdn/structures/api_references/index.html | 58 | ||||
| -rw-r--r-- | files/ko/mdn/structures/compatibility_tables/index.html | 496 | ||||
| -rw-r--r-- | files/ko/mdn/structures/index.html | 18 | ||||
| -rw-r--r-- | files/ko/mdn/structures/macros/commonly-used_macros/index.html | 220 | ||||
| -rw-r--r-- | files/ko/mdn/structures/macros/index.html | 46 |
6 files changed, 952 insertions, 0 deletions
diff --git a/files/ko/mdn/structures/api_references/api_reference_sidebars/index.html b/files/ko/mdn/structures/api_references/api_reference_sidebars/index.html new file mode 100644 index 0000000000..fd8be5585d --- /dev/null +++ b/files/ko/mdn/structures/api_references/api_reference_sidebars/index.html @@ -0,0 +1,114 @@ +--- +title: API 레퍼런스의 사이드바 +slug: MDN/Structures/API_references/API_reference_sidebars +translation_of: MDN/Structures/API_references/API_reference_sidebars +--- +<div>{{MDNSidebar}}</div> + +<p class="summary">API 레퍼런스 문서에는 수정 가능한 사이드바 를 추가할 수 있습니다. 이 사이드바에 인터페이스, 튜토리얼, 혹은 API와 관련된 자료 링크를 노출합니다. 그 사용법을 설명합니다. </p> + +<h2 id="뭘_해야_하나요">뭘 해야 하나요?</h2> + +<p>사이드바 생성은 다음 세 단계로 나뉩니다. </p> + +<ol> + <li>API 레퍼런스 페이지를 만듭니다. </li> + <li><a href="https://github.com/mdn/kumascript">KumaScript 레파지토리</a>의 GroupData.json 데이터 파일에 그 API를 위한 엔트리를 추가합니다. </li> + <li>사이드바가 필요한 페이지에 \{{APIRef}} 메크로를 추가합니다.</li> +</ol> + +<p><a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>를 샘플로 삼아서 단계별로 살펴 보겠습니다. </p> + +<h3 id="신규_API_레퍼런스_페이지_만들기">신규 API 레퍼런스 페이지 만들기</h3> + +<p>페이지에 사이드바를 추가하기 전에 여러분은 페이지를 만들어야 합니다. (자세한건 API 레퍼런스 문서에 필요한건 무엇일까요? 마이드 문서를 보세요)</p> + +<h3 id="GroupData.json에_API의_엔트리를_추가하기">GroupData.json에 API의 엔트리를 추가하기</h3> + +<p><a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a> 파일은 API 레퍼런스 문서의 사이드바 안에 담아야 하는 모든 데이타를 담고 있습니다. API를 파라미터로 주고 \{{APIRef}}메크로를 실행하면, GroupData.json에서 탐색해서 사이드바를 생성하고 페이지에 추가합니다. </p> + +<p>GroupData.json에 엔트리를 추가하려면 다음을 따르세요.</p> + +<ol> + <li><a href="https://github.com/">GitHub</a> 계정이 필요합니다. </li> + <li>KumaScript 레파지토리를 포크뜨고, 작업할 브랜치를 생성하고 로컬에 클론을 뜹니다. </li> + <li>생성한 브랜치로 체크아웃을 하고 작업후 오리진으로 푸시합니다. </li> + <li>MDN 팀이 리뷰할 수 있도록 풀 리퀘스트를 날려주시고, 필요하다 생각이 들면 변경 요청을 주세요.</li> +</ol> + +<p>GitHub 사용법을 잘 모르겠으면 <a href="/ko/docs/MDN/Contribute/Structures/Compatibility_tables#The_new_way_The_browser_compat_data_repo_and_dynamic_tables">호환성 테이블 가이드</a> 문서를 참고하세요. 자세한 내용이 있습니다. </p> + +<p><a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData.json</a>은 KumaScript 레파지토리의 macros 폴더 안에 있습니다. 파일을 열어보면 API별로 자기 내용을 가진 거대한 JSON 구조체를 볼 수 있습니다. 키는 API명이고, 값은 사이드바 링크를 생성하기 위해 정의된 하위 멤버를 담은 객체입니다. </p> + +<p><a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> 를 예로 들면 일치하는 GroupData.json의 엔트리가 다음과 같습니다. </p> + +<pre class="brush: json notranslate">"Fetch API": { + "overview": [ "Fetch API"], + "interfaces": [ "Body", + "Headers", + "Request", + "Response", + "FetchController", + "FetchObserver", + "FetchSignal", + "ObserverCallback" ], + "methods": [ "WindowOrWorkerGlobalScope.fetch()" ], + "properties": [], + "events": [] +}, +</pre> + +<p>보다시피 키 명을 "Fetch API"으로 명명 하고 있고, 하위 멤버들을 담은 객체를 가지고 있습니다. </p> + +<h4 id="GroupData_엔트리에_담긴_하위_멤버들">GroupData 엔트리에 담긴 하위 멤버들</h4> + +<p>GroupData 엔트리에 추가할 수 있는 하위 멤버 목록입니다. </p> + +<p>리스트업된 하위 멤버값 대부분은 링크걸 텍스트와 링크 생성을 위해 메인 API 색인 페이지(https://developer.mozilla.org/<em><language-code></em>/docs/Web/API) 끝에 추가될 슬러그입니다. 예를 들어 en-US 로케일에서 "Body"는 아래 링크를 만듭니다. </p> + +<pre class="brush: html notranslate"><li><a href="https://developer.mozilla.org/en-US/docs/Web/API">Body</a></li> +</pre> + +<p>몇가지 예외가 있습니다.. 예를 들어 "guides" 하위 멤버는 가이드/튜토리얼 관련 링크를 정의할 하나이상의 링크 정보(타이틀과 슬러그)를 갖고 있는데, 이경우 슬러그는 MDN 어디든 추가될 수 있도록 MDN 문서 루트(https://developer.mozilla.org/<em><language-code></em>/docs)의 끝에 추가됩니다. </p> + +<p>사용가능한 멤버들입니다. 로케일은 en-US로 가정합니다. </p> + +<ol> + <li> + <p><code>"overview"</code> — 값은 배열이고, API 오버뷰 문서의 슬러그입니다. 하나인 경우 "Fetch API"이면 다음 같은 링크를 만듭니다. <a href="/en-US/docs/Web/API/Fetch_API">https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API</a>.</p> + </li> + <li> + <p><code>"interfaces"</code> — 해당 API의 인터페이스 전체 목록을 담은 배열 입니다. 값이 "Body"이면 다음 과 같은 링크를 만듭니다. <a href="/en-US/docs/Web/API/Body">https://developer.mozilla.org/en-US/docs/Web/API/Body</a>.</p> + </li> + <li> + <p><code>"methods"</code> — the value is an array that should contain any methods the spec adds to interfaces associated with other APIs, such as instantiation methods created on {{domxref("Navigator")}} or {{domxref("Window")}}. If there are a huge number of methods, you might want to consider only listing the most popular ones, or putting them first in the list. "WindowOrWorkerGlobalScope.fetch()" results in a link being made to <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch</a>.</p> + </li> + <li> + <p><code>"properties"</code> — the value is an array that should contain all of the properties associated with the API. This can include properties that are members of interfaces defined in the API spec, and properties the API defines on other interfaces. If there are a huge number of properties, you might want to consider only listing the most popular ones, or putting them first in the list. "Headers.append" results in a link being made to <a href="/en-US/docs/Web/API/Headers/append">https://developer.mozilla.org/en-US/docs/Web/API/Headers/append</a>.</p> + </li> + <li> + <p><code>"events"</code> — the value is an array that should contain all of the events associated with the API, defined in the API spec, or elsewhere. If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list. "animationstart" results in a link being made to <a href="/en-US/docs/Web/Events/animationstart">https://developer.mozilla.org/en-US/docs/Web/Events/animationstart</a>.</p> + </li> + <li> + <p><code>"guides"</code> — the value is an array containing one or more objects that define links to guides explain how to use the API. Each object contains two submembers — "url", which contains the partial URL pointing to the guide article, and "title", which defines the link test for the link. As an example, the following object:</p> + + <pre class="brush: json notranslate">{ "url": "/docs/Web/API/Detecting_device_orientation", +"title": "Detecting device orientation" }</pre> + + <p>Creates a link with the title "Detecting device orientation", which points to <a href="/en-US/docs/Web/API/Detecting_device_orientation">https://developer.mozilla.org/en-US/docs/Web/API/Detecting_device_orientation</a>.</p> + </li> +</ol> + +<h3 id="API_Submembers_and_Tags">API Submembers and Tags</h3> + +<p>Some submembers are automatically discovered from child pages, based on page tags. Pages under the top-level API are crawled each time the sidebar is rendered, and entries are automatically created for methods ("Method" tag), properties ("Property" tag), and constructors ("Constructor" tag).</p> + +<p>Submembers are automatically decorated with warning icons based on tags as well. Decorations are added for experimental ("Experimental" tag), non-standard ("Non Standard" or "Non-standard" tag), deprecated ("Deprecated" tag), or obsolete ("Obsolete" tag) submembers.</p> + +<p>Further information about tag-based processing is available <a href="https://github.com/mdn/kumascript/blob/master/macros/APIRef.ejs">in the APIRef source</a>.</p> + +<h3 id="Inserting_the_sidebar_in_your_pages">Inserting the sidebar in your pages</h3> + +<p>Once you've added an entry for your API into GroupData.json, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the \{{APIRef}} macro, which takes the name you used for your API in GroupData as a parameter. As an example, the <a href="/en-US/docs/Web/API/WebVR_API">WebVR API</a>'s sidebar is included in its pages with the following:</p> + +<p>\{{APIRef("WebVR API")}}</p> diff --git a/files/ko/mdn/structures/api_references/index.html b/files/ko/mdn/structures/api_references/index.html new file mode 100644 index 0000000000..c521b5f4ec --- /dev/null +++ b/files/ko/mdn/structures/api_references/index.html @@ -0,0 +1,58 @@ +--- +title: API 레퍼런스 +slug: MDN/Structures/API_references +tags: + - API + - 가이드 + - 레퍼런스 + - 봉사 +translation_of: MDN/Structures/API_references +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">웹에서 사용 가능한 기술 중 클라이언트 측 자바스크립트 API가 차지하는 비중은 상당히 높습니다. 그렇기 때문에, MDN은 API의 기능과 사용법을 설명하는 광범위한 참조 자료를 보유하고 있습니다. 이 안내 문서는 이런 API 참고 자료를 MDN에 생성하는 방법을 설명합니다. </p> + +<h2 id="사전_준비">사전 준비</h2> + +<p>API를 문서화 하려면 다음이 가능해야 합니다. </p> + +<ol> + <li>최종 버전의 스팩: 그 API를 다루는 스팩의 단계가 W3C 최종 권고안인지, 초안인지는 관계없지만, 최종 버전의 스팩을 참조해야 합니다. 보통은 웹에서 쉽게 검색할 수 있으며, 그 스팩의 모든 버전의 문서에는 보통 최종 버전으로의 링크가 "lastest draft"등의 제목으로 걸려있습니다. </li> + <li>최신 모던 브라우저: 여러분이 문서화할 기능들은 정식 버전이 아닌 <a href="https://nightly.mozilla.org/">파이어폭스 나이틀리</a>/<a href="https://www.google.com/intl/en/chrome/browser/canary.html">크롬 카나리</a>와 같은 실험 버전에서 지원할 가능성이 높습니다. 앞서가는 실험적인 API를 문서화 한다면 더욱 이런 버전의 브라우저를 사용해야 합니다. </li> + <li>데모/블로그 글/다른 정보: 가능하면 최대한 정보를 찾아보세요. 그 API가 어떻게 동작하는지 스스로 익숙히는 좋은 출발점이 됩니다. 주 인터페이스, 프로퍼티, 메서드가 무엇인지, 주요한 유즈 케이스가 어떻게 되는지 배우고, 어떻게 그 기능을 간단시 서술할지 고민하세요. </li> + <li>기술문의 활용: API 표준화에 참여했거나 브라우저에서 그 스팩을 구현한 누군가에게 기술문의를 할 수 있는 나만의 연락처를 찾을 수 있다면 정말 좋습니다. 다음을 참고하세요. + <ul> + <li>관련 업무를 보는 회사에서 근무한다면 사내 주소록</li> + <li>그 API에 대한 토론 채널에 참여한 공개 메일링 리스트. 모질라의 <a href="https://lists.mozilla.org/listinfo/dev-platform">dev-platform</a>, <a href="https://lists.mozilla.org/listinfo/dev-webapi">dev-webapi</a> 목록, <a href="https://lists.w3.org/Archives/Public/public-webapps/">public-webapps</a> 같은 W3C 목록 참고</li> + <li>스팩 문서. 예를 들면 <a href="https://webaudio.github.io/web-audio-api/">Web Audio API 문서</a> 상단에는 저자들의 연락처가 있음.</li> + </ul> + </li> +</ol> + +<h2 id="문서_구조">문서 구조</h2> + +<dl> + <dt><a href="/ko/docs/MDN/Contribute/Structures/API_references/What_does_an_API_reference_need">API 레퍼런스 문서에 필요한 것은 무엇일까요? </a></dt> + <dd>이 문서는 완벽한 API 레퍼런스 문서에 필요한 것들을 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Page_types">페이지 타입</a></dt> + <dd>MDN에서 반복적으로 사용되는 페이지 타입들이 있습니다. 이 문서는 그 타입들의 목적을 설명하고 신규 문서를 만들때 사용할 수 있는 템플릿 예제를 제공합니다. </dd> +</dl> + +<h2 id="페이지의_기능">페이지의 기능</h2> + +<p>API 레퍼런스 문서를 위한 페이지 기능을 생성하는 방법을 설명합니다. </p> + +<dl> + <dt><a href="/ko/docs/MDN/Contribute/Structures/API_references/API_reference_sidebars">API 레퍼런스 사이드바</a></dt> + <dd>작성한 MDN API 레퍼런스 문서에 사이드바를 추가할 때, 여러분은 API와 관련된 인터페이스 튜토리얼, 다른 자료 링크를 맘대로 출력할 수 있습니다. 이 문서는 그 방법을 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Syntax_sections">API 문법 섹션</a></dt> + <dd>MDN 참조 문서에서 문법 섹션은 그 기능이 가지고 있는 정확한 문법을 기술한 박스형태를 띄고 있다. (어떤 매개변수가 사용가능한지, 어떤 것이 옵션인지 등) 그 문서는 레퍼런스 문서를 위한 문법 섹션 작성법에 대해 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Code_examples">예제 코드</a></dt> + <dd>웹 플랫폼 기능 사용법을 설명하는 페이지에는 어김없이 많은 예제 코드가 있습니다. 이 문서는 페이지에 예제 코드를 추가하기 위한 각각의 가능한 메카니즘을 기술합니다. 무엇을 언제 사용해야 하는지도 함께요.</dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Specification_tables">스펙 테이블</a></dt> + <dd>MDN의 모든 레퍼런스 페이지는 API나 기술이 정의된 스팩, 또는 그 스팩에 대한 정보를 제공해야 합니다. 이 문서는 테이블의 형태와 제작 방법을 설명합니다. </dd> + <dt><a href="/ko/docs/MDN/Contribute/Structures/Compatibility_tables">호환성 테이블</a></dt> + <dd>MDN은 오픈 웹 문서, 즉 모든 브라우저에서 공유되는 DOM, HTML, CSS, JavaScript, SVG 등과 같은 기술 문서를 위한 호환성 테이블 표준을 가지고 있습니다. 이 문서는 호환성 데이터를 MDN 페이지에 추가하는 기능 사용법을 다룹니다. </dd> +</dl> diff --git a/files/ko/mdn/structures/compatibility_tables/index.html b/files/ko/mdn/structures/compatibility_tables/index.html new file mode 100644 index 0000000000..2d1c19eda8 --- /dev/null +++ b/files/ko/mdn/structures/compatibility_tables/index.html @@ -0,0 +1,496 @@ +--- +title: 호환성 표 +slug: MDN/Structures/Compatibility_tables +translation_of: MDN/Structures/Compatibility_tables +--- +<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/en-US/docs/MDN")}}</div> + +<p class="summary">MDN에는 우리의 열린 웹 문서화(즉 모든 브라우저가 공유하는 DOM, HTML, CSS, JavaScript, SVG 등의 기술에 대한 문서화) 의 호환성 표를 위한 표준 형식이 있습니다. 이 글은 우리의 기능들을 이용하여 MDN 페이지들에 호환성 데이터를 추가하는 방법을 다룹니다.</p> + +<div class="warning"> +<p><strong>중요</strong>: <strong><em>데이터가 생성되는 방법이 바뀌었습니다</em></strong>. 예전에는 페이지에 넣는 표의 값을 수동으로 넣었습니다. 이 방법은 비효율적이고 유지보수를 어렵도록 하며 데이터가 유연하지 못하게 만듭니다. 그래서 브라우저 호환 데이터를 깃허브 레포지토리(주소: <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>)로 옮기고 호환성 표를 코드를 통해 생성하는 방식으로 바꾸었습니다.</p> + +<p>In this guide, we document the new way to add compat data to MDN, but we've still kept documentation covering the old way, as you'll see manual tables on MDN for a while. If you need to see the old documentation, check out our <a href="/en-US/docs/MDN/Contribute/Structures/Old_compatibility_tables">Old compatibility tables</a> article.</p> +</div> + +<div class="note"> +<p><strong>Note</strong>: If you need any help with any steps of this guide, you are welcome to contact us at the <a href="https://discourse.mozilla-community.org/c/mdn">MDN discussion forum</a>.</p> +</div> + +<h2 id="How_to_access_the_data_repo">How to access the data repo</h2> + +<p>The data is stored in a GitHub repo — see <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>. To access it, you need to get a GitHub account, fork the browser-compat-data repo over to your own account, then clone your fork onto your local machine.</p> + +<h2 id="Choosing_a_feature_to_add_data_for">Choosing a feature to add data for</h2> + +<p>First of all, find a feature that you want to add browser-compat-data for. This could be an HTML element, CSS property, JS language feature or JS API interface, for example. We would like to encourage you to work on API features, as we already have people working on HTML, JS, and CSS. You can find the status of features that need their data adding to the repo on our <a href="https://docs.google.com/spreadsheets/d/1ivgyPBr9Lj3Wvj5kyndT1rgGbX-pGggrxuMtrgcOmjM/edit#gid=926663640">Browser Compat Data migration</a> spreadsheet.</p> + +<p>The process for using this is as follows:</p> + +<ol> + <li>Go ahead and choose a feature that is not already being worked on or complete. Put your name in the "Who" column, preferably along with your MDN username so we can find your email address and contact you if we need to.</li> + <li>If the feature you want to work on is not already listed in the spreadsheet, add rows for it in an appropriate place, copying the format that is already there. You should also use the same granularity (e.g. per element for HTML, per property or selector for CSS, per object for JS, per interface for APIs).</li> + <li>Once you've started work on adding the data, put the status to "In progress".</li> + <li>Once you've added the data and submitted a pull request to the main repo, put the status to "PR done".</li> + <li>As your data is merged to the repo, then added to the npm package, update the status as necessary.</li> + <li>Once you've updated the documentation page(s) for your feature to use the new macro to dynamically generate the appropriate data table on each page, set the status to "Article updated". At this point, you are done.</li> +</ol> + +<h2 id="Preparing_to_add_the_data">Preparing to add the data</h2> + +<p>Before adding some new data, you should make sure that your fork is up-to-date with the main repo (it contains the same content), create a new branch inside your fork to contain your additions, then pull that branch into your local clone so you can start working inside it:</p> + +<p>Let's look at a simple way to make sure your fork is to-to-date is as follows:</p> + +<h3 id="Adding_the_main_browser-compat-data_repo_as_a_remote">Adding the main browser-compat-data repo as a remote</h3> + +<p>Go to your local clone of your fork in your terminal/command line, and add a remote pointing to the main (upstream) repo like so (you only need to do this once):</p> + +<pre class="brush: bash notranslate">git remote add upstream https://github.com/mdn/browser-compat-data.git</pre> + +<p>If you are unsure whether you've done this, you can check what remotes your repo has using</p> + +<pre class="brush: bash notranslate">git remote -v</pre> + +<h3 id="Updating_your_fork_with_the_remotes_content">Updating your fork with the remote's content</h3> + +<p>Now, whenever you want to update your fork, you can do so by:</p> + +<ol> + <li> + <p>Making sure you are in the master branch:</p> + + <pre class="brush: bash notranslate">git checkout master</pre> + </li> + <li> + <p>fetching the up-to-date repo contents using the following:</p> + + <pre class="brush: bash notranslate">git fetch upstream</pre> + </li> + <li> + <p>rebasing the contents of your master with the main repo's contents:</p> + + <pre class="brush: bash notranslate">git rebase upstream/master</pre> + </li> + <li> + <p>pushing these updates back to your remote fork using this:</p> + + <pre class="brush: bash notranslate">git push -f</pre> + </li> +</ol> + +<h3 id="Creating_a_new_branch_to_do_your_work_in">Creating a new branch to do your work in</h3> + +<p>Next, go to your remote fork (it will be at <code>https://github.com/<em>your-username</em>/browser-compat-data</code>) and create a new branch to store your changes for this data addition. This can be done by:</p> + +<ol> + <li>Clicking on the "Branch: Master" button.</li> + <li>Entering a new branch name into the "Find or create a branch..." text field.</li> + <li>Pressing the resulting "Create branch <em>name-of-branch</em> from Master" button.</li> +</ol> + +<p>For example, if you were wanting to add data for the WebVR API, you'd create a branch called something like "webvr".</p> + +<h3 id="Switching_to_the_new_branch">Switching to the new branch</h3> + +<p>At this point, go back to your terminal/command line, and update your fork's local clone to include your new branch using the following command:</p> + +<pre class="brush: bash notranslate">git pull</pre> + +<p>Now switch to your new branch using this:</p> + +<pre class="brush: bash notranslate">git checkout<em> name-of-branch</em></pre> + +<p>You should now be ready to start adding your data!</p> + +<h2 id="Adding_the_data">Adding the data</h2> + +<p>To add the data, you need to create a new file or files to store your compat data in. The files you need to create differ, depending on what technology you are working on:</p> + +<ul> + <li>HTML: One file per HTML element, contained in <a href="https://github.com/mdn/browser-compat-data/tree/master/html/elements">browser-compat-data/html/elements</a>. The file should be called the name of the element, all in lower case, e.g. <code>div.json</code>.</li> + <li>CSS: One file per CSS property or selector, contained in the appropriate directory (see <a href="https://github.com/mdn/browser-compat-data/tree/master/css">browser-compat-data/css</a>). The file should be called the name of the feature, all in lower case, e.g. <code>background-color.json</code>, or <code>hover.json</code>.</li> + <li>JS: One file per JS object, contained in <a href="https://github.com/mdn/browser-compat-data/tree/master/javascript/builtins">browser-compat-data/javascript/builtins</a>. The file should be called the exact name of the object, with the casing preserved, e.g. <code>Date.json</code> or <code>InternalError.json</code>.</li> + <li>APIs: One file per interface contained in the API, put in <a href="https://github.com/mdn/browser-compat-data/tree/master/api">browser-compat-data/api</a>. Each file should be called the exact name of the interface, with the casing preserved, e.g. The WebVR API has <code>VRDisplay.json</code>, <code>VRDisplayCapabilities.json</code>, etc.</li> +</ul> + +<div class="note"> +<p><strong>Note</strong>: You'll notice that the repo also contains data for <a href="/en-US/Add-ons/WebExtensions">Browser Extensions</a> and <a href="/en-US/docs/Web/HTTP">HTTP</a>. These data sets are basically finished as they stand, but more features may need to be added in the future.</p> +</div> + +<p>Each file you create has to follow the pattern defined in the schema contained within our repo; you can see the <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md">detailed schema description here</a>.</p> + +<h3 id="Basic_compat_data_structure">Basic compat data structure</h3> + +<p>Let's look at an example. CSS property JSON files for example need the following basic structure:</p> + +<pre class="brush: json notranslate">{ + "css": { + "properties": { + "border-width": { + "__compat": { + ... + } + } + } + } +}</pre> + +<p>You have the <code>css</code> object, inside of which is a <code>properties</code> object. Inside the <code>properties</code> object, you need one member for each of the specific features you want to define the compat data for. Each of these members has a <code>__compat</code> member, inside of which the actual data goes.</p> + +<p>The above data is found in the <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a> file — compare this to the <a href="/en-US/docs/Web/CSS/border-width#Browser_compatibility">rendered border-width support table on MDN</a>.</p> + +<p>Other types of features work in the same way, but with different object names:</p> + +<ul> + <li>CSS selectors work in basically the same way as CSS properties, except that the top-level object structure is <code>css.selectors</code> instead of <code>css.properties</code>. See <a href="https://github.com/mdn/browser-compat-data/blob/master/css/selectors/cue.json">cue.json</a> for an example.</li> + <li>HTML data works in basically the same way, except that the top-level object structure is <code>html.elements</code>. See <code>article.json</code> for an example.</li> + <li>The top level object structure for JS built-in objects is <code>javascript.builtins</code>; see <a href="https://github.com/mdn/browser-compat-data/blob/master/javascript/builtins/Array.json">Array.json</a> for an example.</li> +</ul> + +<div> +<p>In HTML, CSS, and JS pages, you'll normally only need one feature. API interfaces work slightly differently — they always have multiple sub-features (see {{anch("Sub-features")}}, below).</p> + +<h3 id="Basic_structure_inside_a_feature">Basic structure inside a feature</h3> + +<p>Inside a feature <code>__compat</code> member, you need to include the following members:</p> + +<ul> + <li><code>mdn_url</code>: Contains the URL of the reference page for this feature on MDN. Note that this needs to be written without the locale directory inside, e.g. <code>/docs/...</code> not <code>/docs/en-US/...</code> (or whatever). This is added in by the macro when the data is put on the page, for localization purposes.</li> + <li><code>support</code>: Contains members representing the browser support information for this feature in all the different browsers we want to report.</li> + <li><code>status</code>: Contains members reporting the standards track status of this feature.</li> +</ul> + +<p>The names of the browser members are defined in the schema (see <a href="https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#browser-identifiers">Browser identifiers</a>). You should use the full list of currently defined identifiers. If you wish to add another browser, talk to us first, as this could have a wide-ranging impact and should not be done without careful thought.</p> + +<p>In a basic browser compat data file, you'll only need to include "version_added" inside the browser identifier members (we'll cover {{anch("Advanced cases")}} later on). The different values you might want to include are as follows:</p> + +<ul> + <li>A version number: If you know the exact version in which a browser started to support your feature, use a string representing the number, e.g. "47".</li> + <li><code>true</code>: If a browser supports a feature but you don't know the exact version number, use the value <code>true</code>. This equivalent to the <code>\{{CompatVersionUnknown}}</code> macro call in the old manual tables.</li> + <li><code>false</code>: If a browser does not support a feature, use the value <code>false</code>. This is equivalent to the the <code>\{{CompatNo}}</code> macro call in the old manual tables.</li> + <li><code>null</code>: If you don't know whether a browser supports a feature or not, use the value <code>null</code>. This is equivalent to the <code>\{{CompatUnknown}}</code> macro call in the old manual tables.</li> +</ul> + +<p>Inside the <code>status</code> member, you'll include three submembers:</p> + +<ul> + <li> "experimental": This should be set to <code>true</code> if the feature is <a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental">experimental</a>, or <code>false</code> otherwise.</li> + <li>"standard_track": This should be set to <code>true</code> if a feature is on some kind of standards track (most commonly W3C/WHATWG, but there are also other standards efforts such as Khronos, TC39, etc.) or <code>false</code> otherwise.</li> + <li>"deprecated": This should be set to <code>true</code> if the feature is <a href="/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Deprecated_and_obsolete">deprecated</a>, or <code>false</code> otherwise.</li> +</ul> + +<p>The feature data for <a href="/en-US/docs/Web/CSS/border-width#Browser_compatibility">border-width</a> (also see <a href="https://github.com/mdn/browser-compat-data/blob/master/css/properties/border-width.json">border-width.json</a>) is shown below as an example:</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="Adding_a_description">Adding a description</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="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> diff --git a/files/ko/mdn/structures/index.html b/files/ko/mdn/structures/index.html new file mode 100644 index 0000000000..7934f5f1f6 --- /dev/null +++ b/files/ko/mdn/structures/index.html @@ -0,0 +1,18 @@ +--- +title: 문서 구조 +slug: MDN/Structures +tags: + - MDN 메타 + - 문서구조 + - 시작하기 +translation_of: MDN/Structures +--- +<div>{{MDNSidebar}}</div> + +<div>{{IncludeSubnav("/ko/docs/MDN")}}</div> + +<div>MDN에는 정보를 일관되게 표현하기 위해서 반복해서 사용하는 문서 구조들이 있습니다. 여기선 여러분이 글을 작성하고 수정, 번역할 때 받아들이고 적용할 뿐만 아니라 개선할 수 있도록 그 구조에 대해 설명합니다.</div> + +<div> </div> + +<p>{{LandingPageListSubPages()}}</p> diff --git a/files/ko/mdn/structures/macros/commonly-used_macros/index.html b/files/ko/mdn/structures/macros/commonly-used_macros/index.html new file mode 100644 index 0000000000..8038d19eba --- /dev/null +++ b/files/ko/mdn/structures/macros/commonly-used_macros/index.html @@ -0,0 +1,220 @@ +--- +title: 흔히 쓰는 매크로 +slug: MDN/Structures/Macros/Commonly-used_macros +tags: + - Reference +translation_of: MDN/Structures/Macros/Commonly-used_macros +--- +<div>{{MDNSidebar}}</div> + +<p><span class="seoSummary">이 페이지는 MDN에서 사용하기 위해 만든 많은 범용 매크로를 나열합니다. 이 매크로 사용법에 관한 정보는, <a href="/ko/docs/MDN/Contribute/Content/Macros">매크로 사용하기</a> 및 <a href="/ko/docs/MDN/Contribute/Editor/Links#Using_link_macros">링크 매크로 사용하기</a>를 참조하세요.</span> 드물게, 특별한 문맥에서만 쓰이거나 사라질(deprecated) 매크로에 관한 정보는 <a href="/ko/docs/MDN/Contribute/Structures/Macros/Other">기타 매크로</a>를 참조하세요. <a href="/ko/docs/templates" title="complete list of all macros on MDN">MDN의 모든 매크로 전체 목록</a>도 있습니다.</p> + +<p>사용 가능 스타일에 관한 <a href="/ko/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)">대개, 임의(arbitrary) 링크 생성을 위해 매크로를 사용할 필요가 없습니다. 링크를 만들기 위해 에디터 인터페이스의 <strong>링크</strong> 버튼을 사용하세요</p> + +<ul> + <li>{{TemplateLink("Glossary")}} 매크로는 MDN <a href="/ko/docs/Glossary" title="glossary">용어사전</a> 내 지정된 용어(term) 항목에 대한 링크를 만듭니다. 이 매크로는 하나는 필수며 둘은 선택인 매개변수를 취합니다: + + <ol> + <li>용어명 (가령 "HTML").</li> + <li>용어명 대신 글에 표시할 텍스트 (이건 드물게 쓰임). {{optional_inline}}</li> + <li>이 매개변수가 지정되고 0이 아닌 경우, 보통 용어사전 링크에 적용된 사용자 정의 스타일링은 적용되지 않습니다. {{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의 특정 참고서(reference) 영역 내 페이지에 링크하는 다양한 매크로가 있습니다.</p> + +<ul> + <li>{{TemplateLink("cssxref")}}는 <a href="/ko/docs/Web/CSS/CSS_Reference" title="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 참고서 내 페이지에 링크합니다, 예: \{{event("change")}}는 {{event("change")}}가 됩니다.</li> + <li>{{TemplateLink("HTMLElement")}}는 HTML 참고서 내 HTML 요소(element)에 링크합니다.</li> + <li>{{TemplateLink("htmlattrxref")}}는 HTML attribute, 전역 attribute 설명 (attribute명만 지정한 경우) 또는 (attribute명 및 요소명을 지정한 경우) 지정 요소와 관련된 attribute에 링크합니다. 예를 들어, <code>\{\{htmlattrxref("lang")\}\}</code>은 이 링크를 만듭니다: {{htmlattrxref("lang")}}.<code> </code> <code>\{\{htmlattrxref("type","input")\}\}</code>은 이 링크를 만듭니다: {{htmlattrxref("type","input")}}.</li> + <li>{{TemplateLink("jsxref")}}는 <a href="/ko/docs/Web/JavaScript/Reference" title="JavaScript Reference">JavaScript 참고서</a> 내 페이지에 링크합니다.</li> + <li>{{TemplateLink("SVGAttr")}}은 특정 SVG attribute에 링크합니다. 예를 들어, <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")}}는 연속글의 일부인 글을 위한 내비게이션 컨트롤을 제공합니다. 단방향 템플릿의 경우, 필요한 유일한 매개변수는 연속글의 이전 또는 다음 글의 위키 주소입니다. {{TemplateLink("PreviousNext")}}의 경우, 필요한 두 매개변수는 해당 글의 위키 주소입니다. 첫 번째 매개변수는 이전 글이고 두 번째는 다음 글입니다.</p> + +<h2 id="코드_샘플">코드 샘플</h2> + +<h3 id="실시간_샘플">실시간 샘플</h3> + +<ul> + <li>{{TemplateLink("EmbedLiveSample")}}은 페이지 상에 코드 샘플의 출력을 포함할 수 있습니다, <a href="/ko/docs/MDN/Contribute/Structures/Live_samples" title="Live samples">실시간 샘플</a>에 설명된 대로.</li> + <li>{{TemplateLink("LiveSampleLink")}}는 페이지 상에 코드 샘플의 출력을 포함하는 페이지로의 링크를 만듭니다, <a href="/ko/docs/MDN/Contribute/Structures/Live_samples" title="Live samples">실시간 샘플</a>에 설명된 대로.</li> +</ul> + +<h3 id="첨부된_샘플_파일">첨부된 샘플 파일</h3> + +<ul> + <li>{{TemplateLink("Embed_text")}} 템플릿은 글 본문 내에 첨부된 텍스트 파일을 삽입할 수 있습니다. 이는 다운로드 가능하지만 글의 콘텐츠에 표시되기도 하는 코드 조각을 갖고 싶은 경우 유용합니다. 구문 강조를 위한 언어를 선택 사항으로 지정할 수도 있습니다; 지정하지 않은 경우, 텍스트는 강조 없이 삽입됩니다. 첫 번째 매개변수는 삽입할 첨부 파일명입니다; 두 번째는, 제공되는 경우 구문 강조기를 적용할 언어입니다, 가령 "javascript", "svg" 또는 "cpp".</li> + <li>{{TemplateLink("EmbedSVG")}}는 SVG 이미지로서 첨부된 XML 파일을 삽입합니다, 페이지 위에다. 첨부된 SVG 파일의 파일명을 지정하세요. 소스 그리고 같은 파일의 렌더링된 출력을 표시하기 위해 {{TemplateLink("Embed_text")}}와 동시에 이를 사용할 수 있습니다.</li> +</ul> + +<h2 id="사이드바_생성">사이드바 생성</h2> + +<p>거의 모든 대규모 페이지 컬렉션 용 템플릿이 있습니다. 보통은 참고서/안내서(guide)/지도서(tutorial)의 메인 페이지로 다시 링크하고 (이동 경로 표시(breadcrumb)가 때때로 이를 수행할 수 없기에 종종 필요함) 글을 적절한 항목(category)에 둡니다.</p> + +<ul> + <li>{{TemplateLink("CSSRef")}}는 CSS 참고서 페이지 용 사이드바를 생성합니다.</li> + <li>{{TemplateLink("HTMLRef")}}는 HTML 참고서 페이지 용 사이드바를 생성합니다.</li> + <li>{{TemplateLink("APIRef")}}는 Web API 참고서 페이지 용 사이드바를 생성합니다.</li> +</ul> + +<h2 id="범용_형식">범용 형식</h2> + +<h3 id="API_문서용_인라인_지시자indicator">API 문서용 인라인 지시자(indicator)</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>(<code>true</code>)면, 사용자 정의 객체임을 나타냅니다.</dd> + <dt>parameterX {{ optional_inline() }}</dt> + <dd>어쩌고 저쩌고...</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="Deprecated">Deprecated</h4> + +<p>{{TemplateLink("deprecated_inline")}}은 공식으로 사라질 API의 사용을 삼가도록 인라인 사라질(deprecated) 표시를 삽입합니다. <strong>주의:</strong> "사라질"은 더 이상 사용되지 않지만 여전히 기능함을 뜻합니다. 전혀 작동하지 않음을 뜻하는 경우, 용어 "안 씀(obsolete)"을 쓰세요.</p> + +<p>모든 브라우저에 쓰일 수 있는 영역(HTML, API, 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="Obsolete">Obsolete</h4> + +<p>{{TemplateLink("obsolete_inline")}}은 공식으로 안 쓰는(obsolete) 예를 들어 함수, 메서드 또는 속성이 사용을 막기 위해 인라인 안 씀 표시를 삽입합니다.</p> + +<p>모든 브라우저에 쓰일 수 있는 영역(HTML, API, 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="/ko/docs/WebAPI">WebAPI</a> 페이지에 사용됩니다. 새 배지 생성 정보는 {{anch("Creating new badges")}} 참조.</p> + +<h3 id="페이지_또는_절_표제_지시자">페이지 또는 절 표제 지시자</h3> + +<p>이 템플릿들은 위에 설명한 자신의 인라인 짝(counterpart)과 같은 의미(semantics)를 갖습니다. 템플릿은 참고 페이지 내 메인 페이지 제목 (또는 가능한 경우 이동 경로 표시(breadcrumb) 내비게이션) 바로 아래에 놓여야 합니다. 페이지 상 절(section)에 표시하는데 사용될 수도 있습니다.</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> +</ul> + +<h3 id="기능을_웹_워커에서_이용가능한_지_나타내기">기능을 웹 워커에서 이용가능한 지 나타내기</h3> + +<p>{{TemplateLink("AvailableInWorkers")}} 매크로 기능이 <a href="/ko/docs/Web/API/Web_Workers_API">웹 워커</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> + +<p> </p> + +<ol> +</ol> + +<p> </p> diff --git a/files/ko/mdn/structures/macros/index.html b/files/ko/mdn/structures/macros/index.html new file mode 100644 index 0000000000..3e27b26b8a --- /dev/null +++ b/files/ko/mdn/structures/macros/index.html @@ -0,0 +1,46 @@ +--- +title: 매크로 +slug: MDN/Structures/Macros +tags: + - Guide + - Kuma + - KumaScript + - MDN Meta + - Structures +translation_of: MDN/Structures/Macros +--- +<div>{{MDNSidebar}}</div><p><span class="seoSummary">MDN이 돌아가는 <a href="/ko/docs/MDN/Kuma" title="/ko/docs/MDN/Kuma">Kuma</a> 플랫폼은 매우 다양한 것들을 자동으로 수행할 수 있게 하는 강력한 매크로 시스템인, <a href="/ko/docs/MDN/Contribute/Tools/KumaScript" title="KumaScript guide">KumaScript</a>를 제공합니다. 이 글은 글 내에서 MDN의 매크로를 호출하는 법에 관한 정보를 제공합니다.</span></p> + +<p><a href="/ko/docs/MDN/Contribute/Tools/KumaScript" title="KumaScript guide">KumaScript 안내서</a>는 상세히 고찰한 MDN 상의 매크로 사용법을 제공합니다. 따라서 이 절은 더 짧은 개요입니다.</p> + +<h2 id="매크로가_구현되는_법">매크로가 구현되는 법</h2> + +<p>MDN의 매크로는 서버에서 실행되는 <a href="/ko/docs/Web/JavaScript">JavaScript</a> 코드로 구현되고, <a href="http://nodejs.org/" title="http://nodejs.org/">Node.js</a>를 사용하여 해석됩니다. 그 위에 우리가 구현한 위키 중심 서비스 및 매크로를 위키 플랫폼 및 그 콘텐츠와 상호 작용하게 하는 기능을 제공하는 많은 라이브러리가 있습니다. 더 배우고 싶다면, <a href="/ko/docs/MDN/Contribute/Tools/KumaScript" title="KumaScript guide">KumaScript 안내서</a>를 참조하세요.</p> + +<h2 id="콘텐츠에_매크로_사용하기">콘텐츠에 매크로 사용하기</h2> + +<p>실제로 매크로를 사용하려면, 괄호로 싸인 매개변수(가 있다면)와 함께 매크로 호출을 그저 중괄호 두 쌍으로 두르세요. 즉 다음과 같이:</p> + +<pre class="notranslate">\{{macroname(parameter-list)}}</pre> + +<p>매크로 호출에 관한 몇 가지 주의사항:</p> + +<ul> + <li>매크로 명은 대소문자를 구분하지만 일부는 흔한 대문자화(capitalization) 오류를 고치기 위해 만든 시도입니다. 따라서 매크로 명은 이름 내에 대문자를 사용할지라도 모두 소문자로 쓸 수 있고 보통 소문자로 시작하는 매크로 명을 대문자로 시작할 수 있습니다.</li> + <li>매개변수는 쉼표로 구분됩니다.</li> + <li>매개변수가 없다면, 괄호를 전부 뺄 수 있습니다. 즉 <code>\{{macroname()}}</code> 및 <code>\{{macroname}}</code>은 동일합니다.</li> + <li>숫자 매개변수는 따옴표로 묶거나 묶지 않을 수 있습니다. 알아서 하세요(그러나, 그 안에 여러 소수가 있는 버전 번호라면 따옴표로 묶어야 합니다).</li> + <li>오류가 생기면, 코드를 신중히 검토하세요. 무슨 일인지 여전히 파악할 수 없다면, 도움을 받기 위해 <a href="/ko/docs/MDN/Kuma/Troubleshooting_KumaScript_errors" title="Troubleshooting KumaScript errors">KumaScript 오류 해결</a>을 참조하세요.</li> +</ul> + +<p>매크로는 다량(heavily) 캐쉬됩니다; 어떠한 일련의 입력 값(매개변수 및 매크로가 실행되었을 URL과 같은 환경 값 모두)에 대해, 그 결과는 저장되고 재사용됩니다. 이는 매크로가 사실 매크로 입력이 바뀔 때만 실행됨을 뜻합니다.</p> + +<div class="note"> +<p><strong>주의:</strong> 페이지의 모든 매크로를 브라우저에서 페이지 강제 새로 고침(즉, shift-새로 고침)하여 재평가되게 강제할 수 있습니다.</p> +</div> + +<p>매크로는 더 큰 텍스트 블록 단순 삽입 또는 MDN의 다른 부분에서 콘텐츠를 교환하는 것처럼 간단하거나, 사이트의 일부를 검색하여 콘텐츠의 전체 색인 구축, 출력 스타일링 및 링크 추가처럼 복잡할 수 있습니다.</p> + +<p><a href="/ko/docs/MDN/Contribute/Structures/Macros/Commonly-used_macros" title="Commonly-used macros">흔히 쓰는 매크로</a> 페이지에서 가장 흔히 쓰는 매크로에 관하여 읽을 수 있습니다; 또한, 여기에 <a href="https://developer.mozilla.org/ko/docs/templates">모든 매크로 전체 목록</a>도 있습니다. 매크로 대부분은 상단에 주석으로 내장된 문서가 있습니다.</p> + +<p>{{EditorGuideQuicklinks}}</p> |