ROBODoc은 문서를 직접 생성한다. 일부 Documentation Tool처럼 중간과정에서 파일을 생성하고 다시 그 파일을 다른 문서형식으로 변환하는 방식이 아니라 HTML이든 LaTex든 상관 없이 소스코드에서 바로 문서를 생성해준다.
ROBODoc 문서화에는 세가지 모드가 있다.
singledoc 모드는 출력되는 문서를 하나의 파일로 저장한다. 반면 multidoc은 문서를 여러개의 작은 조각으로 나누어 준다. 이 모드는 browser로 보아야 하는 HTML형식의 문서를 출력할 때 매우 좋다. singlefile 모드는 디버깅 목적으로 존재한다고 하는데 정확히 무슨 뜻인지는 잘 모르겠다.
다음 4가지의 출력 포맷을 지원한다. 옆에는 각각의 출력포맷에 따른 옵션을 적어놓았다.
RTF, --rtf HTML, --html LaTeX, --latex XML DocBook, --dbxml |
ROBODoc에 사용되는 몇가지 중요한 옵션들이다.
--doc 문서가 출력될 path를 지정한다. --index master index 파일을 생성해준다. 실제로 해보면 multidoc 모드와 함께 쓰여질 때에만 생성된다. html 파일을 생성할 경우 masterindex.html파일이 생성된다. --multidoc 하나의 소스당 하나의 문서를 생성한다. 디렉토리 구조를 계층구조로 사용한다. --nodesc subdirectory 를 제외하고 top directory에 대해서만 문서화를 한다. --src source 파일과 디렉토리를 지정한다. |
앞서 서술한 모드,출력포맷은 이름 그대로 옵션으로 사용한다. 예를 들어 multidoc모드는 --multidoc 옵션으로 넣어준다.
robodoc.rc파일은 robodoc사용을 최적화 하기 위한 설정 파일이다. robodoc.rc파일에는 item의 추가, 변환 옵션의 지정등이 가능하다. 다음은 manual에 나온 robodoc.rc파일의 예이다.
robodoc.rc
items:
NAME
SYNOPSIS
INPUTS
OUTPUTS
HISTORY
ignore items:
HISTORY
BUGS
options:
--src
./source
--doc
./doc
--html
--multidoc
--index
extensions:
.bak
~ |
이 파일을 수정해 현재 작업 디렉토리에 넣어두고 robodoc을 실행시키면 된다.
이제 만들어진 header를 이용하여 실제 문서를 생성하는 예를 보도록 하겠다. 아래의 예제에서는 source 디렉토리의 상위디렉토리에서 실행한 것이다. source의 top directory를 %source%라 하겠다.
HTML로 출력시
#robodoc --src ./%source% --doc ./docs --multidoc --index --html
%source% 에 있는 소스를 이용하여 ./docs 디렉토리에 문서를 생성하게 된다. html형식으로 출력하고 multidoc 모드이므로 파일을 나누게 된다. --index 옵션에 의해 masterindex.html파일을 생성한다. 주의할 것은 --src나 --doc 옵션 다음에 디렉토리가 올 경우 반드시 ./ 나 / 로 시작해야 한다는 것이다. 이를 지키지 않으면 에러 메세지를 보게 된다.
RTF로 출력시
#robodoc --src ./%source% --doc docu --singledoc --rtf --sections
rtf는 browse 할 수 있는 파일이 아니므로 --singledoc 옵션으로 변환한다. 위 명령의 결과로 docu.rtf 파일이 생성된다.
LaTex로 출력시
#robodoc --src ./%source% --doc docu --singledoc --latex --sections
결과로 docu.tex파일이 생성된다. 생성된 tex파일을 ps,dvi등으로 변환하는 것은 다른 문서를 참고하라. 아직 한글로는 실험해보지 않았기 때문에 한글이 잘 출력되는지는 장담할 수가 없다.