나는 리눅스와 FreeBSD를위한 작은 C 라이브러리를 작성했고 이에 대한 문서를 작성할 것이다. 매뉴얼 페이지 작성에 대해 자세히 알아 보려고했으나 라이브러리 매뉴얼 페이지를 작성하는 우수 사례에 대한 지시 사항 또는 설명을 찾지 못했습니다. 특히 함수의 맨 페이지를 넣을 섹션에 관심이 있습니까? 삼? 좋은 예나 매뉴얼이 있습니까? 라이브러리에서 각 기능에 대한 매뉴얼 페이지를 만드는 것이 좋지 않습니까?
답변
라이브러리의 매뉴얼 페이지는 섹션 3에 있습니다.
매뉴얼 페이지의 좋은 예를 들어, 일부는 groff의 특정 세부 사항을 사용하여 작성되거나 실제로 이식성이없는 특정 매크로를 사용한다는 점을 명심하십시오.
일부 시스템은 특수 기능을 사용하거나 사용하지 않을 수 있으므로 맨 페이지의 이식성에는 항상 약간의 함정이 있습니다. 예를 들어, 문서화에서 dialog, 나는 정당화되지 않은 예제를 표시하기 위해 다양한 시스템의 차이점을 명심하고 해결해야했습니다.
에 의해 시작 읽기 의 관련 부분 man man은 표준 매크로를 언급 곳, 그리고 비교 로 FreeBSD와 리눅스에 대한 그 설명을.
라이브러리에 대해 하나의 매뉴얼 페이지를 작성하도록 선택하는지 또는 함수 (또는 기능 그룹)에 대해 별도의 매뉴얼 페이지를 작성하는지 여부는 함수에 대한 설명이 얼마나 복잡한 지에 따라 다릅니다.
- ncurses 에는 수십 개의 매뉴얼 페이지에서 수백 가지 기능이 있습니다.
- 대화 상자 에는 하나의 매뉴얼 페이지에 수십 가지 기능이 있습니다. 다른 사람들은 더 많은 예를 보여줄 것입니다.
더 읽을 거리 :
답변
나는 ronn을 사용 합니다 . 간단히 마크 다운을 작성하면 맨 페이지로 바뀝니다. 또한 mark-man 이라는 (복잡성이 떨어지는) js 클론이 있습니다 .
END_MAN구분 된 heredocs 를 사용하여 스크립트를 문서화 END_MAN하고을 제외하고 동일한 구분 된 heredocs를 사용하여 C / C ++ 코드를 작성했습니다 /* */. sed로 쉽게 추출한 다음 맨 페이지로 렌더링 할 수 있습니다. (Inotifywait와 함께 약간의 UNIX 신호 해커를 사용하면 맨 페이지 섹션을 실시간으로 추출하여보고 맨 페이지 브라우저를 소스 업데이트로 다시로드 할 수 있습니다.)
섹션의 경우 사용자 수준 C 라이브러리의 경우 3이됩니다. man (1) 의 섹션 번호에 대해 읽을 수 있습니다 .
당신은 어떤 읽을 수있는, 잘 구조화 된 예를 매뉴얼 페이지를보고 싶다면, 나는 Plan9 한 번 봐 걸릴 것 https://swtch.com/plan9port/unix/ 어떻게 바로의 제작자 볼 수있는 라이브러리 c와 UNIX그 문서를 시스템은 아마도 이러한 것들이 작동하도록 의도되었습니다.
답변
다른 답변을 보충하기 위해 매뉴얼 페이지 작성을 단순화하는 데 사용할 수있는 또 다른 마크 다운 언어는 reStructuredText 및 python-docutils 패키지의 일부인 rst2man 명령입니다 .
이 마크 다운 언어는 문서화를 위해 파이썬에 의해 채택되었으며 , rst2man이 reStructuredText에서 당신을 위해 생성하는 좋은 오래된 troff man 매크로보다 배우고 쓰고 유지하는 것이 훨씬 쉽습니다.
답변
doxygen 을 사용하여 API를 문서화하여 HTML로 참조를 제공하고 오프라인 읽기를위한 매뉴얼 페이지 및 기타 형식을 생성 할 수도 있습니다.
doxygen의 이점은 JavaDoc 또는 PythonDoc과 같은 일종의 “인라인”문서이며 인터페이스 주석으로 두 배가되는 것입니다 (또는 vv. 문서 텍스트를 소스 / 헤더 파일에 추가하고 여기에서 추출하여 최신 상태를 유지할 가능성을 높입니다.