Linux에서 매뉴얼 페이지를 만드는 방법

새로운 Linux 프로그램이 전문적으로 보이기를 원하십니까? 매뉴얼 페이지를 제공하십시오. 가장 쉽고 빠른 방법을 알려드리겠습니다.

남자 페이지

오래된 Unix 농담에 진실의 핵심이 있습니다. 필요한 명령만 아는 것이 사람이다.” 매뉴얼 페이지에는 풍부한 지식이 포함되어 있으며 명령에 대해 배우고 싶을 때 맨 처음으로 살펴보아야 합니다.

작성한 유틸리티 또는 명령에 대한 매뉴얼 페이지를 제공하면 유용한 코드에서 완전한 형태의 Linux 패키지로 향상됩니다. 사람들은 Linux용으로 작성된 프로그램에 대한 매뉴얼 페이지가 제공되기를 기대합니다. 기본적으로 Linux를 지원하는 경우 프로그램을 진지하게 받아들이려면 매뉴얼 페이지가 필수입니다.

역사적으로 매뉴얼 페이지는 일련의 서식 지정 매크로를 사용하여 작성되었습니다. 사람에게 페이지를 열도록 요청하면 groff를 호출하여 파일을 읽고 형식이 지정된 출력을 생성합니다., 파일의 매크로에 따라. 출력은 less로 파이프된 다음 당신을 위해 표시.

매뉴얼 페이지를 자주 작성하지 않는 한 매뉴얼 페이지를 작성하고 수동으로 매크로를 삽입하는 것은 힘든 작업입니다. 올바르게 구문 분석되고 올바르게 보이는 매뉴얼 페이지를 만드는 작업은 명령에 대한 간결하면서도 철저한 설명을 제공하려는 목표를 능가할 수 있습니다.

모호한 매크로 집합과 싸우지 말고 콘텐츠에 집중해야 합니다.

구조를 위한 판독

그만큼 판독 프로그램 마크다운 파일을 읽고 매뉴얼 페이지를 포함하여 약 40개의 다른 마크업 언어 및 문서 형식으로 새 파일을 생성합니다. 맨 페이지 작성 프로세스를 완전히 변환하므로 상형 문자와 씨름할 필요가 없습니다.

시작하려면 다음 명령을 사용하여 Ubuntu에 pandoc을 설치할 수 있습니다.

sudo apt-get install pandoc

Fedora에서 필요한 명령은 다음과 같습니다.

sudo dnf install pandoc

Manjaro에서 다음을 입력합니다.

sudo pacman -Syu pandoc

man 페이지의 섹션

매뉴얼 페이지에는 표준 명명 규칙을 따르는 섹션이 있습니다. 매뉴얼 페이지에 필요한 섹션은 설명하는 명령의 정교함에 따라 결정됩니다.

최소한 대부분의 매뉴얼 페이지에는 다음 섹션이 포함되어 있습니다.

이름: 명령의 이름과 그 기능을 설명하는 간결한 한 줄짜리입니다.
개요: 누군가가 프로그램을 시작하는 데 사용할 수 있는 호출에 대한 간략한 설명입니다. 허용되는 명령줄 매개변수의 유형을 보여줍니다.
설명: 명령 또는 기능에 대한 설명입니다.
옵션: 명령줄 옵션 목록과 그 기능.
예: 일반적인 사용법의 몇 가지 예.
종료 값: 가능한 반환 코드와 그 의미.
버그: 알려진 버그 및 단점의 목록입니다. 때때로 이것은 프로젝트의 이슈 트래커에 대한 링크로 보완(또는 대체)됩니다.
작성자: 명령을 작성한 사람 또는 사람들.
저작권: 귀하의 저작권 메시지. 여기에는 일반적으로 프로그램이 릴리스되는 라이센스 유형도 포함됩니다.

좀 더 복잡한 매뉴얼 페이지를 살펴보면 다른 섹션도 많이 있음을 알 수 있습니다. 예를 들어, man man을 시도하십시오. 하지만 모두 포함할 필요는 없습니다. 정말 필요한 것만 포함하면 됩니다. man 페이지는 장황한 말을 하는 곳이 아닙니다.

합리적으로 자주 볼 수 있는 다른 섹션은 다음과 같습니다.

참조: 일부가 유용하거나 관련성이 있다고 생각되는 주제와 관련된 기타 명령.
파일: 패키지에 포함된 파일 목록입니다.
주의 사항: 알거나 주의해야 할 기타 사항.
기록: 명령에 대한 변경 기록입니다.

매뉴얼 섹션

Linux 매뉴얼은 모든 매뉴얼 페이지로 구성되며 다음과 같이 번호가 매겨진 섹션으로 나뉩니다.

실행 프로그램: 또는 쉘 명령.
시스템 호출: 커널에서 제공하는 기능.
라이브러리 호출: 프로그램 라이브러리 내의 함수.
특수 파일.
파일 형식 및 규칙: 예: “/etc/passwd”.
계략.
기타: groff와 같은 매크로 패키지 및 규칙.
시스템 관리 명령: 일반적으로 루트용으로 예약되어 있습니다.
커널 루틴: 일반적으로 기본적으로 설치되지 않습니다.

모든 매뉴얼 페이지는 그것이 속한 섹션을 나타내야 하며, 나중에 보게 될 것처럼 해당 섹션의 적절한 위치에도 저장되어야 합니다. 명령 및 유틸리티에 대한 매뉴얼 페이지는 섹션 1에 속합니다.

매뉴얼 페이지의 형식

groff 매크로 형식은 시각적으로 구문 분석하기 쉽지 않습니다. 대조적으로, 마크다운은 산들 바람입니다.

아래는 groff의 매뉴얼 페이지입니다.

같은 페이지가 아래의 마크다운에 표시됩니다.

서문

처음 세 줄은 전면 물질이라고 불리는 것을 형성합니다. 이것들은 모두 백분율 기호(%)로 시작해야 하며 선행 공백 없이 하나 뒤에 와야 합니다.

첫 번째 줄: 명령 이름을 포함하고 그 뒤에 공백 없이 수동 섹션이 괄호 안에 표시됩니다. 이름은 매뉴얼 페이지 헤더의 왼쪽 및 오른쪽 섹션이 됩니다. 관례에 따라 명령 이름은 대문자이지만 그렇지 않은 경우가 많습니다. 명령 이름과 매뉴얼 섹션 번호 뒤에 오는 것은 바닥글의 왼쪽 섹션이 됩니다. 소프트웨어 버전 번호로 사용하면 편리합니다.
두 번째 줄: 저자의 이름. 이들은 매뉴얼 페이지의 자동 생성 작성자 섹션에 표시됩니다. “작성자” 섹션을 추가할 필요는 없습니다. 여기에 하나 이상의 이름만 포함하면 됩니다.
세 번째 줄: 바닥글의 중앙 부분이 되는 날짜.

이름

섹션은 마크다운의 헤더를 나타내는 마크업인 숫자 기호(#)로 시작하는 줄로 표시됩니다. 숫자 기호(#)는 줄의 첫 번째 문자여야 하고 그 뒤에 공백이 와야 합니다.

이름 섹션에는 명령 이름, 공백, 하이픈(-), 공백 및 명령이 수행하는 작업에 대한 매우 짧은 설명이 포함된 간결한 한 줄짜리 항목이 있습니다.

개요

시놉시스는 명령줄이 취할 수 있는 다양한 형식을 담고 있습니다. 이 명령은 검색 패턴이나 명령줄 옵션을 받아들일 수 있습니다. 명령 이름의 양쪽에 있는 두 개의 별표(**)는 해당 이름이 매뉴얼 페이지에서 굵게 표시됨을 의미합니다. 별표 하나

일부 텍스트의 양쪽에 있으면 매뉴얼 페이지에 밑줄이 그어진 내용이 표시됩니다.

기본적으로 줄 바꿈 다음에 빈 줄이 옵니다. 빈 줄 없이 강제로 중단하려면 후행 백슬래시()를 사용할 수 있습니다.

설명

설명은 명령 또는 프로그램이 수행하는 작업을 설명합니다. 중요한 세부 사항을 간결하게 다루어야 합니다. 사용자 가이드를 작성하는 것이 아님을 기억하십시오.

줄 시작 부분에 두 개의 숫자 기호(##)를 사용하면 수준 2 제목이 만들어집니다. 이를 사용하여 설명을 더 작은 덩어리로 나눌 수 있습니다.

옵션

옵션 섹션에는 명령과 함께 사용할 수 있는 모든 명령줄 옵션에 대한 설명이 포함되어 있습니다. 관례에 따라 굵게 표시되므로 앞뒤에 별표 두 개(**)를 포함합니다. 다음 줄에 옵션에 대한 텍스트 설명을 포함하고 콜론(:)으로 시작하고 그 뒤에 공백이 옵니다.

설명이 충분히 짧으면 man은 명령줄 옵션과 같은 줄에 설명을 표시합니다. 너무 길면 명령줄 옵션 아래 줄에서 시작하는 들여쓰기 단락으로 표시됩니다.

예

예제 섹션에는 다양한 명령줄 형식이 포함되어 있습니다. 옵션 섹션에서와 마찬가지로 설명 줄을 콜론(:)으로 시작한다는 점에 유의하십시오.

종료 값

이 섹션에서는 명령이 호출 프로세스로 다시 보내는 반환 값을 나열합니다. 명령줄에서 호출한 경우 셸일 수 있고 셸 스크립트에서 시작한 경우 스크립트일 수 있습니다. 이 섹션에서도 콜론(:)으로 설명 줄을 시작합니다.

버그

버그 섹션에는 사람들이 알아야 할 알려진 버그, 문제 또는 단점이 나열되어 있습니다. 오픈 소스 프로젝트의 경우 여기에 프로젝트의 이슈 트래커에 대한 링크를 포함하여 버그의 상태를 확인하거나 새로운 버그를 보고하는 것이 일반적입니다.

저작권

저작권 섹션에는 귀하의 저작권 진술과 일반적으로 소프트웨어가 릴리스되는 라이센스 유형에 대한 설명이 포함됩니다.

효율적인 워크플로

좋아하는 편집기에서 매뉴얼 페이지를 편집할 수 있습니다. 구문 강조 표시를 지원하는 대부분은 마크다운을 인식하고 텍스트에 색상을 지정하여 제목을 강조 표시하고 굵게 표시하고 밑줄을 긋습니다. 그것이 진행되는 한 훌륭하지만 푸딩의 실제 증거인 렌더링된 매뉴얼 페이지를 보고 있지 않습니다.

pandoc ms.1.md -s -t man | /usr/bin/man -l -

마크다운 파일이 포함된 디렉토리에서 터미널 창을 엽니다. 편집기에서 연 상태에서 주기적으로 파일을 하드 드라이브에 저장하십시오. 그럴 때마다 터미널 창에서 다음 명령을 실행할 수 있습니다.

이 명령을 사용한 후에는 위쪽 화살표를 눌러 반복한 다음 Enter 키를 누를 수 있습니다.

이 명령은 또한 마크다운 파일(여기서는 “ms.1.md”라고 함)에서 pandoc을 호출합니다.
-s(독립 실행형) 옵션은 man 형식의 일부 텍스트가 아닌 위에서 아래로 완전한 매뉴얼 페이지를 생성합니다.

“man” 연산자가 있는 -t(출력 유형) 옵션은 pandoc에 man 형식으로 출력을 생성하도록 지시합니다. 우리는 pandoc에게 출력을 파일로 보내라고 지시하지 않았으므로 stdout으로 보낼 것입니다.

또한 -l(로컬 파일) 옵션을 사용하여 해당 출력을 man으로 파이핑하고 있습니다. man 페이지를 찾는 man 데이터베이스를 검색하지 말라고 man에게 알려줍니다. 대신 명명된 파일을 열어야 합니다. 파일 이름이 -이면 man은 stdin에서 입력을 받습니다.

요약하면 편집기에서 저장하고 터미널 창에서 실행 중인 경우 Q를 눌러 man을 닫을 수 있다는 것입니다. 그런 다음 위쪽 화살표를 누른 다음 Enter 키를 눌러 man 페이지의 렌더링된 버전을 man 바로 내부에서 볼 수 있습니다.

매뉴얼 페이지 만들기

pandoc ms.1.md -s -t man -o ms.1

매뉴얼 페이지를 완성한 후에는 최종 버전을 만든 다음 시스템에 설치해야 합니다. 다음 명령은 “ms.1″이라는 매뉴얼 페이지를 생성하도록 pandoc에 지시합니다.

이것은 설명하는 명령 다음에 매뉴얼 페이지의 이름을 지정하고 마치 파일 확장자인 것처럼 매뉴얼 섹션 번호를 추가하는 규칙을 따릅니다.

manpath

이것은 우리의 새로운 매뉴얼 페이지인 “ms.1” 파일을 생성합니다. 어디에 넣어요? 이 명령은 man이 man 페이지를 검색하는 위치를 알려줍니다.

결과는 다음 정보를 제공합니다.
/usr/share/man: 매뉴얼 페이지의 표준 라이브러리 위치. 우리는 이 라이브러리에 페이지를 추가하지 않습니다.
/usr/local/share/man: 이 심볼릭 링크는 “/usr/local/man”을 가리킵니다.

/usr/local/man: 여기에 새로운 매뉴얼 페이지를 배치해야 합니다.

man1, man2, man3 등의 다른 매뉴얼 섹션이 자체 디렉토리에 포함되어 있습니다. 섹션에 대한 디렉토리가 존재하지 않으면 생성해야 합니다.

sudo mkdir /usr/local/man/man1

이렇게 하려면 다음을 입력합니다.

sudo cp ms.1 /usr/local/man/man1

그런 다음 “ms.1” 파일을 올바른 디렉토리에 복사합니다. man 페이지가 압축될 것으로 예상하므로 gzip을 사용할 것입니다.그것을 압축

sudo gzip /usr/local/man/man1/ms.1

:

sudo mandb

man이 새 파일을 데이터베이스에 추가하도록 하려면 다음을 입력하십시오.

man ms

그게 다야! 이제 다음을 입력하여 새 매뉴얼 페이지를 다른 매뉴얼 페이지와 동일하게 호출할 수 있습니다.

새로운 매뉴얼 페이지가 발견되어 표시됩니다.

적절한 위치에 굵게, 밑줄, 들여쓰기된 텍스트가 있는 다른 매뉴얼 페이지처럼 보입니다.

설명하는 옵션 옆에 맞는 설명 줄은 같은 줄에 나타납니다. 너무 길어서 맞지 않는 줄은 설명하는 옵션 아래에 나타납니다.

또한 “작성자” 섹션을 자동으로 생성했습니다. 바닥글에는 앞문에 정의된 대로 소프트웨어 버전 번호, 날짜 및 명령 이름도 포함됩니다.

당신이 원하는 경우. . .