[ko] convert html to markdown (1) /web/javascript

[hochan222]

PR 목적

html을 markdown으로 변환하는 것에만 목적을 뒀습니다.

변환 방법 (yari)

yarn md h2m web/javascript/path --locale ko --mode keep

느낀점

• 가독성이 좋아졌다.
  • 확실히 HTML 형식보다 markdown이 구조적으로 간단해서 유지보수에 쉬워보인다.
• 변환 조건이 엄격해서 변환이 안되는 부분들이 너무 많았다.
  • 전체 문서를 한번에 명령어로 변환해서 반영하면, 여러 문서에서 깨질 위험성이 굉장히 크다는 것을 느꼈다. 당장의 closure 부분의 code 부분은 전부 변환이 되지않고 일반 text로 변환됐다.
• 본문 중간에 맘대로 개행이 된다.
  • 해결: don't wrap lines when converting to md
• {{jsxref("Math")}} 와 [Math](/ko/Core_JavaScript_1.5_Reference/Global_Objects/Math) 가 기준없이 무차별하게 쓰이고 있다.
  • 위 사례는 하나의 예시일 뿐이다.

목록

• a_re-introduction_to_javascript (동기화 여부 x)
• about_javascript (동기화 여부 o)
• closures (동기화 여부 x)
• data_structures (동기화 여부 x)
• enumerability_and_ownership_of_properties (동기화 여부 x)
• equality_comparisons_and_sameness (동기화 여부 x)
• eventloop (동기화 여부 x)

참고

• https://egas.tistory.com/64?category=482046
• https://docs.google.com/spreadsheets/d/1Nb-WUHveeUfi5YV0-pzVyHI1vR1IC8xF40IdkiceyQQ/edit#gid=0
• https://github.github.com/gfm/
• https://github.com/mdn/translated-content/discussions/1236

가독성 예시

• before

• after

---

변환 후 추가 변경사항

명령어 이후 아래는 추가적으로 진행한 정제작업을 나열했습니다. (중복된 작업은 작성하지 않았습니다.)

• about_javascript

  • <sup>®</sup> 제거 (https://developer.mozilla.org/en-US/docs/MDN/Contribute/Markdown_in_MDN#superscript_and_subscript)
  • <span style="line-height: 1.5;">기본적인 문법은  언어 학습에 필요한 새로운 개념 을 줄이기 위해 Java와 C++의 if문, for와 while문, switch문과 try...catch 구문을 사용하는 언어구조를 사용하며, 그와 같은 (거의 가까운) 동작을 한다.</span> 에서 span tag 제거. (Strip tags/strip attribute)
  • <p style="padding-right: 0px; padding-left: 0px; padding-bottom: 0px; margin: 0px 0px 1.7em; padding-top: 0px;"> p tag 제거 GFM

    • 해당 경우는 style이 포함되어있기 때문에 자동으로 p tag를 삭제를 해주지 않았습니다. error 경우입니다.

  • <a class="external" href="http://www.instantweb.com/%7Efoldoc/foldoc.cgi?query=procedural&#x26;action=Search">을 []()으로 변환 (GFM)
  • <ul><li>을 -로 변경 (GFM)
  • <strong>호스트 객체</strong>을 ****로 변경 (GFM)
  • <dl><dt> (Description lists)

• /web/javascript/closures

  • 해당 페이지에서 <pre> tag를 js code를 나타내는 용도로 쓰였는데 markdown js code로 변환이 되지않고, 평문으로 변환된다.
    • 원인: <pre class="brush: js"> class name이 없음 [Markdown] Decide how to represent code blocks content#3512
  • <font face="consolas, Liberation Mono, courier, monospace"> </font>
    • 삭제가 안된다. (80 line)
  • <a href="http://www.google.com/search?q=javascript+module+pattern" title="http://www.google.com/search?q=javascript+module+pattern">모듈 패턴</a>
  • [모듈 패턴](http://www.google.com/search?q=javascript+module+pattern "http://www.google.com/search?q=javascript+module+pattern")
    • 비효율적 차지 하지만 https://github.github.com/gfm/#example-493 GFM에 있는 문법
    • Suggestion: Remove a title in the []() syntax in markdown. (h2m converter) yari#4320
    • 결론: title을 제거하자 위의 이슈 참고
  • 해당 알림에 대해서 번역본에 기입이 되지 않아서 알림 부분인지 알 수 없었다.

  > **Note:** 이런 방식으로 클로저를 사용하여 객체지향 프로그래밍의 정보 은닉과 캡슐화 같은 이
  점들을 얻을 수 있다.
  

• /web/javascript/data_structures

  • 2<sup>53</sup> -1 를 2^53 -1로 변경
  • /en-US/docs/Storage 페이지 없음. 링크 깨짐
    • Content bug: /en-US/docs/Storage link broken, /Web/JavaScript/data_structures content#7300
    • 해결: /en-US/docs/Web/API/Web_Storage_API

• /web/javascript/equality_comparisons_and_sameness

  • <div class="summary"> 가 있을경우 class 속성을 없애야 정상적인 변환이 이뤄진다.
  • markdown table 변환이 다 안됐다.
    • Content bug: markdown unconverted /javascript/web/equality_comparisons_and_sameness content#7303

• /web/javascript/eventloop

  • <img alt="Stack, heap, queue" src="/files/4617/default.svg" style="height: 270px; width: 294px;">
    • ![Stack, heap, queue](the_javascript_runtime_environment_example.svg) 로 변경

• /web/javascript/a_re-introduction_to_javascript

  • <h2 id=".EA.B0.9C.EC.9A.94" name=".EA.B0.9C.EC.9A.94">개요</h2>
    • 유니코드 id, name으로인해 정상적인 변환이 이뤄지지않았다.

버그

• about_javascript의 깨진 링크
  • Content bug: broken link for /en-US/docs/Web/JavaScript/about_javascript#_flaws content#7271

[peterbe]

@hochan222 There are currently not index.md files in the mdn/translated-content repo but, thanks to people like you, it's only a matter of time.
Once #1705 is merged and you merge in latest main into your branch, it should hopefully start building based on index.md files too.

[github-actions]

Preview URLs

• https://pr1698.content.dev.mdn.mozit.cloud/ko/docs/Web/JavaScript/Equality_comparisons_and_sameness
• https://pr1698.content.dev.mdn.mozit.cloud/ko/docs/Web/JavaScript/A_re-introduction_to_JavaScript
• https://pr1698.content.dev.mdn.mozit.cloud/ko/docs/Web/JavaScript/EventLoop
• https://pr1698.content.dev.mdn.mozit.cloud/ko/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
• https://pr1698.content.dev.mdn.mozit.cloud/ko/docs/Web/JavaScript/Closures
• https://pr1698.content.dev.mdn.mozit.cloud/ko/docs/Web/JavaScript/Data_structures
• https://pr1698.content.dev.mdn.mozit.cloud/ko/docs/Web/JavaScript/About_JavaScript

Flaws

Note! 3 documents with no flaws that don't need to be listed. 🎉

URL: /ko/docs/Web/JavaScript/Equality_comparisons_and_sameness
Title: 동치 비교 및 동일성
on GitHub
Flaw count: 6

• macros:
  • /ko/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2 does not exist but fallbacked on /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2
• broken_links:
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback
• heading_links:
  • h2 heading contains an <a> tag

---

URL: /ko/docs/Web/JavaScript/A_re-introduction_to_JavaScript
Title: JavaScript 재입문하기 (JS ​튜토리얼)
on GitHub
Flaw count: 18

• broken_links:
  • Can't resolve /ko/docs/docs/Web/JavaScript/Data_structures#bigint_type
  • Can't resolve /ko/docs/docs/Web/JavaScript/Data_structures#undefined_type
  • Can't resolve /ko/docs/docs/Web/JavaScript/Data_structures#null_type
  • Can't resolve /ko/docs/docs/Web/JavaScript/Data_structures#bigint_type
  • Can't resolve /ko/Core_JavaScript_1.5_Reference/Operators/Arithmetic_Operators
  • and 13 more flaws omitted

---

URL: /ko/docs/Web/JavaScript/EventLoop
Title: 동시성 모델과 이벤트 루프
on GitHub
Flaw count: 2

• broken_links:
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback

---

URL: /ko/docs/Web/JavaScript/Data_structures
Title: 자바스크립트의 자료형
on GitHub
Flaw count: 19

• macros:
  • /ko/docs/Web/JavaScript/Reference/Map does not exist
  • /ko/docs/Web/JavaScript/Reference/Int8Array does not exist
  • /ko/docs/Web/JavaScript/Reference/Uint8Array does not exist
  • /ko/docs/Web/JavaScript/Reference/Uint8ClampedArray does not exist
  • /ko/docs/Web/JavaScript/Reference/Int16Array does not exist
  • and 7 more flaws omitted
• broken_links:
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback
  • Can use the English (en-US) link as a fallback
  • and 2 more flaws omitted

External URLs

URL: /ko/docs/Web/JavaScript/Equality_comparisons_and_sameness
Title: 동치 비교 및 동일성
on GitHub

• 🚨 http://dorey.github.io/JavaScript-Equality-Table/ (1 time) (Note! This may be a new URL 👀)
• https://ecma-international.org/ecma-262/5.1/ (3 times) (Note! This may be a new URL 👀)
• https://tc39.es/ecma262/ (2 times) (Note! This may be a new URL 👀)

---

URL: /ko/docs/Web/JavaScript/A_re-introduction_to_JavaScript
Title: JavaScript 재입문하기 (JS ​튜토리얼)
on GitHub

• 🚨 http://es5.github.io/ (1 time) (Note! This may be a new URL 👀)
• 🚨 http://javascript.crockford.com/javascript.html (1 time) (Note! This may be a new URL 👀)
• 🚨 http://simon.incutio.com/ (1 time) (Note! This may be a new URL 👀)
• 🚨 http://simon.incutio.com/archive/2006/03/07/etech (1 time) (Note! This may be a new URL 👀)
• https://couchdb.apache.org/ (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Double_precision_floating-point_format (1 time) (Note! This may be a new URL 👀)
• https://nodejs.org/ (1 time) (Note! This may be a new URL 👀)
• https://www.ecma-international.org/ (1 time) (Note! This may be a new URL 👀)
• https://www.ecma-international.org/publications/standards/Ecma-262.htm (1 time) (Note! This may be a new URL 👀)
• https://www.gnome.org/ (1 time) (Note! This may be a new URL 👀)

---

URL: /ko/docs/Web/JavaScript/EventLoop
Title: 동시성 모델과 이벤트 루프
on GitHub

• https://html.spec.whatwg.org/multipage/webappapis.html (1 time) (Note! This may be a new URL 👀)
• https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/ (1 time) (Note! This may be a new URL 👀)
• https://stackoverflow.com/questions/2734025/is-javascript-guaranteed-to-be-single-threaded/2734311 (1 time) (Note! This may be a new URL 👀)

---

URL: /ko/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
Title: Enumerability and ownership of properties
on GitHub

No new external URLs

---

URL: /ko/docs/Web/JavaScript/Closures
Title: 클로저
on GitHub

• 🚨 http://jsfiddle.net/xAFs9/3/ (1 time) (Note! This may be a new URL 👀)
• https://jsfiddle.net/vnkuZ/7726/ (1 time) (Note! This may be a new URL 👀)
• https://www.google.com/search?q=javascript+module+pattern (1 time) (Note! This may be a new URL 👀)

---

URL: /ko/docs/Web/JavaScript/Data_structures
Title: 자바스크립트의 자료형
on GitHub

• https://code.google.com/p/google-caja/source/browse/trunk/src/com/google/caja/ses/StringMap.js?r=4779 (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Double-precision_floating-point_format (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Hash_table (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Mask_%28computing%29 (1 time) (Note! This may be a new URL 👀)
• https://github.com/monmohan/DataStructures_In_Javascript (1 time) (Note! This may be a new URL 👀)
• https://github.com/nzakas/computer-science-in-javascript/ (1 time) (Note! This may be a new URL 👀)
• https://productforums.google.com/forum/ (1 time) (Note! This may be a new URL 👀)
• https://tc39.es/ecma262/ (1 time) (Note! This may be a new URL 👀)

---

URL: /ko/docs/Web/JavaScript/About_JavaScript
Title: JavaScript에 대하여
on GitHub

• https://code.google.com/p/v8/ (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Chakra_%28JScript_engine%29 (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/First-class_function (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Prototype-based_programming (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Rhino_(JavaScript_engine) (1 time) (Note! This may be a new URL 👀)
• https://my.opera.com/ODIN/blog/carakan-faq (1 time) (Note! This may be a new URL 👀)
• https://nodejs.org/ (1 time) (Note! This may be a new URL 👀)
• https://spidermonkey.dev/ (1 time) (Note! This may be a new URL 👀)
• https://www.w3.org/DOM/ (1 time) (Note! This may be a new URL 👀)
• https://www.webkit.org/projects/javascript/index.html (1 time) (Note! This may be a new URL 👀)

(this comment was updated 2021-07-26 19:20:39.418687)

[hochan222]

@mdn/yari-content-ko

html을 markdown으로 변환시키는 첫번째 예시입니다. yarn md h2m web/javascript/path --locale ko --mode keep 명령어로 모두 해결되면 좋겠지만, 많은 한국 문서에 레거시로 인해 변환이 잘 이뤄지지 않는 경우가 많습니다. (예: id, class 값이 있을 경우 변환을 하지 않고 그대로 놔둠). 리뷰를 할때, 변환이 잘 이뤄지지 않는 경우에 대해 알고있어야 합니다. 따라서, 해당 PR에 멘션했습니다.

[alattalatta]

@hochan222 이 PR이 예시인지 실제로 병합될지는 모르겠지만 Git 히스토리가 날아가는 것은 좀 우려스럽습니다. mdn/content#6936 을 보시면

1. .html->.md 이름만 변경
2. 마크다운 커밋

의 형태로 되어있음을 볼 수 있습니다. 여타 html -> md 변환 PR의 경우에도 동일한 절차를 취해야 하지 않을까 해요. (#1763)

[hochan222]

@alattalatta 알려주셔서 감사합니다. 중요한 점을 놓치고 있었네요.

여타 html -> md 변환 PR의 경우에도 동일한 절차를 취해야 하지 않을까 해요.

동의합니다. 관련 지침은 따로 제가 만들겠습니다.

어쩌면 조금 성급했는지도 모르겠습니다. #1574 해당 PR처럼 관련 사전 작업도 시간을 내서 따로 해야겠네요.

[hochan222]

현재 PR의 작업은 #1769 로 이전되었습니다. #1769 을 참고해주세요.