improvement.md

변환 품질 개선

품질이란

의미적으로 올바르고 깔끔한 HTML이 만들어져야 한다.

• PDF의 원래 레이아웃이 2단이었어도 HTML은 1단 레이아웃으로 변환되어야 한다(PDF reflow).
• 의미적으로 올바른 HTML이 만들어질 것. 논문의 제목은 h1, 중간 제목은 위계에 따라 h2-h6, 목록은 ul/li, 단락은 p, 코드 블럭은 pre/code, 표는 table 태그를 사용한다.
• 본문의 굵은 글씨체는 strong, 기울임 글씨체는 em, 취소선은 s, 밑줄은 u를 쓴다.
• 내부 링크나 참조는 a 태그를 사용한다.
• 각 페이지의 각주는 문서 제일 마지막으로 옮긴다.

품질 목표

세계 최고 수준의 pdf2html 변환기를 만드는 게 목표입니다. 적당히 하지 마세요.

• PDF 파일의 형식을 깊게 이해하고 활용할 수 있는 모든 정보를 활용하세요.
• PDF 파일의 텍스트 bbox 좌표, 글꼴, 글자 크기 등 PDF 파일에 담긴 모든 정보를 활용하여 문서의 전체적인 레이아웃, 텍스트의 위치 등을 파악하고 게슈탈트 원리, 편집 디자인 등 모든 지식을 활용하여 올바른 변환에 활용하세요.
• Machine Vision, 디자인, 통계학, 전산학, 수학 등 다양한 분야의 아이디어를 참신하게 조합하여 시도하세요. 세계 최고 수준의 변환기를 만들려면 기존의 뻔한 알고리즘이나 휴리스틱만으로는 한계가 있습니다.
• 알고리즘과 휴리스틱과 AI를 아주 영리하게 조합하여 성능이 빠르면서도 품질이 최고로 좋은 변환기를 만들어야 합니다.
• 기존 코드의 방향성에 한계가 있다고 판단하면 과감하게 수정하세요.

우선순위

• 강제 줄바꿈으로 끊어진 paragraph 이어주기
• 잘못 이어진 paragraph 나눠주기
• 텍스트 bbox 정보에 기반한 1단, 2단 레이아웃 검출
• 텍스트 bbox 정보에 기반한 paragraph 검출
• 이미지 추출
• 내부 링크 처리

힌트

• 문서 내의 구체적인 문자열을 탐지하는 식의 접근을 피하세요. 정말 어쩔 수 없는 상황인 경우에 한하여, 매우 일반화 가능성이 높은 텍스트 패턴을 탐지하는 건 괜찮습니다.
• 텍스트와 다른 텍스트가 놓인 상대적 위치, 전체적인 레이아웃 안에서의 위치와 크기, 폰트의 크기 등을 종합적으로 고려하여 텍스트의 역할과 의미를 파악하세요. 마치 사람이 눈으로 하는 것처럼.
• 기존 코드의 방향성에 의지하지 말고 가장 좋은 방법을 찾으세요.

품질 개선 절차

변환 품질을 개선하려면 반드시 다음 절차를 따라 진행하며, 한 번에 한 종류의 문제를 개선하는 일에 집중한다. 아래 절차를 따르면 한 문서의 한 종류의 문제에만 집중했음에도 불구하고 여러 문서가 동시에 좋아질 수 있다.

1. 각 문서의 페이지 PNG 이미지는 data/work/png/{문서명}/에 있다. (예: data/work/png/attention/) 원본 PDF와 대조할 때 참고할 것.
2. data의 각 문서를 html로 파일로 변환한다.
   • 명령: node src/cli.ts pdf2html <pdfPath> <baselineHtmlPath>
   • 출력 위치: data/work/before/{문서명}.html (예: data/work/before/attention.html)
3. 변환된 HTML 파일 중 하나의 문서를 집중하여 살펴보며 잘못 변환된 것으로 추정되는 문제의 유형을 찾는다. 제목이 아닌데 h1-h6 태그가 쓰였거나, 목록인데 li가 쓰이지 않았거나, 하나의 단락인데 여러 p 태그가 쓰였거나, 여러 단란인데 하나의 p 태그가 쓰였거나, 텍스트 추출이 잘못된 듯 텍스트의 내용이 이상하게 적혀 있거나(예를 들어 2단 레이아웃을 인식하지 못해서 텍스트가 섞이는 경우), 내부 링크가 걸려야 하는데 걸리지 않았거나 하는 등의 문제를 찾는다.
4. 해당 문제로 인해서 깨지는 단위 테스트를 추가하고 테스트를 실행하여 실제로 테스트가 깨지는지 확인한다. 테스트 파일은 소스코드와 co-locate한다. (예: src/foo.ts의 테스트는 src/foo.test.ts)
5. 코드를 수정하여 해당 문제를 해결한다. 이 때, 특정 문서의 특정 현상만을 해결하는 꼼수를 쓰지 않고 일반화된 알고리즘 또는 휴리스틱을 만든다. 새 알고리즘으로 인해 기존 알고리즘을 제거하거나 간소화할 수 있으면 가장 좋다. 알고리즘이나 휴리스틱으로 처리할 수 없는 경우에 한하여 OpenAI API를 사용하여 문제를 해결한다. .env에 OPENAI_API_KEY가 있으니 이걸 활용하여 API를 호출하는 코드를 만들 것. gpt-5-mini-2025-08-07 모델을 사용할 것.
6. 모든 테스트를 실행하여 전체 테스트가 통과하는 걸 확인한다. 새 알고리즘에 의해 기존의 다른 테스트들이 깨지면 각각의 내용을 면밀하게 살펴보고 regression이 발생한 경우 코드를 수정한다. 반면, HTML이 더 바람직한 방향으로 변했기 때문에 테스트가 깨진 것이면 코드가 아니라 테스트를 수정한다. 기존 테스트가 많이 깨진다고 해서 반드시 regression이라고 단정하지 말고 내용을 잘 살펴볼 것.
7. data의 각 문서를 html로 변환한다.
   • 명령: node src/cli.ts pdf2html <pdfPath> <afterHtmlPath>
   • 출력 위치: data/work/after/{문서명}.html (예: data/work/after/attention.html)
8. 2단계에서 변환한 html과 7단계에서 변환한 diff를 하여 테스트에 잡히지 않은 regression이 없는지 확인한다. regression이 있다면 5단계로 돌아간다.
9. 7단계에서 만들어진 모든 HTML을 data/{문서명}.html 파일로 저장한다. (예: data/attention.html)
10. 커밋한다.

특정 문서의 특정 문제만 개선을 하려고 하더라도 위 절차를 따라서 나머지 문서들에도 regression이 없는지 반드시 확인해야 한다. 모든 변화가 regression은 아니다. 충분히 일반화된 알고리즘 또는 휴리스틱을 썼다면 다른 문서들도 덩달아 개선될 것이다. diff 결과를 면밀하게 살피며 regression인지 아닌지 잘 판단할 것.

테스트 케이스 작성 요령

• 테스트 케이스는 data 디렉토리에 있는 실제 문서를 기반으로 작성하세요.
• 데이터 로딩 및 변환은 beforeAll()에서 한 번에 하세요.

CLI 명령

이 저장소에서 변환에 사용하는 CLI 서브 명령은 아래 2개다.

• node src/cli.ts pdf2png <pdfPath> <outputDir>
• node src/cli.ts pdf2html <pdfPath> <outputHtmlPath>

예시:

• node src/cli.ts pdf2png data/sample.pdf data/work/png/sample
• node src/cli.ts pdf2html data/sample.pdf data/work/before/sample.html
• node src/cli.ts pdf2html data/sample.pdf data/work/after/sample.html