Guide XML
기본적인 구조
이제 여러분은 guide XML문서를 변환 할 수 있게 되었다.
여러분은 guide XML 의 문법을 배울 준비가 된 것이다.
우리는 이제 guide XML 문서의 초기화 태그를 시작할 것이다.
<?xml version='1.0'?>
<guide>
<title>Gentoo Linux Documentation Guide</title>
<author title="Chief Architect"><mail link="drobbins@gentoo.org">
Daniel Robbins</mail>
</author>
<author title="Editor"><mail link="thomasfl@gentoo.org">
Thomas Flavel</mail>
</author>
<abstract>This guide shows you how to compose web documentation using
our new lightweight Gentoo guide XML syntax. This syntax is the official
format for Gentoo Linux web documentation, and this document itself was created
using guide XML. </abstract>
<version>1.0</version>
<date>29 Mar 2001</date>
첫번째 라인은 이 문서가 XML 문서라는것을 알려주는 식별자 태그이다.
다음에 따라오는 문장은 <guide> 태그이다. -- 전체적인
가이드 문서는 <guide> </guide> 두쌍의 태그로 둘러
싸인다.
다음으로, <title> 태그가 온다, 전체 문서의 제목을 정할때 쓰는
태그이다.
다음으로 따라오는 태그는 <author> 태그이다, 해당문서에 대한
여러명의 저자의 정보를 포함 할 수가 있다.
각각의 <author> 태그는 title=
요소를 옵션으로 가진다. 문서에 대한 저자들끼리의 특수한 관계도
표현 할수 있다.(저자, 공저자, 수정인, 그외...).
이와 같은 예에서, 저자의 이름은 another 태그로 묶인다. --
<mail> 태그는 특정인의 이메일 주소를 표시할때 쓰인다.
<mail> 태그는 선택사항이므로 생략해도 상관없다. 그리고
더이상의 <author> 요소는 하나의 가이드 문서에서 더이상 요구되지
않는다.
다음으로 나오는 <abstract>, <version> 과
<date> 는, 문서의 개략적인 요약사항을 표시하는 태그이다,
각각 현재 버전 번호와 현재 버전의 날짜 ( DD MMM YYYY 형식) 을 뜻한다.
여기까지가 가이드 문서의 시작부분이고 이제부터 본격적인 가이드 문서의 내용이
시작된다.
<title> 과 <mail>태그는
더이상 직접적으로 <guide>태그안에 나타나지 않는다.
그리고 이들 태그는 문서의 실질적인 내용이 시작하기 전에 사용하는것을
권한다.(반드시 필요한것도 아니다.)
챕터와 섹션
초기화 태그를 작성할 수 있다면, 여러분은 이제 문서에 실질적인 내용을
추가할 수 있는 준비가 된것이다.
가이드 문서는 챕터로 나뉘어 있고, 각각의 챕터는 한개 이상의 섹션으로
구성되어 있다.
각각의 챕터와 섹션은 제목을 가지고 있다.
아래에 한개짜리 섹션을 가진 챕터의 예가 나와 있다. 한단락 한단락에 대해 잘
생각해 보아라.
만약 여러분이위에 있는 인용문 과 아래에 있는
XML문서를 붙이고 그 아래에</guide> 를 첨가해서 파일을 만들면,
여러분은 아주 작고 간단한 guide XML문서를 만들 수 있을 것이다.
<chapter>
<title>This is my chapter</title>
<section>
<title>This is section one of my chapter</title>
<body>
<p>This is the actual text content of my section.</p>
</body>
</section>
</chapter>
위에서, 나는 <title> 태그를 <chapter> 태그안에 하부 요소로 이용했다.
그리고 섹션을<section> 태그를 이용해 만들었다. 만약 여러분이
<section> 의 안을 본다면, 여러분은 두개의 하부 요소를 볼 수 있을 것이다. --
<title> 과 <body> 태그이다. 이제 더이상 <title>
태그는 새롭지 않다, <body> 는 -- 현재 부분단락의 실질적인 내용을 담고 있는 태그이다.
우리는 <body>태그안의 요소가 한 조각을 이루고 있음을 볼 수 있다.
<guide> 요소는 여러개의
<chapter>요소를 포함 할 수 있다. 그리고 <chapter>요소는 여러개의
<section>요소를 포함 할 수 있다. 그러나 <section>
요소는 오직 한개의 <body> 요소만을 포함한다.
<body>의 예
이제, 실질적인 내용을 어떻게 작성하는가에 대해 배울 시간이 왔다!. 여기에 XML코드로
<body> 를 어떻게 구성해야 하는지에 대해 설명하고 있다.
<p>
이것은 문단이다. <path>/etc/passwd</path> 는 파일이다.
<uri>http://www.gentoo.org</uri> 는 내가 좋아하는 웹사이트이다.
<c>ls</c> 는 여러분 맘대로 생각해라. 나는 <e>존나게(-_-)</e> 졸립다.
</p>
<pre>
이것은 텍스트 출력이거나 코드이다.
# <i>이것은 여러분의 입력이다</i>
HTML/XML 은 읽기 쉽게금 선택적으로 강조할 수 있다:
<foo><i>bar</i></foo>
<codenote>이것은 코드 블럭 안에서 어떻게 첨부내용을 쓸 수 있는지를 알려준다</codenote>
</pre>
<note>이것은 노트다</note>
<warn>이것은 경고다</warn>
<impo>이것은 중요한 내용이다</impo>
이 아래로는 위의
<body> 요소안의 코드가 어떻게 랜더링 되었는지에 대해 나온다.
이것은 문단이다. /etc/passwd 는 파일이다.
http://www.gentoo.org 는 내가 좋아하는 웹사이트이다.
ls 는 여러분 맘대로 생각해라. 나는 존나게(-_-) 졸립다.
이것은 텍스트 출력이거나 코드이다.
# 이것은 여러분의 입력이다
HTML/XML 은 읽기 쉽게금 선택적으로 강조할 수 있다:
<foo>bar</foo>
이것은 코드 블럭 안에서 어떻게 첨부내용을 쓸 수 있는지를 알려준다
이것은 노크다
이것은 경고다
이것은 중요한 내용이다
<body> 태그
우리는 이전 섹션에서 새로운 많은 태그에 대한 소개를 보았다. -- 이제는 여러분이 알기 원하는 내용이 나온다
<p> (문단), <pre> (코드 블럭), <note>, <warn> (경고) 와
<impo> (중요) 태그들은 한줄이상의 텍스트 정보를 가질 수 있다. 덧붙여
<table> 요소 (테이블에 대해서는 약간만 설명한다)와 함께,
이들 태그들은 오로지 <body> 요소 안에 바로 사용해야 한다. 다른점들 -- 이 태그들은
중첩해서 사용하면 안된다. -- 다시 말해서, <note> 요소를
<p> 요소 안에서 쓸 수 없다. 아마 여러분이 생각하기에,<pre> 요소
는 공백을 그대로 보존하니까, 프로그램 코드를 넣는데 적당하다고 볼것이다. 맞는 생각이다.
<path>, <c> 와 <e>
<path>, <c> 와 <e> 요소는
<body>태그안에서 <pre>를 제외한 모든 하부포함 태그 안에서 사용될 수 있다.
<path> 요소는
디스크상의 파일을 표시하거나 가르키는데 사용한다.
-- 절대경로나 상대경로 둘다로 표현이 가능하다, 아니면 간단한 파일 이름등을 표시할때 쓴다.
이 요소는 일반적으로 표준 문단 타입에서 고정폭 글꼴로 랜더링 된다.
<c> 요소는 명령어 나 사용자의 입력내용등을 표시하는데 사용한다.
<c> 를 또한 세심한 주의를 요하는 입력이나, 주의해서 읽어야 할 부분 등에 사용하는 방법도 생각해볼만 하다.
예를 들어,이 문서의 모든
XML태그들은 <c> 태그에 둘러쌓여 표시된다.
왜냐면 사용자가 경로가 아닌것을 입력할 수 있도록 설명해야 하기 때문이다.
<c> 요소를 사용해서, 여러분은 여러분의 글을 읽는 독자들이 보다 쉽고 빠르게 명령어와 그들이 입력해야
할것들을 구분해 내도록 도와줄 수 있다.
또한, <c> 요소는 고정폭 글꼴이다, 그래서 유저의 입력을 큰따옴표로 묶을 필요가 없다.
예를 들어, "<c>" 이런식으로 표현하지 말라는 말이다.
위에처럼 큰따옴표를 사용하지 않는 문서형식을 문서를 더욱 보기 쉽게 만들어준다.-- 사랑스러울정도로! (역자주:-_-)
<e> 는 단어나 문장을 강조하는데 사용한다; 예를 들어:
나는 정말로 세미콜론을 더 많이 써야 한다. 여러분이 보듯이, 이 글자는
강조를 위해 폭이 조정된다. 이는 여러분의 문서를 보다 멋지게!
해준다
<mail> 과 <uri>
우리는 <mail> 태그를 저 앞에서 먼저 보았다; 이 태그는 어떤 문장을 특정한 이메일 주소로 링크를 걸어준다.
<mail link="foo@bar.com">Mr. Foo Bar</mail>이런식으로 사용하면 된다.
<uri> 태그는 인터넷상의 파일이나 주소를 표시할때 사용한다.
이건 두가지 형식을 가지는데 -- http://www.gentoo.org처럼 문서안에서 링크 이름을 그대로
출력해서 링크에 접근하는 방식이다.이 링크를 만들려고, 난
<uri>http://www.gentoo.org</uri>라고 입력했다. 나머지 다른 형식은 링크이름을 다른 문장으로 대체해
문서에는 URI가 직접 드러나지 않는 방식이다. -- 예를 들면 the Gentoo Linux website와 같은거다. 이 링크를 만들려면
<uri link="http://www.gentoo.org">the Gentoo Linux website</uri> 라고 입력하면 된다.
그림
문서에 그림을 어떻게 삽입해야 하는지를 설명한다 -- <figure
link="mygfx.png" short="my picture" caption="my favorite picture of all
time"/>이렇게 입력한다. link= 그래픽이미지의 파일이름,
short= 그래픽 이미지의 간단한 설명 (HTML alt= 속성을 이용한다), 그리고 제목 으로 구성된다.
뭐.. 그리 어렵지 않다. :)
우리는 또한 HTML-스타일의 <img src="foo.gif"/> 태그도 지원한다.
이경우 이미지에 테두리나, 제목 등을 지원하지 못한다.
테이블과 리스트
guide XML은 HTML과 비슷한 테이블 태그를 지원한다.
테이블의 시작은, <table> 태그를 사용해서 시작한다. 한줄은<tr>태그로
그러나, 실질적인 데이터의 입력에서, 우리는 HTML 방식의 <td> 를 사용하지 않는다.
만약에 헤더를 입력했으면, 일반적인 정보는 <ti>태그로 입력한다.
여러분은 또한 <th>태그도 사용할 수 있다. 어디든지 <ti> 태그를 사용할 수 있다 --
이는 <th> 요소를 필요로 하지 않는다. 이건 오로지 줄의 첫번째에서만 나타난다.
일반적으로, 이 태그는 다른 특별한 속성을 지원하지 않는다. 그러나 몇가지는
추가 할 수 있다 (예를 들어 <table> 에서 caption= 속성을 쓸 수 있다 ).
순정렬 혹은 역순정렬 리스트를 만들려면, 간단한 HTML-style 을 사용하면 된다.
<ol>, <ul> 과 <li> 태그들말이다.
리스트 태그들은 <p>, <ti>,
<note>, <warn> 나 <impo> 태그 안에서 사용되어야 한다.
문서 레퍼런스
가이드 문서는 정말로 쉽게 문서의 다른 부분을 하이퍼링크를 이용해 레퍼런싱 할 수 있다.
여러분은 chaper1의 링크를 <uri link="#doc_chap1">ChapterOne</uri>
라고 타이핑 함으로써 만들 수 있다.
section two of Chapter One는
<uri link="#doc_chap1_sect2">section two of Chapter One</uri>라고 타이핑 함으로써 만들 수 있다.
그림 3을 참조하는 링크는, <uri link="doc_fig3">figure 3</uri>라고 타이핑 하면 된다.
또한 code listing 2는 <uri link="doc_pre2">code listing 2</uri>
라고 타이핑하면 만들어진다.
우리는 곧 자동링크 기능을 (테이블을 지원하는) 추가할 것이다.