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을 제자리에서 편집 — 재포맷하거나 pretty-print하지 마세요
(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:id, w:author, w:date 속성을 가진 <w:ins>/<w:del>로 감싸세요. <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>을 추가하는 것입니다. <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는 자동 할당됩니다. 그런 다음 <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> 스니펫을 출력하므로 이를 word/document.xml에 추가하여 주석이 특정 텍스트에 고정되도록 해야 합니다 — 해당 마커를 배치할 때까지 주석은 존재하지만 보이지 않습니다.
종속성
docx (npm, 사전 설치됨 — require('docx')가 실패하는 경우에만 설치) · pandoc · LibreOffice (soffice) · pdftoppm (Poppler)