CppKorea/CppCoreGuidelines

가이드라인 문서 내 링크 수정 지침

luncliff opened this issue · 1 comments

luncliff commented

#137 을 해결하기 위한 지침

Plan

기본적인 문서간 링크 수정 지침은 아래와 같습니다.
새로운 의견이 있다면 자유롭게 댓글을 작성해주시기 바랍니다

Background

원본 문서는 하나의 md파일에 모든 내용이 모여있어서, HTML Anchor만 충돌하지 않는다면 별다른 문제없이 해당 항목으로 이동할 수 있었습니다.

하지만 현재 이 방법은 다음과 같은 이유로 불편함이 있습니다.

  1. 문서 내 검색에 너무 많은 내용이 나오기 때문에 독자들에게 불편
  2. 문서가 너무 길어서 다른 도구에서 Guideline 문서를 처리하지 못하는 경우
  3. ...

GitHub Wiki cannot render the document

Markdown

Before

상기 이유로 CppCoreGuidelines.md 문서는 sections/의 여러 문서로 분리되었고, 결과적으로 아래와 같이 Anchor로 이동하는 링크들이 무효화 되었습니다..

[{} 초기화 문법을 선호하라](#Res-list).

다행히 ](#를 검색하여 수정이 필요할수도 있는 링크가 있는지 쉽게 검색할 수 있습니다.

After

해당 문서로의 상대경로를 추가합니다.
이는 번역자가 Local clone이후 작업할 때, Visual Studio Code와 같은 도구에서 제공하는 문서 Navigation기능을 활용할 수 있도록 하기 위함입니다.

GitHub 에서 문서를 읽을때도 상대경로 링크가 문제없이 동작하는 것을 확인할 수 있었습니다.

다른 문서(Section)로의 링크

* [F: 함수(Functions)](./Functions.md)
* [E: 오류 처리(Error handling)](./Errors.md)
* [T: 템플릿과 제너릭 프로그래밍(Templates and generic programming)](./Templates.md)
* ...

다른 문서의 특정 항목(Item)으로의 링크

[{} 초기화 문법을 선호하라.](./Expr.md#Res-list).

C++ Code

일부 예제코드에는 참고 항목으로의 Anchor가 주석에 작성되어 있기도 합니다.
일반적으로 Local에서 문서의 Raw 파일을 검색하면서 읽을때는 문제가 되지 않으나, GitHub에서 읽을때처럼 Markdown Rendering을 수행한 이후에는 이 내용을 검색해서 찾아가기 어렵다는 문제가 있습니다.

최종적으로는 독자가 어떤 항목을 참고해야 하는지 전달하는데 그 목적이 있으므로, 수정 지침은 아래와 같습니다.

Before

    // [see also](./#Ri-expects)
    unsigned area(unsigned height, unsigned width) {
        // ...
    }

After

항목으로의 링크가 아니라 제목을 적어 해당 규칙을 검색하지 않고도 읽어나갈 수 있도록 합니다.

    // see also: I.6 사전 조건을 표현하고 싶다면 `Expects()`를 사용하라
    unsigned area(unsigned height, unsigned width) {
        // ...
    }

역자의 판단에 따라 아래와 같이 항목 번호만 작성하여도 좋습니다.

    // see also: I.6

To Do

  • Architecture.md
  • Concurrency.md
  • Expr.md
  • Glossary.md
  • Not.md
  • ReadMe.md
  • Source.md
  • Bibliography.md
  • Const.md
  • FAQ.md
  • Interfaces.md
  • Performance.md
  • References.md
  • Templates.md
  • CPL.md
  • Enum.md
  • Functions.md
  • Introduction.md
  • Philosophy.md
  • Resource.md
  • Unclassified.md
  • Class.md
  • Errors.md
  • GSL.md
  • Naming.md
  • Profile.md
  • SL.md