Learn Vimscript The Hard Way - 54. Documentation

Documentation

우리의 포션 플러그인은 이제 많은 기능들로 가득 차 있지만, 이를 document화 시키지 많으면 사람들이 사용하지 못하기 때문에 쓸모가 없을 것이다.

vim의 자체 documentation 기능은 아주 강력하다. 이는 아주 장황하지 않고, 철두철미하다. 또한 플러그인 저자로 하여금 document를 작성할 수 있게 영감을 주어 vimscript 커뮤니티에 강력한 documentation culture를 이뤄내었다.

How Documentation Works

vim에서 :help를 읽으면 몇몇 항목들은 다르게 하이라이트 된 것을 볼 수 있을 것이다. 이것이 어떻게 작동하는지 살펴보자.

아무 help 토픽을 열고 (:help help와 같은) :set filtype?을 실행시켜보자. filetype=help를 출력할 것이다. :set filetype=text를 실행시켜보면 하이라이팅들이 사라지는 것을 볼 수 있다. 다시 :set filetype=help를 하면 다시 하이라이팅이 된다.

vim의 help 파일들은 다른 포맷의 파일들처럼 syntax-highlighting을 지원하는 것으로 보인다. 이는 당신이 자신의 documentation을 적고 이를 하이라이팅 할 수 있다는 말이다.

플러그인 레파지토리에 doc/potion.txt를 만들자. Vim 이나 Pathogen은 help topic을 인덱싱 할 때 doc 디렉토리의 파일을 찾기 때문에 우리는 해당 경로에 플러그인의 help text를 작성할 것이다.

파일을 열고 :set filetype=help를 실행시켜 우리가 적는 내용이 하이라이팅 되게 하자.

Help Header

help 파일의 포멧은 개인의 취향에 달려있다. 그래서 나(저자)는 현대 vimscript community에서 가장 인기 있는 구조 중 하나를 가지고 얘기할 것이다.

파일의 첫 줄은 help file의 파일명과 plugin이 하는 한 줄 설명이 와야 한다. potion.txt 파일에 다음 내용을 첫 줄로 추가해주자.

*potion.txt* functionality for the potion programming language

asterisk(*)로 감싸진 단어는 help 파일의 "tag"를 만들어서 점프할 수 있게 해 준다. :Helptags를 실행시켜 Pathogen이 help tag index를 다시 빌드하게 한 후 :help potion.txt를 싱행시켜보자. 우리 가 만든 help document가 실행될 것이다.

만약 vim plug를 사용중이라면 :call plug#helptags() 함수로 help tag를 regenerate 할 수 있다.

다음은 long description과 함께 타이틀의 제목을 입력한다. (저자를 포함한) 몇몇 작성자들은 ASCII art를 사용하여 재미를 주는 것을 좋아한다. 쿨한 title section을 추가해보자.

*potion.txt* functionality for the potion programming language

                      ___      _   _              ~
                     / _ \___ | |_(_) ___  _ __   ~
                    / /_)/ _ \| __| |/ _ \| '_ \  ~
                   / ___/ (_) | |_| | (_) | | | | ~
                   \/    \___/ \__|_|\___/|_| |_| ~

          Functionality for the Potion programming language.
        Includes syntax highlighting, code folding, and more!

나는 이 멋진 글자를 figlet -f ogre "Potion" 코맨드로 만들었다. Figlet은 ASCII art text를 만들어 주는 작지만 멋진 프로그램이다. 각 줄의 마지막에 ~ 문자는 vim에게 해당 art의 각 캐릭터들을 하이라이팅 하거나 숨기지 않게 하려고 추가한다.

What to Document

다음으로는 보통 table of contents(목차)가 온다. 먼저 우리가 정말로 추가하고 싶은 내용을 결정해보자.

새로운 플러그인의 documentation을 작성할 때 나(저자)는 보통 다음 내용들로부터 시작한다.

• Introduction
• Usage
• Mappings
• Configuration
• License
• Bugs
• Contributing
• Changelog
• Credits

만약 플러그인이 크다면 "overview"같은 것이 필요할 것이다. 나는 introduction 섹션을 적어 어떻게 플러그인이 동작하는지 summary를 적을 것이다. 딱히 필요하지 않으면 이 부분은 넘어간다.

"Usage" 섹션은 사용자가 실제 플러그인을 어떻게 사용하는지에 대한 설명이다. 만약 매핑을 사용하여 플러그인을 쓴다면, 그것을 얘기해준다. 만약 매핑이 별로 많지 않다면 이를 단순히 나열하고, 그렇지 않다면 분리된 "mappings" 섹션을 만들어서 추가해준다.

"Configuration" 섹션은 각각 변경할 수 있는 변수를 나열하고 효과나 기본값 등을 적어 준다.

"license" 섹션은 플러그인이 어떤 라이센스로 작성되었는지 적어준다. licence에 대한 전체 텍스트는 help text에 적지 말고 URL로 연결해두라.

"bugs" 섹션은 짧고 간결해야 한다. 당신이 이미 알고 있지만 해결하지 못한 메이저 버그를 나열하고, 만약 버그를 발견하면 어떻게 리포트 하면 되는지 적어라.

만약 사용자들이 버그 픽스 등 contributing 하기를 원한다면 어떻게 하는지 알아야 한다. "contributing" 섹션을 만들어서 당신이 어떤 방식을 선호하는지 적어라.

changelog는 유저가 당신의 플러그인을 version X에서 version Y로 올렸을 때 무엇이 바뀌는지 등을 보여주는 좋은 항목이다. 또한 나(저자)는 Semantic Versioning을 사용하여 versioning scheme을 작성할 것을 강력하게 추천한다.

마지막으로 "credits" 섹션에서는 저자 자신의 이름과 다른 기여자들 등을 적어준다.

이는 대개 좋은 출발점이 된다. 더 유니크한 플러그인들은 위 목차에서 조금 벗어날 수 있지만, 상관 없다. 다음 항목들을 제외하면 꼭 따라야 할 규칙은 없다.

• Be thorought.
• Don't be too wordy.
• Take the user on a journey from having no idea what your plugin is to being an expert user of it.

Table of Contents

이제 대략적인 아이디어를 얻었으니 potion.txt 파일에 추가해보자.

====================================================================
CONTENTS                                            *PotionContents*

    1. Usage ................ |PotionUsage|
    2. Mappings ............. |PotionMappings|
    3. License .............. |PotionLicense|
    4. Bugs ................. |PotionBugs|
    5. Contributing ......... |PotionContributing|
    6. Changelog ............ |PotionChangelog|
    7. Credits .............. |PotionCredits|

주목할 만한 것들이 몇 개 있다. 먼저 = 문자로 만들어진 줄은 syntax highlighting이 된다. 이를 이용해서 시각적으로 나눠진 섹션을 구성할 수 있다. 원한다면 -를 사용해도 무방하다.

*PotionContents는 다른 태그를 만들어준다. :help PotionContents로 해당 태그를 사용할 수 있다.

|로 감싸진 각각의 단어들은 태그로의 링크를 만들어준다. 사용자는 help text에서 해당 단어에 커서를 두고 <c-]를 눌러서 해당 태그가 있는 위치로 점프할 수 있다. (:help xxx를 친 것과 동일한 효과이다.) 마우스로 클릭도 가능하다.

vim *와 |를 가리고 syntax highlighting을 해 주기 때문에 사용자가 보기에는 깔끔한 table of contents로 보인다.

Sections

다음과 같이 section header를 만들 수 있다.

====================================================================
Section 1: Usage                                       *PotionUsage*

This plugin with automatically provide syntax highlighting for
Potion files (files ending in .pn).

It also...

*로 감싼 태그가 위의 목차에서 추가한 링크와 동일한지 잘 확인해주자.

나머지 섹션도 헤더를 추가해주자.

Examples

help 파일에 사용되는 모든 문법을 나열할 수도 있겠지만, 이는 취향 차이가 있다. 따라서 나는 아주 잘 documentation이 작성된 몇몇 vim plugin들을 보여줄 것이다.

각각의 help 텍스트에서 filetype을 help와 text로 변경해 보면 어떤 방식으로 적용되는지 볼 수 있다.

vimscript skill을 사용하여 현재 버퍼의 filetype을 help와 text로 토글시켜주는 키 매핑을 만들 수 있을 것이다.

• Clam, my own plugin for working with shell commands. It's a pretty short example that hits most of the sections I talked about.
• The NERD tree, a file navigation plugin by Scrooloose. Note the general structure, as well as how he summarizes the mappings in an easy-to-read list before explaining every one in detail.
• Surround, a plugin for handling "surrounding" characters by Tim Pope. Note the lack of a table of contents, the different style of section headers, and the table column headers. Figure out how these things were done, and decide if you like them. It's a matter of taste.
• Splice, my own plugin for resolving three-way merge conflicts in version control systems. Note how the lists of mappings are formatted, and how I used ASCII-art diagrams to explain layouts. Sometimes a picture really is worth a thousand words.

vanila vim documentation도 많은 예시를 제공해주는 것을 기억하라.

Write!

이제 documentation의 구조가 잡혔으니 섹션을 채우기만 하면 된다.

만약 이런 technical documentation을 써 보지 않았더라면 꽤 도전일 수 있다. 적는 것을 배우는 것은 확실히 쉽지 않지만 다른 스킬들처럼 꼭 연습이 필요하지, 일단 해 보라. 나중에 더 고칠 수 있으니 완벽할 필요는 없다.

완전히 확신하지 못하는 것에 대해 적는 것을 두려워하지 말아라. 나중에 그냥 날려버리고 다시 적을 수 있다.

시작하기 좋은 방법 중 하나는 당신의 친구가 당신의 vim setting을 사용한다고 상상해 보는 것이다. 당신의 플러그인을 사용해 본 적은 없지만 흥미가 있을 것이고, 당신의 목표는 그들을 꽤 숙련된 유저로 만드는 것이다. 실제 사람에게 설명하는 것을 생각한다면 너무 technical하가 쓰지 않고 좋은 글을 쓸 수 있을 것이다.

아직도 막혀 있고 전체 플러그인에 documentation을 쓸 기분이 아니라면 작은 것부터 시작해보라. ~/.vimrc 파일의 매핑을 하나 고른 다음에 코멘트로만 document를 작성해 보라. 무엇을 위한 것이고, 어떻게 사용하며 어떻게 동작하는지 적어보라. 다음은 나(저자)의 ~/.vimrc 예시이다.

" "Uppercase word" mapping.
"
" This mapping allows you to press <c-u> in insert mode to convert the
" current word to uppercase.  It's handy when you're writing names of
" constants and don't want to use Capslock.
"
" To use it you type the name of the constant in lowercase.  While
" your cursor is at the end of the word, press <c-u> to uppercase it,
" and then continue happily on your way:
"
"                            cursor
"                            v
"     max_connections_allowed|
"     <c-u>
"     MAX_CONNECTIONS_ALLOWED|
"                            ^
"                            cursor
"
" It works by exiting out of insert mode, recording the current cursor
" location in the z mark, using gUiw to uppercase inside the current
" word, moving back to the z mark, and entering insert mode again.
"
" Note that this will overwrite the contents of the z mark.  I never
" use it, but if you do you'll probably want to use another mark.
inoremap <C-u> <esc>mzgUiw`za

전체 플러그인의 documentation보다는 짧지만, 적는 연습용으로는 충분히 좋다. 다른 사람들의 ~/.vimrc를 읽는 것도 많은 도움이 된다.

Exercises

• Write the documentation for each section of the Potion plugin.

• Read :help help-writing for help about writing help.

• Read :help :left, :help :right, and :help :center to learn about three useful commands for getting your ASCII art perfect.