ABOUT ME

-

Today
-
Yesterday
-
Total
-
  • README.md
    저장소/git 2016. 12. 26. 10:58

    README.md 파일은 git, github 등과 같이 저장소에서 많이 본 파일입니다. 해당 파일은 소스코드에 앞서 어떠한 목적으로 개발이 되었는지, 코드의 개요, 구조도 등을 처음 사람들에게 노출함으로써 해당 프로젝트에 대해 설명을 합니다.

    여기서는 여러형태의 리드미 파일을 전부 다루는 것이 아닌 현재 사용중인 gitlab의 README.md파일을 위주로 필요성 및 문법을 설명하도록 하겠습니다.

    리드미(readme)란?


    리드미 (README, readme, read me) 파일은 디렉토리나 압축 파일에 포함된 기타 파일에 대한 정보를 가지고 있으며, 일반적으로 소트프웨어와 함께 배포됩니다. 또한 현재 git과 같은 저장소에서도 해당 파일을 default로 생성하여 해당 저장소에 대한 설명을 기입하도록 하고 있습니다.

    리드미의 파일 형태는 README.TXT, README.md, README.1ST, README.DOC READ.ME 또는 간단히 README 등 많은 파일 명과 확장자 형태를 가지고 있습니다.


    리드미 (README의 다양한 형태를 여기서는 '리드미'로 부르겠습니다.)는 다음 중 하나 이상의 정보를 포함합니다.

    • 컴퓨터 구성 안내
    • 설치 안내
    • 사용법
    • 파일 메니페스트 (파일 목록 포함)
    • 저작권 및 사용권 정보
    • 배포자 및 프로그래머의 연락처 정보
    • 알려진 버그
    • 트러블슈팅
    • 크레딧
    • 체인지로그


    위에 나열한 목록 이외의 정보를 포함할 수 있습니다. 또한 오픈소스 배포판을 일반적으로 아래와 같은 표준 집합의 리드미 파일들을 포함합니다.


    README일반 정보
    AUTHORS제작 정보
    THANKS도와주신 분들에 대한 정보
    ChangeLog프로그래머들이 참고 할 수 있는 자세한 체인지로그
    NEWS사용자들이 참고할 수 있는 기본적인 체인지로그
    INSTALL설치 안내
    COPYING/LICENSE저작권 및 사용권 정보
    BUGS알려진 버그 및 새로운 버그 보고 방법 안내

    리드미 파일로 해당 프로젝트의 버젼, 이전버젼과 변경된 사항들, 파일 목록, 시스템 구조도 등을 작성하여 사용자들이 특이 사항들을 바로 확인 할 수 있도록 합니다.

    리드미(readme)작성법


    readme작성은 사실 사용자 마음대로 작성해도 되지만 Markdown 문법에 맞게 작성하면 html과 같이 더 멋지게 꾸밀 수 있습니다.

    마크다운 소개 

    마크다운(Markdown)은 일종의 마크업 언어로 텍스트에 태그를 이용해서 글자를 굵게 하거나, 이미지를 삽입하거나 하는 일이 가능합니다. 엔하위키에 글을 쓸 때 위키 언어를 이용해서 글을 써야하는데, 마크다운 언어는 그 위키 언어와 상당히 유사하다고 할 수 있습니다. 하지만 마크다운은 위키문법보다 훨씬 더 간단하므로 익히는데 그리 긴 시간이 필요하지 않다는 장점을 가지고 있습니다.

    요즘 마크다운은 아주 여러 곳에서 사용되고 있습니다. 이제 워드프레스에서는 기본적으로 마크다운을 지원하기 시작했고, Tumblr나 Ghost와 같은 블로그 플랫폼에서도 마크다운 언어를 기본적으로 지원하고 있습니다. 그리고 심지어는 그누보드나 XE에도 마크다운을 쓸 수 있는 플러그인이 있어서 그 플러그인을 설치하면 그누보드나 XE에서 글을 쓸 때, 마크다운을 이용하는 것이 가능합니다.

    마크다운의 장단점

    장점

    • 읽기 쉽다.
      마크다운은 다른 마크업 언어에 비해 훨씬 알아보기 쉽습니다. 제목은 앞에 #을 붙여주면 되고, 글자를 강조하려면 글자 주위를 **으로 감싸주면 됩니다. HTML로 글을 쓸 때는, 그 글이 실제로 브라우저에 어떻게 보여질지 상상하는 것이 꽤 어려운 일이었다면 마크다운으로 쓴 텍스트는, 텍스트만으로 그 글이 브라우저에서 어떻게 보여질지 쉽게 상상할 수 있습니다.
    • 익히기 쉽다
      마크다운은 상당히 간단합니다. John Gruber가 처음에 마크다운을 만들었을 때, 사람들이 가장 많이 사용하는 기능만을 마크다운으로 쓰고, 복잡한 것은 HTML로 쓰도록 디자인했기 때문입니다. 그래서 비록 몇가지 제한이 있기는 하지만 마크다운으로 글을 쓸 때, 중간에 HTML을 그대로 써도 상관 없습니다.
    • 모바일 친화적이다
      요즘 모바일을 통해서 글을 쓰고 올리는 경우가 상당히 많아졌습니다. 그런데, 모바일로 서식이 들어간 글을 쓰는 것은 상당히 불편하다. 특히 모바일에서는 에디터가 제대로 작동하지 않는 경우도 있고, 작동하더라도 작은 화면때문에 에디터를 통해서 글을 작성하는 것이 상당히 불편한 경우가 많습니다. 하지만 마크다운을 이용해서 글을 쓰면 간단한 태그만으로 쉽게 서식을 넣을 수 있어서, 위지윅 에디터를 사용하는 것보다는 훨씬 편리합니다.

    단점

    • 문법이 너무 단순하다
      문법이 너무 단순해서 그 기능을 벗어나려고 할 때는 결국 HTML을 써야하는 경우가 생깁니다. 예를 들어, 마크다운에는 이미지를 정렬하는 문법이 없습니다. 따라서 이미지를 정렬하려면 HTML의 img 태그를 써야합니다. 또한 태그에 클래스 지정등이 불가능하기 때문에, 클래스나 id를 지정하려면 역시 HTML을 써야합니다.
    • 확장 문법이 많다
      이것은 첫 번째 단점 때문에 발생한 문제라고 볼 수 있습니다. 문법이 너무 단순하기 때문에 그 불편함을 해소하기 위해서 여러가지 확장 문법들이 생기기 시작했고, 그런 파편화 때문에 한 곳에서 잘 작동하는 마크다운 문서가 다른 곳에서는 잘 작동하지 않는 현상이 생기기도 합니다.
    • 멀티미디어 삽입이 불편하다
      위지윅 에디터에서 이미지를 삽입할 때는, 보통 이미지 업로드 버튼을 이용해서 이미지를 삽입합니다. 하지만 마크다운은 그저 텍스트만 입력 가능하기 때문에, 이미지를 삽입하는 것과 이미지를 업로드하고, 그 주소를 따오는 과정들이 모두 분리되어 있습니다. 그래서 마크다운을 이용해서 블로그의 글을 작성할 때 가장 불편한 것이 바로 이미지를 삽입할 때입니다. 하지만 유튜브 등의 외부 동영상을 삽입할 때는 위지윅 에디터를 쓰는 것과 크게 다르지 않습니다.

    마크다운 문법

    제목

    # 을 하나 쓰면 HTML의 <H1> 태그이고 #을 2개쓰면 <H2> 태그를 의미합니다. #은 총 6개까지 사용할 수 있고 #이 늘어날 때 마다 글씨가 작아집니다.

    # 제목
    ## 부제목
    ### 소제목

    번호가 없는 리스트

    * 목록 
    * 목록 1
    - 다른 목록
    - 다른 목록 1
    + 다른 목록 3

    번호가 있는 리스트

    1 첫 번쨰
    2 두 번째
    3 세 번째
    5 다섯 번째
    4 여섯 번째 

    반드시 숫자를 맞춰 사용할 필요는 없습니다.

    기울여진 글씨

    *텍스트*
    OR
    _텍스트_

    굵은 글씨

    **텍스트**
    OR
    __텍스트__

    인용

    > 텍스트

    인용문안에 인용문을 또 사용하려면 >을 추가하면 됩니다.

    인라인 링크

    [텍스트](링크주소)

    참조링크

    [텍스트][참조명]
     
    [참조명]: 링크주소

    이미지

    ![텍스트](이미지링크)

    수평선

    _, *, - 을 3개 이상씩 나열
     
    ---
    ***
    ___

    코드

    \`코드 내용\`

    코드블럭

    앞에 공백 4개 이상 삽입


    댓글