DOCX 생성, 편집 및 분석
.docx 파일은 XML 파일들의 ZIP 아카이브입니다. 작업에 따라 적절한 접근 방식을 선택하세요:
| 작업 | 접근 방식 |
|---|---|
| 새 문서 생성 | docx (npm) 스크립트 작성 — 아래 주의사항 참고 |
| 기존 문서 편집 | unzip → word/document.xml 편집 → zip (docx-js는 기존 파일을 열 수 없음) |
| 읽기 | pandoc -t markdown file.docx |
아래 스크립트 경로는 이 스킬의 디렉토리를 기준으로 합니다.
docx-js로 생성할 때의 주의사항
docx는 사전 설치되어 있습니다 — npm install을 먼저 실행하지 말고 스크립트를 작성한 후 직접 require('docx')를 사용하세요. 해당 require가 실패하는 경우에만 npm install docx를 실행합니다. 모델은 API를 알고 있습니다. 주의해야 할 함정들은 다음과 같습니다:
- 페이지 크기 기본값은 A4입니다. US Letter로 설정하려면
page: { size: { width: 12240, height: 15840 } }(DXA; 1440 = 1인치)를 사용하세요. - 가로 방향: 세로 방향 치수를 전달하고
orientation: PageOrientation.LANDSCAPE를 설정하세요 — docx-js가 내부적으로 너비와 높이를 바꿉니다. - 표는 이중 너비가 필요합니다: 표에
columnWidths를 설정하고 모든 셀에width를WidthType.DXA로 설정하세요 (PERCENTAGE는 Google Docs에서 깨집니다). 열 너비는 표 너비와 일치해야 합니다. - 표 음영:
ShadingType.CLEAR를 사용하고 절대SOLID를 사용하지 마세요 (검은색으로 렌더링됩니다). - 목록: 절대
•를 문자 그대로 삽입하지 마세요.LevelFormat.BULLET을 사용한numbering구성을 사용하세요. ImageRun에는type:이 필요합니다 ("png","jpg", …).PageBreak는Paragraph내부에 있어야 합니다.- 절대
\n을 사용하지 마세요 — 별도의Paragraph요소를 사용하세요. - 목차: 제목은 내장
HeadingLevel.*을 사용해야 합니다. 사용자 정의 제목 스타일에는outlineLevel이 설정되어야 하며, 그렇지 않으면 표시되지 않습니다. - 표를 가로줄로 사용하지 마세요 — 대신 단락 아래쪽 테두리를 사용하세요.
- 점선 지시선 / 같은 줄 오른쪽 정렬:
TextRun내부에PositionalTab(alignment: PositionalTabAlignment.RIGHT,leader: PositionalTabLeader.DOT)을 사용하고, 문자 그대로의.이나 공백 패딩을 사용하지 마세요.
출력 확인
.docx 파일을 작성한 후 렌더링하여 확인하세요:
python scripts/office/soffice.py --headless --convert-to pdf output.docx
pdftoppm -jpeg -r 100 output.pdf page
ls page-*.jpg # 이미지 읽기
pdftoppm은 페이지 번호를 페이지 수 폭으로 0으로 채웁니다 (page-01.jpg…page-12.jpg).
기존 문서 편집
레거시 .doc 파일은 먼저 변환해야 합니다: python scripts/office/soffice.py --headless --convert-to docx file.doc.
unzip -q doc.docx -d unpacked/
find unpacked -type l -delete # 심볼릭 링크 항목 제거 — 외부에서 온 docx는 신뢰할 수 없음
python scripts/merge_runs.py unpacked/ # 분할된 실행을 병합하여 텍스트를 찾을 수 있게 함
# unpacked/word/document.xml을 제자리에서 편집 — 재포맷하거나 이쁘게 출력하지 마세요
(cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .)
python scripts/office/validate.py out.docx --original doc.docx # XSD 검사; --auto-repair가 일반적인 문제를 수정
# 변경 내용 추적? --author "<변경 내용을 추적한 이름>"을 추가하여 모든 편집이 추적되었는지 확인
Word는 텍스트를 여러 <w:r> 실행으로 분할합니다 (수정 ID, 맞춤법 검사 표시). 따라서 문서에서 볼 수 있는 구문이 XML에서 연속된 문자열로 존재하지 않는 경우가 많습니다. merge_runs.py는 word/document.xml에서 인접하고 동일한 형식의 실행을 콘텐츠나 렌더링을 변경하지 않고 병합합니다. 또한 .docx 파일을 직접 받을 수도 있습니다 (python scripts/merge_runs.py doc.docx -o merged.docx).
변경 내용 추적: 문서를 수정할 때 --author "<변경 내용을 추적한 이름>" (와 함께 --original 필요)로 검증하세요 — 이 옵션은 주변에 <w:ins>/<w:del>이 없는 텍스트 변경 사항(실수로 쉽게 발생하며 수락된 보기에서 보이지 않음)을 보고합니다. 실행을 <w:ins>/<w:del>로 감싸고 w:id, w:author, w:date 속성을 포함하세요. <w:del> 내부에서는 텍스트 요소가 <w:t>가 아닌 <w:delText>입니다. 삭제된 단락 표시 (<w:pPr><w:rPr><w:del w:id=".." w:author=".." w:date=".."/></w:rPr></w:pPr>)는 "이 단락을 다음 단락과 병합"을 의미합니다. 따라서 단락을 완전히 삭제하는 것은 이것과 모든 실행 주위의 <w:del>을 추가하는 것입니다. <w:del/>은 rPr의 다른 자식보다 먼저 와야 합니다. 순서는 스키마에 의해 강제됩니다.
모든 변경 내용을 수락한 깨끗한 사본을 생성하려면: python scripts/accept_changes.py in.docx out.docx.
삭제된 단락 표시를 수락하면 해당 단락이 아래 단락과 병합되어야 하므로 모든 실행이 모두 삭제된 단락은 사라집니다. Word는 이렇게 합니다. accept_changes.py와 pandoc --track-changes=accept는 항상 그렇지 않습니다. 둘 다 같은 방식으로 실패합니다 — 삭제된 텍스트는 제거하지만 비워진 단락은 남겨두어 자동 번호 매기기가 적용된 경우 잘못된 빈 글머리 기호로 읽힙니다:
pandoc --track-changes=accept는 단락을 병합하지 않습니다.accept_changes.py(LibreOffice)는 삭제된 단락 뒤에 빈 공백 단락이 오는 경우를 제외하고 올바르게 병합합니다.
두 보기 중 하나의 빈 글머리 기호는 문서의 결함이 아니라 해당 보기의 아티팩트입니다. XML에서 단락 삭제를 확인하세요.
주석
주석은 6개의 상호 연결된 파일이 필요합니다. 헬퍼를 사용하세요 — 디렉터리 모드(document.xml도 편집할 때 권장, unzip/rezip 사이클 절약), 그 외에는 .docx 직접 모드:
# 이미 압축이 풀린 디렉터리에서 (마커 배치 시 선호)
python scripts/comment.py unpacked/ "수수료 및 비용 상한선이 너무 낮습니다"
python scripts/comment.py unpacked/ "동의" --parent 0
# .docx 파일을 직접 대상으로
python scripts/comment.py contract.docx "이 상한선이 너무 낮습니다" -o annotated.docx
스크립트는 comments.xml, commentsExtended.xml, commentsIds.xml, commentsExtensible.xml, 관계, 콘텐츠 유형 재정의를 작성합니다. 주석 ID는 자동 할당됩니다. 그런 다음 word/document.xml에 추가할 <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> 스니펫을 출력하여 주석이 특정 텍스트에 고정되도록 합니다 — 해당 마커를 배치할 때까지 주석은 존재하지만 표시되지 않습니다.
종속성
docx (npm, 사전 설치됨 — require('docx')가 실패하는 경우에만 설치) · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)