Main Content

이 번역 페이지는 최신 내용을 담고 있지 않습니다. 최신 내용을 영문으로 보려면 여기를 클릭하십시오.

사용자 지정 문서 표시하기

개요

MathWorks® 제품과 함께 작동하는 툴박스를 만드는 경우, 단지 몇 가지 함수만 있는 툴박스일지라도 HTML 도움말 파일 형식의 사용자 지정 문서를 포함시킬 수 있습니다. 툴박스에 대한 사용자 지정 문서에는 Figure, 도식, 화면 캡처, 수식, 서식 지정을 사용하여 더 유용한 툴박스 도움말을 만들 수 있습니다.

사용자 지정 문서가 제대로 표시되려면 다음 파일을 포함해야 합니다.

  • HTML 도움말 파일 — 이 파일에는 사용자 지정 문서에 대한 정보가 들어 있습니다.

  • info.xml 파일 — 이 파일은 MATLAB®이 HTML 도움말 파일을 찾아 식별할 수 있게 해 줍니다.

  • helptoc.xml 파일 — 이 파일에는 도움말 브라우저의 목차 창에 표시되는, 문서의 목차가 들어 있습니다. 이 파일은 HTML 도움말 파일이 포함된 폴더에 저장해야 합니다.

  • 검색 데이터베이스(선택 사항) — 이러한 파일은 HTML 도움말 파일에서 검색할 수 있게 해 줍니다.

사용자 지정 문서를 보려면 도움말 브라우저를 열고 홈 페이지로 이동하십시오. 홈 페이지 하단에 있는 추가 소프트웨어에서 툴박스 이름을 클릭하십시오. 도움말이 현재 창에 열립니다.

HTML 도움말 파일 만들기

아무 텍스트 편집기나 웹 퍼블리시 소프트웨어를 사용해 HTML 도움말 파일을 만들 수 있습니다. MATLAB에서 도움말 파일을 만들려면 다음 두 가지 방법 중 하나를 사용하십시오.

툴박스의 HTML 도움말 파일과 추가적인 사용자 지정 문서 파일(예: PNG 및 CSS 파일)을 모두 한 폴더(예: 툴박스 폴더의 html 하위 폴더)에 저장하십시오. 이 폴더는 다음 위치에 있어야 합니다.

  • MATLAB 검색 경로 내

  • matlabroot 폴더 외부

  • 설치된 하드웨어 지원 패키지 도움말 폴더 외부

문서 세트에는 다음과 같은 항목이 포함되는 경우가 많습니다.

  • 로드맵 페이지(즉, 문서에 대한 초기 시작 페이지)

  • 툴박스를 사용하는 방법을 설명하는 예제와 항목

  • 함수 또는 블록 도움말 페이지

info.xml 파일 만들기

info.xml 파일은 문서에 대해 표시할 이름을 비롯하여 사용자 지정 문서를 설명합니다. 또한, HTML 도움말 파일과 helptoc.xml 파일이 있는 위치도 식별합니다. 문서 작업하는 각 툴박스에 대해 info.xml이라는 파일을 만드십시오.

다음 템플릿을 수정하여 툴박스를 설명하는 info.xml을 만들 수 있습니다.

<productinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:noNamespaceSchemaLocation="optional">
    <?xml-stylesheet type="text/xsl"href="optional"?>
     
    <matlabrelease>R2016b</matlabrelease>
    <name>MyToolbox</name>
    <type>toolbox</type>
    <icon></icon>
    <help_location>html</help_location>
  
</productinfo>
또한 MATLAB 문서에 포함된 템플릿 info_template.xml을 사용하여 info.xml을 만들 수도 있습니다. 현재 폴더에 템플릿 파일의 복사본을 만들고 편집하려면 명령 창에서 다음 코드를 실행하십시오.
copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',...
'examples','templates','info_template.xml'),pwd)
fileattrib('info_template.xml','+w')
edit('info_template.xml')

다음 표에서는 info.xml 파일의 필수 요소를 설명합니다.

XML 태그설명템플릿의 값참고
<matlabrelease>MATLAB의 릴리스R2016b도움말 파일을 언제 추가했는지 나타냅니다. 브라우저에는 표시되지 않습니다.
<name>툴박스 제목MyToolbox브라우저 목차 창에 사용자 지정 문서에 대해 표시할 이름입니다.
<type>툴박스 레이블toolbox허용되는 값: matlab, toolbox, simulink, blockset, links_targets, other.
<icon>시작 버튼 아이콘(사용되지 않음)없음더 이상 사용되지 않지만, MATLAB이 info.xml 파일을 구문 분석하는 데 <icon> 요소가 필요합니다.
<help_location>도움말 파일의 위치html툴박스의 helptoc.xml, HTML 도움말 파일 및 다른 사용자 지정 문서 파일(예: PNG 및 CSS 파일)이 있는 하위 폴더의 이름입니다. 도움말 위치가 info.xml 파일 위치의 하위 폴더가 아닌 경우, info.xml 파일에 대한 상대적 help_location 경로를 지정하십시오. 여러 툴박스에 대한 HTML 도움말 파일을 제공하는 경우 각 info.xml 파일의 help_location은 서로 다른 폴더여야 합니다.
<help_contents_icon>목차 창에 표시할 아이콘없음MATLAB R2015a 이상에서는 무시됩니다. info.xml 파일에 나타나도 오류를 발생시키지는 않지만, 필요하지는 않습니다.

info.xml 파일에 저작권 정보나 연락처 정보와 같은 주석을 포함할 수도 있습니다. <!---->로 라인의 텍스트를 감싸서 주석을 만드십시오.

info.xml 파일을 만들 때는 다음 사항을 확인해야 합니다.

  • 필요한 모든 요소가 포함되어 있습니다.

  • 포함된 항목이 위 표와 같은 순서로 입력되어 있습니다.

  • XML의 파일과 폴더 이름이 실제 파일 및 폴더 이름과 정확히 일치하며 대/소문자 표기가 동일합니다.

  • info.xml 파일이 MATLAB 검색 경로의 폴더에 있습니다.

    참고

    info.xml이 포함된 폴더를 경로에 추가하면 MATLAB이 info.xml 파일을 구문 분석하고 문서를 표시합니다. 경로에 이미 존재하는 폴더에 info.xml 파일을 만든 경우 해당 폴더를 경로에서 제거하십시오. 그런 다음, MATLAB이 파일을 구문 분석하도록 폴더를 다시 추가합니다. 추가하는 폴더가 현재 폴더에 없도록 합니다.

helptoc.xml 파일 만들기

helptoc.xml 파일은 추가 소프트웨어 브라우저의 목차 창에 표시된 도움말 파일의 계층 구조를 정의합니다.

MATLAB 문서에 포함된 템플릿을 사용하여 helptoc.xml 파일을 만들 수 있습니다. 현재 폴더에 템플릿 파일 helptoc_template.xml의 복사본을 만들고 편집하려면 명령 창에서 다음 코드를 실행하십시오.

copyfile(fullfile(matlabroot,'help','techdoc','matlab_env',...
'examples','templates','helptoc_template.xml'),pwd)
fileattrib('helptoc_template.xml','+w')
edit('helptoc_template.xml')

helptoc.xml 파일을 HTML 문서 파일이 있는 폴더에 넣으십시오. 이 폴더는 info.xml 파일에서 <help_location>으로 참조되어야 합니다.

helptoc.xml 파일의 각 <tocitem> 항목은 HTML 도움말 파일 중 하나를 참조합니다. helptoc.xml 파일의 첫 번째 <tocitem> 항목은 문서의 초기 시작 페이지 역할을 합니다.

최상위 <toc> 요소 내에서 중첩 <tocitem> 요소는 목차의 구조를 정의합니다. 각 <tocitem> 요소에는 파일 이름을 제공하는 target 특성(Attribute)이 있습니다. 파일 이름과 경로 이름은 대/소문자를 구분합니다.

helptoc.xml 파일을 만들 때는 다음 사항을 확인해야 합니다.

  • helptoc.xml 파일의 위치는 info.xml 파일에서 <help_location>으로 표시됩니다.

  • 모든 파일 이름과 경로 이름은 대/소문자까지 정확히 일치합니다.

  • 모든 경로 이름에는 URL 파일 경로 구분 기호(/)가 사용됩니다. Windows 스타일 파일 경로 구분 기호(\)를 사용하면 목차가 잘못 표시될 수 있습니다. 예를 들어, 주 문서 폴더 내의 하위 폴더 refpages에 HTML 도움말 페이지 firstfx.html이 있는 경우 이 페이지의 <tocitem> target 특성(Attribute) 값은 refpages/firstfx.html이 됩니다.

예제 helptoc.xml 파일

다음 HTML 파일을 만들었다고 가정하겠습니다.

  • 툴박스의 로드맵 또는 시작 페이지 mytoolbox.html.

  • 함수를 나열하는 페이지 funclist.html.

  • 세 개의 함수 도움말 페이지: firstfx.html, secondfx.html, thirdfx.html.

  • 예제 myexample.html.

다음과 같이, helptoc.xml 파일에 파일 이름과 설명을 포함합니다.

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

    <tocitem target="mytoolbox.html">My Toolbox
        <tocitem target="funclist.html">Functions 
            <tocitem target="firstfx.html">first</tocitem>
            <tocitem target="secondfx.html">second</tocitem>
            <tocitem target="thirdfx.html">third</tocitem>
        </tocitem>
        <tocitem target="myexample.html">My Example
        </tocitem>
    </tocitem>

</toc>

helptoc.xml 파일은 올바로 작성된 info.xml 파일과 함께 도움말 브라우저에 다음과 같은 화면을 표시합니다.

검색 데이터베이스 구축하기

문서를 검색할 수 있게 하려면 builddocsearchdb 함수를 사용하여 검색 데이터베이스를 만드는데, 이를 검색 색인이라고도 부릅니다. 이 함수를 사용할 때는 HTML 파일이 포함된 폴더의 전체 경로를 지정하십시오.

예를 들어, HTML 파일이 C:\MATLAB\MyToolbox\html에 있다고 가정하겠습니다. 다음 명령은 이들 파일에 대한 검색 가능한 데이터베이스를 작성합니다.

builddocsearchdb('C:\MATLAB\MyToolbox\html')

builddocsearchdbC:\MATLAB\MyToolbox\html의 하위 폴더 helpsearch-v4를 만드는데 이 폴더에는 데이터베이스 파일이 포함됩니다.

툴박스에서 용어를 검색하려면 도움말 브라우저를 열고 도움말 검색 필드에서 검색하려는 용어를 입력하십시오. 그런 다음, 페이지 왼쪽의 출처별 상세 검색 아래에서 추가 소프트웨어를 선택하여 툴박스에 대한 결과를 확인합니다.

MATLAB R2014b부터는 검색 인덱스를 나란히 유지할 수 있습니다. 사용자 지정 툴박스의 문서를 특정 릴리스에서 검색 가능하도록 하려면 해당 릴리스의 MATLAB을 사용하여 도움말 파일에 대해 builddocsearchdb를 실행하십시오. R2021b 또는 그 이전 릴리스를 사용하여 builddocsearchdb를 실행할 경우 builddocsearchdb는 하위 폴더 helpsearch-v3를 만들어서 해당 검색 데이터베이스 파일을 포함시킵니다. helpsearch-v4 하위 폴더와 helpsearch-v3 하위 폴더를 나란히 유지하십시오. 이렇게 하면, 어떤 MATLAB 릴리스를 실행하든 도움말 브라우저가 자동으로 적합한 데이터베이스를 사용하여 문서를 검색합니다.

info.xml 파일에 대한 유효성 검사 오류 처리하기

XML 유효성 검사 오류란?

MATLAB은 검색 경로나 현재 폴더에서 info.xml 파일을 찾으면 자동으로 지원 체계에 대한 파일 유효성 검사를 수행합니다. info.xml 파일에 유효하지 않은 구문이 있는 경우, MATLAB은 명령 창에 오류를 표시합니다. 일반적으로 오류의 형식은 다음과 같습니다.

Warning: File <yourxmlfile.xml> did not validate.
...

MATLAB을 시작하거나 검색 경로에 폴더를 추가하면 info.xml 유효성 검사 오류가 발생할 수 있습니다.

XML 파일 유효성 검사 오류의 주요 원인은 다음과 같습니다.

  • info.xml 파일에서 엔터티가 누락되었거나 순서가 잘못되었습니다.

  • 관련 없는 info.xml 파일이 존재합니다.

  • info.xml 파일에 구문 오류가 있습니다.

  • MATLAB이 구버전 MathWorks 제품에 대한 info.xml 파일에 액세스하려고 합니다.

info.xml 내의 누락되었거나 순서가 잘못된 엔터티

필요한 XML 요소를 미리 정해진 순서로 나열하지 않는 경우 XML 유효성 검사 오류가 발생합니다.

Often, errors result from incorrect ordering of XML tags. Correct the error by updating
the info.xml file contents to follow the guidelines in the MATLAB help documentation.
info.xml 파일에 필요한 요소에 대한 설명과 이 요소의 지켜야 할 순서를 확인하려면 info.xml 파일 만들기 항목을 참조하십시오.

관련 없는 info.xml 파일

사용자 지정 문서와 관련이 없는 info.xml이라는 파일이 있다고 가정하겠습니다. 이 info.xml 파일은 관련 없는 파일이기 때문에 이 파일이 오류를 발생시킨 경우, 무시해도 해가 없습니다. 오류 메시지가 다시 발생하지 않도록 하려면 관련 없는 info.xml 파일의 이름을 바꾸십시오. 또는, 이러한 파일이 검색 경로나 현재 폴더에 없도록 하십시오.

info.xml 파일에 구문 오류가 있음

오류 메시지를 사용하여 문제를 분리하거나 XML 체계 유효성 검사기를 사용하십시오. info.xml 파일의 구조에 대한 자세한 내용은 matlabroot/sys/namespace/info/v1/info.xsd에서 해당 체계를 참조하십시오.

구버전 MathWorks 제품에 대한 info.xml 파일

다른 버전의 MATLAB에서 만든 info.xml 파일이 있는 경우, 현재 버전에서 유효하지 않은 구문이 파일에 포함되었을 수 있습니다. 다른 버전에서 만든 info.xml 파일을 식별하려면 오류 메시지에 보고된 전체 경로 이름을 확인하십시오. 경로에는 일반적으로 버전 번호(예: ...\MATLAB\R14\...)가 포함됩니다. 이 상황에서, 오류는 실제로 문제를 야기하지 않으므로 이 오류 메시지를 무시해도 됩니다. 이런 오류가 다시 발생하지 않도록 하려면 오류가 발생된 info.xml 파일을 제거하십시오. 또는, 검색 경로와 현재 폴더에서 구버전 info.xml 파일을 제거하십시오.

참고 항목

관련 항목