추가 요청

같은 samples/ 문서들을 한글 2010 / 한글 2020 OCX 오토메이션으로도 PDF 저장하여 추가 부탁드립니다.

목적

• 한컴 버전 간 렌더링 차이(2010 → 2020 → 2022)를 비교 가능한 형태로 보존
• rhwp의 SVG 출력이 어느 버전과 가장 가까운지, 어느 버전 기준으로 정합성을 맞출지 판단할 근거 자료 확보

제안 파일명 규약

• 한글 2010: pdf-2010/{stem}-2010.pdf
• 한글 2020: pdf-2020/{stem}-2020.pdf
• (현재) 한글 2022: pdf/{stem}-2022.pdf

또는 동일 폴더에 접미어로만 구분하는 것도 가능합니다 (pdf/{stem}-2010.pdf, -2020.pdf, -2022.pdf). 폴더 구조는 메인테이너 판단에 따라 주시면 됩니다.

변환 스크립트

현재 PR에 포함된 pdf/_convert.ps1 을 버전별로 복제하여 OCX ProgID 만 교체하면 동일하게 일괄 변환 가능할 것으로 보입니다 (HWPFrame.HwpObject 버전 분기).

와우! 고생하셨습니다.

한글2022 PDF 자동 변환 방법 상세

본 PR의 PDF 결과물 생성에 사용한 자동화 절차를 기록합니다. 한글 2010/2020 추가 변환 작업도 동일한 패턴을 재사용할 수 있습니다.

1. 환경 구성

1.1 Python + pyhwpx 설치

한글 COM 자동화 시 매 파일마다 뜨는 "외부 프로그램에서 호출되었습니다" 보안 다이얼로그를 차단하려면, FilePathCheckerModule.dll 보안 모듈이 필요합니다. 이 DLL은 pyhwpx 패키지에 번들되어 있어 가장 손쉽게 확보 가능합니다.

```powershell
winget install --id Python.Python.3.12 -e --accept-package-agreements --accept-source-agreements --silent --scope user
& "$env:LOCALAPPDATA\Programs\Python\Python312\python.exe" -m pip install pyhwpx
```

설치 후 DLL 위치:
```
%LOCALAPPDATA%\Programs\Python\Python312\Lib\site-packages\pyhwpx\FilePathCheckerModule.dll
```

1.2 보안 모듈 레지스트리 등록

```powershell
$dll = 'C:\Users<USER>\AppData\Local\Programs\Python\Python312\Lib\site-packages\pyhwpx\FilePathCheckerModule.dll'
$key = 'HKCU:\Software\HNC\HwpAutomation\Modules'
if (-not (Test-Path $key)) { New-Item -Path $key -Force | Out-Null }
Set-ItemProperty -Path $key -Name 'FilePathCheckerModule' -Value $dll -Type String
```

이 등록 이후 COM 코드에서 `hwp.RegisterModule('FilePathCheckDLL', 'FilePathCheckerModule')` 호출이 True를 반환하면 다이얼로그가 더 이상 뜨지 않습니다 (False 반환 시 등록 실패).

2. PDF 변환 핵심 코드 (모아찍기 차단)

PDF 저장은 `IHwpObject.SaveAs(path, "PDF", "")` 직접 호출 대신, `FileSaveAs_S` 액션 + `Attributes = 0` 패턴을 사용합니다 (pyhwpx 1.7.2 `save_as` 메서드와 동일). 이 패턴이 한글의 PDF 저장 다이얼로그 기본값(1-up)을 강제하므로, 시스템 환경설정에 모아찍기가 설정되어 있어도 1페이지/장으로 출력됩니다.

```powershell
$hwp = New-Object -ComObject 'HWPFrame.HwpObject'
$null = $hwp.RegisterModule('FilePathCheckDLL', 'FilePathCheckerModule')

$null = $hwp.Open($srcPath, '', '')

$pset = $hwp.HParameterSet.HFileOpenSave
$null = $hwp.HAction.GetDefault('FileSaveAs_S', $pset.HSet)
$pset.filename = $outPath
$pset.Format = 'PDF'
$pset.Attributes = 0
$ok = $hwp.HAction.Execute('FileSaveAs_S', $pset.HSet)

fallback (FileSaveAs_S 실패 시)

if (-not $ok) { $ok = $hwp.SaveAs($outPath, 'PDF', '') }

$hwp.XHwpDocuments.Item(0).Close($false)
```

검증: 변환된 PDF의 MediaBox 크기가 원본 한글 페이지 설정과 일치하는지 `pypdf` 등으로 확인 (예: A4 595×841pt, A4 가로 841×595pt).

3. 크래시 복구 (자동) — pdf/_convert.ps1

특정 손상 파일 처리 시 한글 프로세스가 죽으며 이후 모든 COM 호출이 `RPC_S_SERVER_UNAVAILABLE (0x800706BA)` 또는 `RPC_S_CALL_FAILED (0x800706BE)` 로 실패합니다. 한 파일 실패가 배치 전체를 중단시키지 않도록:

1. 각 파일 try/catch에서 RPC 에러 패턴 감지
2. `Hwp.exe` 강제 종료 (`Stop-Process -Force`)
3. 새 `HWPFrame.HwpObject` COM 인스턴스 생성 + `RegisterModule` 재호출
4. 다음 파일부터 정상 진행

본 PR 변환에서 3건의 크래시가 모두 자동 복구되었습니다.

4. Hang 감지 watchdog — pdf/_watchdog.ps1

크래시가 아닌 무한 루프형 hang (한글 프로세스 CPU 사용 중이지만 COM 호출 무응답) 도 발생할 수 있습니다. 본 PR 변환에서 `basic\calendar_monthly.hwp` 파일이 약 8분간 hang 했습니다.

별도 PowerShell 프로세스가 `_convert.log` 의 mtime을 10초마다 감시하여 60초 이상 무변동 시 `Hwp.exe` 를 강제 종료합니다. 메인 스크립트는 RPC 에러로 받아 크래시 복구 경로를 타게 됩니다.

```powershell
while ($true) {
Start-Sleep -Seconds 10
$age = (Get-Date) - (Get-Item $log).LastWriteTime
if ($age.TotalSeconds -gt 60) {
Get-Process Hwp -ErrorAction SilentlyContinue | Stop-Process -Force
}
if ((Get-Content $log -Tail 2) -match 'DONE: ok=') { break }
}
```

5. 본 PR 변환 결과 요약

실패 8개 파일

공통적으로 `_saved`, `-no`, 저장본/스펙 파일이며, 이전에 비정상 저장됐거나 특수 컨트롤이 들어있는 케이스로 추정됩니다.

6. 한글 2010 / 2020 추가 변환 시 참고

• COM ProgID는 동일 (`HWPFrame.HwpObject`) — 한 시스템에 여러 한글이 설치되어 있어도 마지막에 등록된 버전 1개만 활성화됩니다. 따라서 한글 2010/2020/2022 변환은 각 버전을 단독 설치한 환경에서 순차로 진행하거나, 가상 머신/별도 사용자 계정으로 분리해야 합니다.
• `FilePathCheckerModule.dll` 등록은 한글 버전 무관하게 동일하게 작동합니다 (레지스트리 키 동일).
• `FileSaveAs_S` 액션의 `Attributes` 매개변수는 한글 버전 간 호환되지만, 일부 옵션(예: PDF/A 모드, 보안 설정 등)은 버전별 차이가 있을 수 있어 변환 후 첫 1~2개 파일을 시각 확인 권장.

7. 참고 파일

• `pdf/_convert.ps1` — 변환 본 스크립트 (크래시 복구 포함)
• `pdf/_watchdog.ps1` — hang 감지 watchdog
• `pdf/_convert.log` — 본 변환 실행 전체 로그 (재현/디버깅 참고용)

PR #670 처리 결과

cherry-pick 머지 완료 (69a7078 + 본 환경 정합 보강 commit 12aa99c).

본 환경 결정적 검증 (PDF binary 만 추가, src 영역 영향 0)

• cargo test --lib --release: 1155 passed (회귀 0)
• cargo clippy --lib -- -D warnings: 0
• cargo build --release: 통과

본 환경 정합 보강 영역 (후속 commit 12aa99c)

1. pdf/README.md 신규 작성

• 폴더 구조 (pdf/ 한글 2022 / pdf-2020/ 예정 / pdf-2010/ 예정)
• 명명 규약
• 권위 등급 영역 (컨트리뷰터 환경별)
• 변환 자동화 스크립트 영역 (PR 본문의 본 영역 가져옴)

2. CLAUDE.md 갱신

• PDF 권위 자료 명명 규약 표
• PDF 권위 등급 (컨트리뷰터 환경별):
  • Windows + 한컴 편집기: 한컴 2010/2020/2022 편집기 1차 + PDF 보조
  • macOS / Linux (한컴 편집기 미접근): 한글 2020/2022 PDF 1차 정답지 / 한글 2010 PDF 등급 미달
  • 한컴 뷰어 / 외부 변환 / macOS 인쇄: 모든 환경 정답지 아님

본 PR 의 본질 영역 인지

본 PR 의 199 PDF 영역의 가치 영역 = 외부 컨트리뷰터 다양성 인프라:

• macOS / Linux 컨트리뷰터 영역에서 한컴 편집기 영역 부재 → 본 PDF 가 시각 판정 영역의 정답지 역할
• 향후 컨트리뷰터 증가 시 한컴 프로그램 부재 환경에서도 기여 가능 영역 확보
• project_dtp_identity (rhwp 정체성) 영역 정합 강화

한글 2010 / 2020 추가 변환 제안 영역 응답

작업지시자 결정 영역:

• 폴더 구조: 컨트리뷰터의 현재 영역 유지 (pdf/{stem}-2022.pdf) + 향후 한글 2010 추가 시 pdf-2010/ + 한글 2020 추가 시 pdf-2020/ 별도 폴더
• 권위 등급: 한글 2020 / 2022 PDF 만 정답지 영역 (한글 2010 PDF 는 보조 자료, 정답지 등급 미달)
• 추가 변환 환영: 한글 2020 PDF 변환 영역 별도 PR 환영 (한글 2010 PDF 는 영역 외 — 정답지 등급 미달 영역 영구 보존 영역 부재)

변환 자동화 스크립트 영역의 가치

_convert.ps1 / _watchdog.ps1 영역 영구 보존 — 향후 한글 2020 PDF 추가 변환 시 재사용 영역. pyhwpx + FilePathCheckerModule.dll + FileSaveAs_S 패턴 + 크래시 자동 복구 + watchdog hang 감지 영역 모두 정합.

긴 시간 + 자동 복구 3 건 + watchdog 영역 등 변환 작업 영역의 노력 + 결과 자료 영역 + 자동화 스크립트 영역 모두 본 환경 정합 영역 강화 정합.