Linux man 페이지의 단점을 해결하는 TL;DR 프로젝트


개요

리눅스와 유닉스는 man 명령으로 유용한 정보를 많이 담고 있는 매뉴얼 페이지(manual page)를 볼수 있지만 가독성이 좋지 않고 사용자에게 친절하지 않기로 유명합니다.


전통적인 이유는 Technical writer 같은 전문 직종이 없었고 유닉스의 사용자가 곧 개발자였으므로 친절하지 않은 딱딱한 매뉴얼도 이해하는데 큰 문제가 없었습니다.

설사 이해가 되지 않는 부분이 있었어도 소스 코드에 접근할 수 있었으므로 소스 코드를 보면서 동작 방식을 이해하면 되므로 manual page 의 가독성은 별 문제가 되지 않았습니다.


하지만 이제는 사용자가 곧 개발자가 아니며 활용법을 알기 위해 소스 코드를 들여다 볼수 있는 시대가 아닙니다.

최근의 개발자들은 익혀야 할 지식의 폭이 너무 넓고 프레임워크와 도구의 홍수에 빠져 익사할 지경이라 불친절한 manual page 를 보기 어려우므로 커뮤니티를 중심으로 사용 예제 중심의 심플한 manual 을 만드는 TL;DR 프로젝트가 github 를 통해서 진행되고 있습니다.


TL;DR 을 사용하면 아래와 같이 사용 예제 위주로 편리하게 명령어 매뉴얼을 확인할 수 있습니다.


man tar

man tar


tldr tar

tldr tar


한 눈에 비교해 봐도 tl;dr 은 사용 예제별로 표시해 주니 실무적으로 많은 도움이 되는 것을 알 수 있습니다.

자세한 동작 방식을 알아보려면 여전히 man 명령을 사용하는 게 필요합니다.


설치

tl;dr 을 읽기 위한 다양한 client 가 있는데 먼저 추천하는 방법은 https://tldr.ostera.io/에 접속해서 web broswer 를 통해서 보는 것입니다. 


2번째로 유용한 클라이언트는 프로젝트 팀에서 추천하는 nodejs 로 작성한 client 로 아래 명령어로 설치하면 됩니다.

nodejs client 설치
$ npm i -g tldr 


저는 windows 를 주력으로 사용하며 패키지 관리자로는 scoop 을 사용하는데 다음 명령어로 scoop 용 tldr 을 설치할 수 있습니다.

scoop install tldr


go 로 된 client 는 다음 명령어로 설치하면 됩니다.

go get -u github.com/isacikgoz/tldr


그외의 클라이언트 목록은 https://tldr.sh/ 에서 확인할 수 있습니다.

사용

tldr 을 옵션없이 실행하면 사용법을 출력합니다.

$ tldr

Usage: tldr command [options]

Simplified and community-driven man pages

Options:
  -V, --version            output the version number
  -l, --list               List all commands for the chosen platform in the cache
  -a, --list-all           List all commands in the cache
  -1, --single-column      List single command per line (use with options -l or -a)
  -r, --random             Show a random command
  -e, --random-example     Show a random example
  -f, --render [file]      Render a specific markdown [file]
  -m, --markdown           Output in markdown format
  -o, --os [type]          Override the operating system [linux, osx, sunos]


tl;dr 형식의 매뉴얼 목록을 보려면 -l 옵션을 주고 실행하면 됩니다

$ tldr -l


매뉴얼 목록은 개행이 되지 않으므로 원하는 매뉴얼이 있는지 확인이 어렵습니다. 이럴때 개행을 해주는 옵션인 -1 을 추가하고 pipe 로 grep 을 연결해서 원하는 명령어에 대한 tl;dr 이 있는지 확인하면 됩니다.

예로 아래는 curl 이 있는지 확인하는 명령어입니다.

$ tldr -l -1 |grep curl

curl


또는 키워드를 검색하는 -s 옵션과 키워드를 주고 실행하면 됩니다. curl 을 키워드로 검색하면 curl 과 http 두 개의 tl;dr 이 나오는 것을 확인할 수 있습니다.

$ tldr -s curl

Searching for: curl

    $ curl
    $ http

Run tldr <command> to see specific pages.


명령어에 대한 tl;dr 이 있는게 확인되었으니 tl;dr 을 보려면 명령어 이름을 옵션으로 주고 실행하면 됩니다.


$ tldr curl



tldr 은 테마를 지원하는데 기본 테마인 simple 은 밋밋해서 가독성이 떨어집니다. -t 옵션으로 테마를 설정할 수 있으며 base16 과 ocean 이 있습니다.

저는 개인적으로 ocean 테마가 더 보기가 좋았습니다.

$ tldr curl -t ocean



tl;dr 매뉴얼은 속도를 위해 local 에 캐시되며 업데이트된 매뉴얼을 받으려면 -u 옵션을 주고 실행합니다.

$ tldr -u

✔ Updating...                                                                                               
✔ Creating index... 


Ref