정보 [+]

위키-DocBook 변환

소개

위키-DocBook을 이용하면 복잡한 태그 입력 없이 DocBook XML 문서를 손 쉽게 만들어 낼 수 있습니다.

차례 [+]

문서의 구조

최상위 요소

최상위 요소(article, book, chapter, set 등)는 항상 !!!!으로 시작. !!!! 다음의 텍스트는 그 요소의 제목( title )이 됩니다. 최상위 요소는 선택 가능. ( 문서 종류 참고).

문서 정보

문서에 대한 정보는

@정보이름 값;값...

형태입니다. 문서 정보들은 문서 어느 곳에 위치해도 됩니다만 최상위 제목 아래에 넣는 게 깔끔하겠죠.

현재 지정할 수 있는 정보는 다음과 같습니다.

[참고]

인코딩이나 문자집합에 따라 정보이름 키워드가 달라지는 것은 비효율적이므로, 2005년 2월 버전부터는 @ 다음에 오는 정보 이름들을 모두 영문 알파벳으로 바꾸었습니다. 따라서 기존 문서에서 문서 정보를 사용한 부분을 적절히 변경할 필요가 있습니다. 변경된 이름들을 요약하자면:

예전	지금
지은이, 글쓴이	author
엮은이	editor
옮긴이	translator
고침	rev
종류	type
헤더	header

author, editor, translator(지은이, 엮은이, 옮긴이)

지은이, 엮은이, 옮긴이는 각각 author, editor, othercredit(role="translator") 요소에 해당합니다. 셋 다 생략 가능, 임의의 조합 가능, 복수 출현 가능.

형태는 @author/@editor/@translator 성 이름;주소 . 주소 생략 가능, 성도 생략 가능.

예:

@author 홍 길동;hgd(at)yuldo.net
@translator 임 꺽정
@editor 나

<authorgroup>
	<author>
	<surname>홍</surname><firstname>길동</firstname>
	<affiliation>
 	<address><email>hgd(at)yuldo.net</email>
	</address>
	</affiliation>
	</author>

	<othercredit role="translator">
	<surname>임</surname><firstname>꺽정</firstname>
	</othercredit>

	<editor>
	<surname>나</surname>	</editor>

</authorgroup>

rev(고침 내역)

revision 요소에 해당. 생략 가능, 복수 출현 가능, revhistory로 묶임.

형태는 @rev 버전;날짜;고친이;설명

예:

@rev 1.1 ;2002-04-26;gryu;고침 옵션 테스트
@rev 1.0 ;2002-04-23;gryu;최초 업로드

<revhistory>
	<revision>
	<revnumber>1.1</revnumber>
	<date>2002-04-26</date>
	<authorinitial>gryu</authorinitial>
	<revremark>고침 옵션 테스트</revremark>
	</revision>

	<revision>
	<revnumber>1.0</revnumber>
	<date>2002-04-23</date>
	<authorinitial>gryu</authorinitial>
	<revremark>최초 업로드</revremark>
	</revision>

</revhistory>

type(종류)

문서의 종류를 명시합시다. 생략 가능, 생략 시 기본은 article. 형태는

 @type 종류이름

종류 이름이 그대로 최상위 요소 이름과 DTD 선언의 이름으로 쓰이며, 변환 시 유효한 문서 종류인지 점검하지는 않습니다. 따라서 종류를 webpage로 하고 몇몇 부분을 수정하는 형식으로 website 용 문서를 만드는 것도 가능합니다.

예: 이 페이지 제일 위에 지정된 것과 이 페이지의 DocBook 소스 루트 요소를 비교해 보시길!

header(헤더)

문서 처음에 포함될 XML 선언, DTD 선언을 지정합니다. 생략 가능, 생략 시에는 DTD 선언 없이 XML 선언만 포함됩니다. 다음과 같은 형태들이 가능합니다.

@header XML: XML 선언만. @header를 생략한 것과 같음
@header DTD: XML 선언과 기본 DTD 선언.
@header DTD;DTD URI: XML 선언과 DTD 선언, DTD URI를 직접 지정하는 형태
@header none: XML, DTD 모두 없음. XML 개체 형태로 다른 닥북 문서에 포함시키고자 할 때 유용.

XML 선언은 항상 다음과 같은 형태입니다. XML 선언의 encoding은 DbWiki 인코딩 설정을 따릅니다.

 <?xml version="1.0" encoding="utf-8"?>

기본 DTD 선언은 기본적으로는 다음과 같은 형태입니다.

<!DOCTYPE 문서종류 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">

DTD의 DocBook XML 버전 번호는 DbWiki 버전에 따라 다를 수 있습니다.

[참고]

기본 DTD는 index.php 중간 부분의 $DefaultDTD 변수에 설정되어 있습니다.

DTD URI는 DTD 선언 중 "<!DOCTYPE 문서종류" 와 마지막 ">" 사이에 들어가는 부분입니다. 예를 들면

@header DTD;SYSTEM "path/to/docbookx.dtd"

문서 종류가 chapter일 경우 위의 옵션은 다음과 같이 확장됩니다.

<?xml version="1.0" encoding="euc-kr"?>
<!DOCTYPE chapter SYSTEM "path/to/docbookx.dtd">

// 주석기능

문서의 내용이나 포매팅 등에 대한 주석을 삽입하는 기능입니다.

@// 이것은 주석. 우아~  --류광

이것은 주석. 우아~ --류광

DocBook 소스에는 로 들어갑니다. --> 와의 충돌을 피하기 위해, 주석 내용 중 --는 -로 치환됩니다.

다른 문서 정보들은 문서 전체에 영향을 미치며 DocBook 소스의 시작 부분에 삽입되지만, 주석은 해당 위치에 직접 삽입되며 문서 전체에는 영향을 미치지 않습니다.

섹션들

섹션은 !!!, !!, ! 중 하나. !의 개수가 섹션의 깊이를 지정하는 방식입니다. 적을 수록 하위 섹션입니다.

섹션 깊이가 3 이상이라면, _!, _!!, _!!! .... 식으로 계속 들어가는 것도 가능하긴 합니다. 이 경우에는 !가 많을 수록 하위 섹션입니다. 그러나 이런 것들을 사용하는 것 보다는 part - chapter - article 식으로 문서 자체를 분할하는 게 더 낫다고 봅니다.

예:

!!!! 문서 제목

!!! 서론

...

!!! 본론

...(블럭)...

!! 단원 1

...(블럭)...

! 소단원 1

...(블럭)...

! 소단원 1

...(블럭)...

_! 더 낮은

_!! 더욱 낮은

_!!! 더더욱 낮은 섹션

!!! 결론

...(블럭)...

하위 섹션 예:

소단원

소소

소소소

HTML에서는 여기가 H6에 해당. 즉 더 이상은 의미가 없음. DocBook의 경우에는 가능하긴 하지만 하나의 문서가 이렇게까지 깊이 들어가는 것은 별로 좋지 않은 것 같아요.

섹션 안에 들어가는 블럭 구조들

문단

빈 줄(줄바꿈 두 번)로 구분된 텍스트는 문단(para)이 됩니다.

목록은 #나 *로 시작.

번호 있는 목록

번호가 매겨지는 목록은 #로 시작.

# 하나
## 하나 반
## 또 하나 반
# 둘
## 둘 반
### 둘의 '''반의 반'''
# 셋

하나
1. 하나 반
2. 또 하나 반
둘
1. 둘 반
  1. 둘의 반의 반
셋

번호 없는 목록

번호가 없는 목록은 *로 시작. 각 항목을 개별 줄로, 항목 사이에 빈 줄이 없어야 같은 목록의 항목들로 인식됩니다.

* 하나
** 하나 반
** 또 하나 반
* 둘
** 둘 반
*** 둘의 반의 반
* 셋

하나
- 하나 반
- 또 하나 반
둘
- 둘 반
  - 둘의 반의 반
셋

정의 목록

DocBook의 variablelist에 해당. ;과 :로 구성됩니다.

; 용어1 : 용어1의 정의
; 용어2 : 용어2의 정의

용어1: 용어1의 정의
용어2: 용어2의 정의

목록의 인라인 마크업

목록의 텍스트에도 인라인 마크업들이 그대로 적용됩니다.

예:

* DocBook  '''문서화'''
** http://www.docbook.org/tdg/en/html/docbook.html
* [내부링크 | #interlink]

# DocBook  '''문서화'''
## http://www.docbook.org/tdg/en/html/docbook.html
# [내부링크 | #interlink]

; '''DocBook 한국♡ 프로젝트''' : KldpNet의 프로젝트 페이지는 http://kldp.net/projects/docbook/

DocBook 문서화
- http://www.docbook.org/tdg/en/html/docbook.html
내부링크

DocBook 문서화
1. http://www.docbook.org/tdg/en/html/docbook.html
내부링크

DocBook 한국♡ 프로젝트: KldpNet의 프로젝트 페이지는 http://kldp.net/projects/docbook/

포매팅 유지

프로그램 소스 코드 등 포매팅이 그대로 유지되어야 하는 부분은 {{{ 와 }}} 로 감쌉 니다. {{{, }}} 모두 개별적인 줄로 존재해야 하며 줄 제일 처음에 나와야 함.

 #include <string>
 using namespace std;

이 경우에는 programlisting 요소가 됩니다. 다른 요소로 하려면, {{{ 다음에 요소 이름을 직접 써주면 됩니다.

 {{{screen
 Volume in drive C is SYSTEM         Serial number is 2350:717C
 ...
 }}}

또는 줄의 제일 첫 칸을 빈칸으로 해도 동일한 효과가 됩니다. 이 경우는 무조건 programlisting.

 한 칸 띄면 이렇게.

테이블

테이블 항목들은 모두 |로 시작하구요. |!는 테이블 제목 , |{는 헤더(thead), |}는 푸터(tfoot). 나머지 |들은 테이블 각 칸들을 구분하는 역할을 합니다.

예를 보면 쉽게 알 수 있을 것입니다.

|! 테이블 예제
|{ 헤더1 | 헤더2 |헤더3
| 1-1 | 1-2 | 1-3
| 2-1 | 2-2 | 2-3
| 3-1 | 3-2 | 3-3
|} 꼬리1 | 꼬리2 |꼬리3

테이블 예제

헤더1	헤더2	헤더3
1-1	1-2	1-3
2-1	2-2	2-3
3-1	3-2	3-3
꼬리1	꼬리2	꼬리3

테이블에서 |!를 사용하지 않으면 title 요소가 없는 informaltable이 됩니다.

| 1-1 | 1-2 | 1-3
| 2-1 | 2-2 | 2-3
| 3-1 | 3-2 | 3-3

1-1	1-2	1-3
2-1	2-2	2-3
3-1	3-2	3-3

블럭 이미지

이미지(이미지 참고)가 줄의 제일 앞에 나오면, 즉 대괄호가 제일 첫 글자이면 블럭 이미지(mediaobject)가 됩니다.

예:

닫는 대괄호 이후부터 줄 끝까지는 mediaobject 내부의 caption 요소가 됩니다.

이 부분은 캡션

범용 블럭과 블럭 이미지를 결합하면 figure 요소를 구현할 수 있습니다.

그림 예

자~알 생긴 오리

(((figure  그림 예 ::example_figure::
[http://occam.n4gate.com/dbwiki/images/dbwiki.png] 자~알 생긴 오리
)))

각주

각주는 대괄호와숫자를 통해서 표현합니다. 각주 표시가 될 위치를 이렇게 표기해주고^[1], 같은 숫자를 감싸는 대괄호로 시작하는 줄을 따로 만들어서 각주의 내용을 적으면 됩니다.

각주 표시가 될 곳에 이렇게 [1]

....

[1] 실제 각주는 이렇게

[1] 숫자를 감싼 대괄호로 시작하는 줄은 해당 각주 번호에 대한 실제 각주가 됩니다.

범용 블럭

다음과 같이 ((( ))) 를 이용하면 범용 블럭을 지정할 수 있습니다.

범용 블럭

이것은 범용 블럭을 이용한 example 요소의 예이다. 범용 블럭은 ((( 다음에 블럭 요소 이름을 써주고,

그 뒤에 블럭 제목을 써주고,
블럭 내용을 넣은 후

끝에 )))로 닫으면 됨.

(((example 범용 블럭  ::example_block::
이것은 범용 블럭을 이용한 example 요소의 예이다. 범용 블럭은 ((( 다음에 블럭 요소 이름을 써주고,
* 그 뒤에 블럭 제목을 써주고,
* 블럭 내용을 넣은 후
끝에 )))로 닫으면 됨.
)))

섹션 제목과 마찬가지로, 제목 끝에 :: 를 이용해서 블럭의 id를 지정할 수 있음. id가 있으므로 링크 대상이 될 수 있다. 그림 예

범용 블럭은 내포될 수 없음. 그 외의 것은 대부분 허용되나 범용 블럭 안에 섹션 헤더가 있으면 최종 DocBook 소스의 적격성이 보장되지 않는다.

인라인 마크업들

블럭 안에서 부분 문자열 단위로 적용되는 것들입니다.

링크

외부 링크

외부 링크는 대괄호로 표시할 수 있습니다. 링크텍스트 처럼 링크 텍스트와 URL을 세로줄로 구분합니다. http://url.net 처럼 URL만 써주면 그 URL이 링크텍스트가 되는 형식으로 링크가 걸립니다.

[링크텍스트 | http://url.net]

링크텍스트

외부 링크는 닥북 XML의 ulink 요소가 됩니다.

내부 링크

내부 링크는 ID 또는 링크텍스트 형태입니다. 여기서 ID 는 섹션 제목(!..) 옆에 ::ID:: 형태로 지정된 것입니다. 이 섹션의 !! 내부 링크 ::interlink:: 처럼요... 예: 내부링크

[#ID], [링크텍스트 | #ID] [내부링크 | #interlink]

이런 링크는 닥북 XML의 link 요소가 됩니다.

다른 페이지의 내부 링크

다른 페이지의 특정 일부분을 직접 가리킬 수 있습니다. 이런 형태입니다.

[페이지이름#ID], [링크 텍스트|페이지이름#ID]

페이지 이름이 영문 위키 이름 형태라고 해도 내부 링크를 걸기 위해서는 반드시 대괄호로 감싸야 합니다.

닥북 XML은 외부 링크와 마찬가지로 ulink 요소가 됩니다. (link 요소가 되게 하는 게 바람직하나, 여러 페이지들에 걸친 닥북 XML 생성에 대한 정책이 서지 않았기 때문에 일단은 ulink로 했습니다.)

이미지

인라인 이미지는 나 처럼 문단 중간에서 대괄호 안에 이미지 파일 이름(확장자를 통해 식별됨)을 넣으면 됩니다.

이렇게 [../images/dbwiki.png]나 [http://img.kldp.org/static/kldpnet.png]

이미지가 줄의 제일 앞에 나오면, 즉 대괄호가 제일 첫 글자이면 블럭 이미지(mediaobject)가 됩니다. 블럭 이미지 참고.

강조

작은따옴표 세 개의 쌍으로 둘러싸인 부분은 강조(emphasis)가 됩니다.

'''강조(emphasis)'''

인용

작은따옴표 두 개로 둘러싸인 부분은 "인용(quote)"이 됩니다. 문장 안의 인용(inline quote)에 해당. 인용구(block quote)는 아직 지원 안 됩니다. DbWiki(HTML) 상에서는 그냥 직접 큰따옴표를 사용한 것과 다를 바 없지만, XML 소스에서는 <quote> 요소가 됩니다.

This software is provided ''as is'', without expressed
or implied warranty.

범용 인라인

F1 처럼 {{ 다음에 DocBook 요소 이름을 쓰고, 한 칸 띄우고 요소 내용을 쓰고 }}로 닫으면 됩니다. 태그가 내포되지 않는 단순한 인라인 요소들에 사용할 수 있습니다.

{{keycap F1}}

주석기능

문서 내부에 주석을 첨가하는 방법 (주석기능 참고)

있는 그대로 - DocBook 태그를 그대로 사용

프로그램 소스 코드와 비슷한 방식으로 줄 제일 처음의 <<<와 역시 줄 제일 처음의 >>> 사이에 있는 것들은 변환 없이 그대로 출력됩니다. 이를 이용해서 현재 Wiki-DocBook에서 지원하지 않는 DocBook 태그들을 그대로 문서에 집어 넣을 수 있습니다.

<<<
    <head>
      <title>DocBook 한국♡ 홈페이지</title>
      <summary>DocBook 한국 홈페이지</summary>
      <keywords>
        DocBook, XML, SGML, 공개 문서, 전자 문서, 문서, 형식, 포맷
      </keywords>
    </head>
>>>

    <head>
      <title>DocBook 한국♡ 홈페이지</title>
      <summary>DocBook 한국 홈페이지</summary>
      <keywords>
        DocBook, XML, SGML, 공개 문서, 전자 문서, 문서, 형식, 포맷
      </keywords>
    </head>

header	DTD
type	chapter
author	류 광;gryu(at)korea.com
rev	1.3.5; 2005-04-23; gryu; 다른 페이지의 내부 링크에 대한 설명 추가
rev	1.3.5; 2005-02-28; gryu; 옵션 단어 변경사항 및 각주 설명 추가
rev	1.3.4; 2003-08-09; gryu; 블럭 이미지 설명 추가
rev	1.3.3; 2003-07-22; dyaus; 중복된 주석기능 설명 정리
rev	1.3.2; 2003-06-21; gryu; 내부 링크 문법 변경
rev	1.3.1; 2003-06-11; dyaus;주석기능 설명 추가
rev	1.3; 2003-06-02; dyaus;mediaobject, 범용 블럭기능 추가
rev	1.2; 2003-05-18; gryu; 정의 목록 설명 추가, 목록의 인라인 마크업 지원 내용 추가
rev	1.1; 2003-04-26; gryu; 고침 옵션 테스트
rev	1.0; 2003-04-23; gryu; 최초 업로드
numbering	example,note

Wiki To Doc Book

위키-DocBook 변환

문서의 구조

최상위 요소

문서 정보

author, editor, translator(지은이, 엮은이, 옮긴이)

rev(고침 내역)

type(종류)

header(헤더)

// 주석기능

섹션들

소단원

소소

소소소

섹션 안에 들어가는 블럭 구조들

문단

목록

번호 있는 목록

번호 없는 목록

정의 목록

목록의 인라인 마크업

포매팅 유지

테이블

블럭 이미지

각주

범용 블럭

인라인 마크업들

링크

외부 링크

내부 링크

다른 페이지의 내부 링크

이미지

강조

인용

범용 인라인

주석기능

있는 그대로 - DocBook 태그를 그대로 사용