JtestR 관련 두번째 글을 작성하고 blogger 에 올리려고 했을 때 잠시 좌절했었다. 소스 코드와 함께 예쁘게 포맷되어서 올려진 다른 글들을 보고는 기본 에디터에서 소스라고 지정해줄 수 있을 것이라고 생각했던 것이다. 소제목들과 소스만 영역 설정해서 표시해주면 될 것이라고 생각했었는데 너무 많은 것을 기대했었다는 것을 올리려는 순간에야 알았다.
참고로한 소스 코드와 함께 올려졌으면서도 예쁘게 포맷된 블로그 포스트의 경우 이미 HTML 출력을 지원하는 에디터의 손을 거친 것이었다. 어떻게 해야하나? 우선은 별 생각 없이 HTML 이나 Blog 저작 툴이라고 되어 있는 것들을 깔아보고 하나를 고를 계획이었다.
그렇지만, HTML 편집을 직접하는 것은 원하지 않았다. 포맷팅에 신경을 쓰지 않고 글을 쓰고 싶었다. Docbook 이나 LaTeX 같은 것을 쓸까? 한 페이지 블로그 엔트리 작성에 그것들을 사용하는 것은 아무래도 오버라는 생각이 들었다.
그렇게 HTML 저작 툴들이 깔려가고 있을 때 떠오른 것이 RDoc 이다.
RDoc ?
RDoc 은 Javadoc 이나 Doxygen 과 비슷한 부류의 프로그램이다. Ruby 소스의 주석으로부터 문서를 만들어내는 도구이지만 소스 파일이 아닌 경우도 포맷팅을 해준다.
RDoc 에서 지원해주는 Markup 들이 딱 내가 필요로하는 정도였다.
- 빈 줄로 단락 구분
- 들여쓰기로 verbatim 처리 (소스 표시에 좋다.)
- 다양한 목록 처리 (일반, numbered, labeled)
- http: ftp: 등의 링크 표시의 간편함
- =로 단락 제목 (Heading)
예를 들어서 위 내용의 변환 전 소스는 아래와 같다.
== RDoc ? RDoc[http://rdoc.rubyforge.org/] 은 Javadoc 이나 Doxygen 과 비슷한 부류의 프로그램이다. Ruby 소스의 주석으로부터 문서를 만들어내는 도구이지만 소스 파일이 아닌 경우도 포맷팅을 해준다. RDoc 에서 지원해주는 Markup[http://rdoc.rubyforge.org/classes/RDoc/Markup.html] 들이 딱 내가 필요로하는 정도였다. * 빈 줄로 단락 구분 * 들여쓰기로 verbatim 처리 (소스 표시에 좋다.)
원래의 JtestR 글을 조금 만져주었더니 RDoc 의 소스로 바로 사용이 가능했다. (링크, 헤딩(Heading), 소스 들여쓰기) 문제는 RDoc 이 Ruby 문서화를 위한 도구이기 때문에 기본 출력이 blog 포스팅에 사용하기에는 불편하다는 점이다. 우선은 인코딩과 출력 양식을 조절해 줄 필요가 있다.
rdoc -1 -c utf-8 rdoc_as_html_writing.rdoc -n without_template.html
- -1
- 한개의 html 파일로 출력
- -c utf-8
- 인코딩은 utf-8
- -n without_template.html
- without_template.html 파일로 출력
원하는 단계에 거의 다 왔다. 하지만 여전히 RDoc 의 기본 출력은 군더더기 들이 많아서 불편하다.
예를들면 without_template.html 의 내용은 아래와 같다.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>RDoc Documentation</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<h2>File: rdoc_as_html_writing.rdoc</h2>
<table>
<tr><td>Path:</td><td>rdoc_as_html_writing.rdoc</td></tr>
<tr><td>Modified:</td><td>Mon Sep 01 11:11:45 +0900 2008</td></tr>
</table>
<h1>RDoc 을 blog 작성 도구로</h1>
<p>
...
<h2>Classes</h2>
</body>
</html>
여기서 파일 이름이나 날짜가 나올 필요도 없고, 관련 Classes 가 나올 필요도 없고 오로지 <body> 테그 안의 </table> 이후의 내용만 있으면 된다. 어떻게? 템플릿을 조금 손 보면 된다.
RDoc 의 기본 팀플릿 중 one_page_html.rb 를 가져다가 손을 보았다.
cp /usr/lib/ruby/1.8/rdoc/generators/template/html/one_page_html.rb blog_template.rb
수정 후의 blog_template.rb
module RDoc
module Page
######################################################################
#
# The following is used for the -1 option
#
CONTENTS_XML = %{
IF:description
%description%
ENDIF:description
}
########################################################################
ONE_PAGE = %{
START:files
} + CONTENTS_XML + %{
END:files
}
end
end
많은 내용이 있었지만 우리의 목적에는 이것으로 충분하다. 소스 코드가 아닌 파일의 경우에는 그냥 description 으로 처리가 된다.
템플릿을 사용하는 것은 —template 옵션을 사용한다.
최종에 가까워 지는 Rakefile 내용이다. (최종 룰은 아래에서 완성된다.)
rule '.html' => '.rdoc' do |t|
sh "rdoc -1 -c utf-8 --template ./blog_template.rb #{t.source} -n #{t.name}"
end
이제 해당 html 생성은 rake some_file.html 하면 된다.
포스팅
이제 첫째줄을 제목으로 해서 나머지 내용을 올리면 포스팅이 완료된다.
(생성된 html을 blogger.com 에 올릴 때 주의할 점은 "설정"=>"서식" 에서 "줄바꿈 전환" 을 "아니오"로 해 두어야 한다는 것이다. 그렇지 않으면 원하는 결과가 아닌 수시로 줄바꿈이 있는 결과를 보게 된다. 미리보기에는 반영이 안되기 때문에 편집기에 복사해 붙이고 미리보기를 할 경우에는 당황스러울 수 있다.)
(소스 코드 부분의 배경색을 바꿔주기 위해서 "레이아웃"=>"HTML 편집"을 하고 CSS 부분에 <pre> 태그의 스타일을 추가했다.
pre {
background: #dddddd;
}
)
헤딩 조절
기본적으로 blogger 는 포스트 제목에 <h3> 헤딩을 사용한다.(blogger 템플릿에 따라서 다른 지는 모르겠다.) 하지만 RDoc 은 <h1> 부터 출력을 만들어낸다. 그대로 사용하면 전체 적인 조화가 흐트러지는 문제가 생긴다.
해결방법은
- 그냥 조화가 흐트러진 채로 쓴다. - (지금까지는 이렇게 했다.)
- 작성시부터 <h3> 이후의 헤딩을 사용한다. (=== 부터 사용)
- 전처리를 통해서 헤딩을 바꿔주고 그 파일로부터 html을 만들어 준다.
- RDoc 처리를 바꾼다. (단순히 RDoc 템플릿을 수정하는 것으로는 해결이 안 되는 것 같다.)
정도를 생각해 볼 수 있었다. 첫번째는 해결방법이 아니고, 두번째는 적절한 방법이 아니다. 세번째 방법은 간단히 할 수 있다.
Rakefile .html 룰 처리에 변환 코드를 넣었다.
rule '.html' => '.rdoc' do |t|
h3_heading = IO.read("#{t.source}").map do |l|
l[/^=/] = '===' if l[/^=/]
l
end
tmp_file = "__#{t.source}"
#
tmp_file = tmp_file.gsub!(/[\.\/\\]/,'_')
File.open(tmp_file, "w") { |f| f.write(h3_heading) }
sh "rdoc -1 -c utf-8 --template ./blog_template.rb #{tmp_file} -n #{t.name}"
rm tmp_file
end
이제 되었다. 이 글을 변환하고 올려 보아야겠다. ^^
글
