Docs 파이프라인용 Ami Pro .SAM을 Markdown으로 변환

TL;DR

내용이 저장소, 정적 사이트 생성기, 또는 텍스트 파이프라인으로 향할 경우 Markdown를 선택하세요. Markdown는 작고, 변경 사항 추적 친화적이며, 휴대 가능합니다: 제목, 목록, 표, 링크는 유지되며, 추출된 다이어그램은 연결된 이미지 파일이 되고, 수식은 LaTeX 형식으로 포함될 수 있습니다. Git과 결합하면, 변환된 Ami Pro 아카이브는 신뢰에 의존하지 않고 코드 리뷰를 통해 검토할 수 있습니다. Ami Pro Converter로 변환하세요.

레거시 문서에 Markdown를 사용하는 이유

Docs-as-code는 '문서를 가진다'는 의미를 바꿨습니다. 저장소의 콘텐츠는 버전 기록, 코드 리뷰, 자동 링크 확인, 빌드 파이프라인을 얻습니다. 독점 바이너리 형식의 콘텐츠는 이런 것들을 하나도 얻지 못하고, .sam 파일은 그보다 더 못 얻습니다. 체인 내 어떤 도구도 그것을 읽을 수 없기 때문입니다.

Markdown로 변환하면 수십 년간의 자료가 다른 모든 것과 동일한 워크플로로 이동합니다. 1995년 설치 절차도 2002년 개정본과 비교(diff)할 수 있는 파일이 되고, 풀 리퀘스트에서 주석을 달 수 있으며, 이번 분기 릴리스 노트와 동일한 정적 사이트 생성기를 통해 게시할 수 있습니다.

Markdown는 또한 사용 가능한 가장 내구성이 뛰어난 실질적인 선택입니다. 이는 가벼운 관습 계층이 있는 일반 텍스트로, 어떤 소프트웨어 없이도 읽을 수 있고, 여러 구현체에서 구문 분석할 수 있으며, 필요에 따라 HTML, PDF, DOCX 또는 다른 어떤 것으로도 변환할 수 있습니다. 전체 문제가 공급업체가 사라진 이후에도 남아 있는 공급업체 형식에서 시작되었다는 점을 고려하면, 이러한 이식성이 핵심입니다.

무엇이 깔끔하게 매핑되고, 무엇이 그렇지 않은가

Markdown는 의도적으로 최소화되어 있으며, 이것이 장점이자 한계입니다. 구조는 잘 번역되지만, 프레젠테이션은 그렇지 않으며, 보통 괜찮습니다. 왜냐하면 어쨌든 프레젠테이션은 교체하고 싶은 층이기 때문입니다.

제목 — .STY 시트의 Ami Pro 스타일은 Markdown 제목 수준이 되어 실제 문서 구조를 제공합니다
목록 — 글머리 기호 및 번호 매기기 목록은 중첩을 포함하여 표준 Markdown 목록으로 변환됩니다
강조 — 굵게 및 기울임은 직접 매핑됩니다; 밑줄에는 Markdown에 해당하는 항목이 없으며 일반적으로 강조로 변환됩니다
표 — 단순 표는 파이프 표로 변환되지만, 복잡하게 병합된 셀 레이아웃은 표현할 수 없으며 HTML 대체나 설명이 필요합니다
이미지 — 추출된 WMF/EMF 다이어그램은 파일로 작성되며 표준 이미지 구문으로 참조됩니다
방정식 — 수학 렌더링이 가능한 경우 LaTeX로 제공되며, 그렇지 않은 경우 링크된 이미지로 제공됩니다

스타일 시트는 제목을 가능하게 만드는 것입니다

이것은 Markdown 변환이 유용한지 쓸모없는지를 결정하는 세부사항입니다. Markdown에는 "16포인트 볼드 헬베티카"라는 개념이 없습니다 — 그것은 제목 수준을 가지고 있습니다. 변환기가 한 줄이 강조된 단락이 아니라 레벨 2 제목임을 알 수 있는 유일한 방법은 단락 스타일을 .STY 스타일 시트와 비교하여 해석하는 것입니다.

스타일 시트가 있으면, 변환된 문서는 목차를 만들고 구간을 나눌 수 있는 제목 계층 구조와 함께 제공됩니다. 스타일 시트가 없으면, 단락이 일렬로 이어지고 가끔 굵은 글씨가 있는 평면적인 문서만 얻을 수 있으며, 위에 언급된 모든 장점은 사라집니다.

따라서 아카이브를 문서 파이프라인용으로 변환하기 전에 .STY 파일이 이전 서버에서 제대로 전달되었는지 확인하세요. 시간이 1분 정도 걸리지만 전체 프로젝트의 결과를 결정합니다.

저장소에서 이미지 다루기

1. 자산이 위치할 곳을 결정하다

대부분의 정적 사이트 생성기는 이미지를 전용 디렉토리에 두거나 페이지와 함께 배치되기를 기대합니다. 변환하기 전에 이러한 규칙을 선택하면 한 번만 파일을 이동하게 되며, 나중에 수천 개의 Markdown 파일에서 참조를 바꾸는 일을 하지 않아도 됩니다.

2. 저장소 크기 보기

추출된 다이어그램이 합산됩니다. 도표가 포함된 수천 개의 문서는 이전에 텍스트만 있던 저장소에 수백 메가바이트를 추가할 수 있습니다. Git LFS를 고려하거나, 자산을 객체 저장소에 보관하고 URL로 참조하십시오.

3. 파일 이름 정규화

레거시 아카이브에는 DOS 시대의 이름, 공백, 혼합 대소문자가 가득합니다. 이동 중에는 이름을 소문자 하이픈 형태로 정규화하고, 게시된 페이지를 원래 .sam 파일로 추적할 수 있도록 매핑 테이블을 유지하세요.

4. 처음에 방정식 전략을 선택하세요

사이트가 수학식을 렌더링한다면, 추출한 LaTeX를 사용하여 선명하고 선택 가능하며 검색 가능한 수식을 얻으세요. 렌더링하지 않는다면, 이미지로 렌더링된 수식을 사용하고 수학식이 검색되지 않는다는 것을 받아들이세요. 하나의 아카이브에서 둘을 혼합하는 것은 피해야 할 옵션입니다.

수천 개의 변환된 파일 검토

아무도 3,000개의 Markdown 파일을 읽지 않지만, Git은 DOCX 파일 폴더가 할 수 없는 방식으로 선택적 검토를 가능하게 합니다. 변환 결과를 하나의 큰 커밋으로 브랜치에 올린 다음, 파일별이 아닌 패턴별로 검토하세요.

여기서 주요 도구는 Grep입니다. 의심스럽게 짧은 파일, 전혀 제목이 없는 파일, 해결되지 않은 이미지 참조, 파싱 오류를 나타내는 괴상한 대괄호 표기, 인코딩 문제를 나타내는 대체 문자를 검색하세요. 이러한 각 검색은 몇 초 만에 실패 유형을 드러냅니다.

그런 김에 파이프라인에 자동화를 추가하세요: 깨진 내부 참조를 잡기 위한 링크 검사기, 생성기가 필요로 한다면 앞부분 메타데이터 검증기, 누락된 이미지가 있을 때 실패하는 빌드 단계. 이들이 통과하면, 아카이브는 유지 관리되는 문서와 동일한 품질 수준에 있게 됩니다.

Markdown가 잘못된 대상일 때

Markdown은 고의적으로 복잡한 페이지 레이아웃을 표현할 수 없으며, 일부 Ami Pro 문서는 작성된 것이 아니라 디자인된 것이었습니다 — 뉴스레터, 형식화된 양식, 프레임 기반 구성의 보고서 표지 등. 이러한 것들을 Markdown로 억지로 변환하면 기술적으로는 유효하지만 실질적으로는 쓸모없는 결과물이 됩니다.

법적 의미가 있고 정확한 표현에 의존하는 문서에도 동일하게 적용됩니다: 체결된 계약서, 서명된 양식, 공식 공지문. 이러한 경우, PDF는 정직한 출력물이며, 만약 Markdown과 함께 검색 가능하게 하려면, 두 가지 모두로 변환하고 짧은 Markdown 스텁에서 PDF로 연결하면 됩니다.

선택적으로 하는 것은 타협이 아니다. 깔끔하고 구조화된 Markdown으로 가득한 문서 저장소와 레이아웃 고정이 필요한 문서를 위한 연결된 PDF 세트는 품질이 떨어진 변환물의 일률적인 더미보다 더 나은 결과다.

Markdown이 오래된 아카이브에 주는 것

한 번도 없었던 버전 기록, 코드 리뷰, 비교 기능을 문서에
현재 문서와 같은 정적 사이트 생성기로 게시 가능
어떤 단일 도구보다도 오래가는 작고 이식성 높은 일반 텍스트 파일
목차와 AI 청킹에 적합한 제목 구조
이미지가 되지 않고 검색 가능한 상태로 남는 LaTeX 수식

레거시 문서는 현대적인 도구가 필요하다

저장소에서 .sam 파일과 Markdown 파일 사이의 차이는 단순한 형식 변경이 아닙니다. 이는 누구도 검토할 수 없는 콘텐츠와, 팀이 작성하는 다른 모든 것처럼 검토, 검색 및 자동 게시에 참여하는 콘텐츠 사이의 차이입니다.

스타일 시트를 확인하고, 시작하기 전에 자산과 방정식 규칙을 결정하며, 아카이브를 한 번에 변환하고, 읽지 말고 grep으로 검토합니다. 그런 다음 나머지 문서와 동일한 파이프라인을 통해 전송합니다.