@@ -55,159 +55,4 @@ Gildong Hong <email1@bwg.com> <2>
----
== 매뉴얼 관리
매뉴얼 관련된 리소스들은 GitLab을 통해서 유지 관리된다. SWD팀에서는 관련 리소스와 매뉴얼탬플릿 그리고 시각화를 위한 Style, CSS 등을 유지 관리한다. R&D에서는 각 제품별, 버전별로 매뉴얼을 작성하고 유지 관리한다. 국제화를 위해서 각 나라의 언어별로 프로젣트를 구분하여 리소스를 관리하는 구조를 갖고 있다.
=== Repository 구조
----
📒 repository (swlab-docs) <1>
📄 antora-playbook.yml <2>
📂 getting-started <3>
📄 antora.yml <4>
📂 modules <5>
📂 ROOT <6>
📂 images <8>
📄 image-source-file.png <9>
📂 pages <10>
📄 page-source-file.adoc <11>
📄 nav.adoc <12>
📂 guide-like-bgbook <7>
📂 images
📄 image-source-file.png
📂 pages
📄 page-source-file.adoc
📄 nav.adoc
📂 ready-to-write <7>
📂 images
📄 image-source-file.png
📂 pages
📄 page-source-fi le.adoc
📄 nav.adoc
----
<1> 팀별로 구성
<2> 필수 구성 파일
: 사이트, 콘텐츠 원본 및 UI URL을 구성
<3> 콘텐츠 원본 루트
<4> 필수 구성 파일
: 이름, 버전, 메타데이터, 속성 및 탐색 목록을 구성
<5> 필수 모듈 디렉토리
<6> ROOT 모듈 디렉토리
: ROOT 모듈의 페이지는 구성 요소 버전의 최상위 페이지가 되므로 다른 모듈에서 참조하는 공통 리소스를 저장한다.
+
[CAUTION]
====
기본 셋팅되어 있는 리소스는 수정/제거하지 않도록 주의한다.
====
<7> 명명된 모듈 디렉토리
: 필요한 만큼 생성 가능하고 생성할 때는 xref:./00aboutManual.adoc#module_name_rule["모듈 디렉토리 명명 규칙"]에 준하여 생성한다.
<8> 이미지 디렉터리
<9> 이미지 소스 파일
: PNG, JPG, SVG 및 GIF(정적 및 애니메이션) 이미지 파일 형식을 지원한다.
<10> pages 디렉토리
: 하나 이상의 AsciiDoc 소스 파일이 포함되어야 한다.
<11> 페이지의 원본 파일
: AsciiDoc 구문으로 마크업되고 유효한 .adoc 파일 확장명으로 저장된 페이지 파일
<12> 내비게이션 파일
: 사이트 탐색 파일로써 모듈당 하나의 탐색 파일을 가진다. xref:./00aboutManual.adoc#nav_file["내비게이션 파일"]을 참고하여 작성한다.
[#antora_yml]
=== 필수 구성 파일 (antora.yml)
antora.yml 파일은 구성 요소 버전을 식별, 설명 및 구성하는 필수 및 선택적 정보를 제공한다.
[source,yml]
----
name: swlab-docs <1>
title: SWLab Docs <2>
version: '2.0' <3>
start_page: ready-to-write:text-editor.adoc <4>
asciidoc: <5>
attributes:
source-language: asciidoc@
table-caption: false
nav: <6>
- modules/ready-to-write/nav.adoc
- modules/guide-like-bgbook/nav.adoc
----
.키 설명
[cols="25,75a"]
|===
|키
|설명
|1) name
|* 구성 요소 버전을 식별하는 데 사용되는 구성 요소 이름으로 리소스 ID의 구성 요소 좌표 및 구성 요소 버전의 게시된 리소스에 대한 구성 요소 URL 세그먼트에서 사용된다.
|2) title
|* 왼쪽 메뉴 페이지에 표시되는 목적으로 사용되는 구성 요소 이름으로 공백, 대문자 및 다양한 문자를 사용할 수 있다.
|3) version
|* 구성 요소 버전을 식별하는 데 사용되는 버전으로 리소스 ID의 버전 좌표 및 구성 요소 버전의 게시된 리소스 URL에 대한 버전 세그먼트로 사용된다.
|4) start_page
|* 페이지를 구성 요소 버전의 홈 페이지로 지정한다.
형식) 모듈명:페이지 (ROOT모듈은 모듈명 작성시 생략한다.)
|5) asciidoc.attributes
|* **수정금지!** 기본 제공 및 사용자 정의 AsciiDoc 속성 및 페이지 속성을 나타내고 antora.yml의 속성은 구성 요소 버전에 속하는 모든 페이지와 리소스(해당되는 경우)에 적용되므로 수정하지 않습니다.
|6) nav
|* 왼쪽 메뉴 페이지 구성에 사용될 탐색 파일 목록을 설정한다.
** 한 줄에 하나씩 입력한다.
** 들여쓰지 않는다.
** 각 값을 하이픈(-)으로 시작하고 그 뒤에 공백을 입력한다.
** 공백 뒤에 antora.yml 파일의 위치를 기준으로 개별 탐색 파일의 경로를 입력한다.
** 나열된 순서로 왼쪽 메뉴 페이지가 구성된다.
|===
[#module_name_rule]
=== 모듈 디렉토리 명명 규칙
모듈 이름은 페이지, 이미지, 첨부 파일, 예제 및 부분의 리소스 ID에서 모듈 좌표로 사용된다. 또한 해당 모듈에 할당된 게시 가능한 리소스의 URL에도 사용된다(ROOT 모듈 제외). 따라서 모듈 폴더 이름을 선택할 때 다음 사항을 지켜 생성한다.
* 공백이나 슬래시(/)를 포함할 수 없다.
* 대문자, 밑줄(_) 및 URL에서 권장되지 않는 기타 문자를 사용하지 않는다.
* 너무 길거나 기억하기 어렵게 만들지 말고 짧고 설명적으로 만든다.
[#nav_file]
=== 내비게이션 파일
탐색 파일은 사이트의 왼쪽메뉴를 구성한다. 작성 방법은 다음과 같다.
==== 파일 이름 및 형식
탐색 파일은 **nav.adoc**으로 명명한다.
탐색 파일에는 하나 이상의 글머리 기호 목록이 포함되어 있다.
목록의 각 항목은 페이지에 대한 상호 참조, 사이트에 속하지 않은 웹 사이트의 URL 또는 중첩된 목록 항목 집합을 그룹화하는 범주 제목과 같은 연결되지 않은 텍스트일 수 있다.
==== 목록 구조
탐색 목록은 순서가 지정되지 않은 AsciiDoc 목록이다. 파일에 여러 목록이 포함된 경우 각 목록은 목록 제목으로 시작해야 하고 각 최상위 목록 항목은 최대 2 Level까지만 허용한다.
[NOTE]
====
최상위 목록 항목은 점(.)으로 표시되는 목록 제목이거나, 목록 제목이 없는 경우 단일 별표(*)로 표시된 각 목록 항목을 말한다.
====
[discrete]
==== AsciiDoc 소스
탐색 파일을 작성하는 AsciiDoc 소스는 다음과 같다.
[source,asciidoc]
----
.가이드
* xref:00aboutManual.adoc[]
** xref:00_1writing.adoc[]
* xref:01title.adoc[]
----
[discrete]
==== 결과
탐색 파일을 작성한 메뉴 형태는 다음과 같다.
[NOTE]
====
메뉴의 각 항목은 문서 제목으로 표시된다.
====
****
.Navigation file (Site)
image::figure0_1.png["내비게이션 파일",800]
****
==== 내비게이션 등록
필수 구성 파일인 xref:./00aboutManual.adoc#antora_yml["antora.yml"]에 등록한다.
xref:./00_2management.adoc#manual_management["매뉴얼 관리"] 메뉴에서 설명한다.
