부록 부록

A.5 참고자료·출처

A.5.1 이 책의 출처에 관한 정직한 진술

먼저 이 책이 어떻게 쓰였는지 밝힌다.

이 책은 집필 환경에 ROS 2가 설치되지 않은 상태에서, 실행 검증 없이 작성되었다(목차 3·BK-03). 내용은 ROS 2 문서·소스·커뮤니티 관행에 대한 지식에 기반하지만, 개별 문장을 특정 출처와 대조해 확인하지 않았다.

2026-08-14부터 여러 차례에 걸쳐 일부를 실제 Jazzy 컨테이너에서 확인했다(범위는 목차 3의 표). 초기 두 차례는 코어 API·CLI를, 이후 회차는 생태계 스택 네 개(ros2_control·Nav2·MoveIt 2·ros_gz)를 대상으로 했다.

1차에서 오류 두 건을 찾아 고쳤다 — 존재하지 않는 명령(ros2 bag echo), "SEDP가 QoS 전체를 교환한다"는 부정확한 서술.

2차에서 다섯 건을 더 찾아 고쳤다 — 존재하지 않는 환경변수 셋(RCUTILS_LOGGING_SEVERITY·FASTDDS_LOG_LEVEL·FASTDDS_DEFAULT_PROFILES_FILE), Jazzy에서 이미 낡은 ros2 topic echo 서술(기본 QoS가 best_available이라 자동 협상한다 — 오히려 --qos-reliability reliable을 붙이면 끊긴다), 그리고 QoS 정책값 BEST_AVAILABLE이 전권에서 완전히 빠져 있던 것.

3차(2026-08-16)는 성격이 달랐다 — 틀린 서술이 아니라 빠진 주제를 찾았다. 갭 점검으로 다섯 가지 누락을 확인해 채웠고(rclcpp::TypeAdapter, ~/get_type_description 서비스, 내용 필터, matched·incompatible_type 이벤트, 내장 토픽 통계), 전부 컨테이너에서 컴파일·실행한 뒤 집필했다. 같은 작업에서 참조 오지정 75건도 고쳤다 — 파라미터를 1.7(서비스)로, 액션을 1.9(파라미터)으로, 디스커버리를 1.5(QoS)로 가리키던 혼동이 여러 장에 퍼져 있었다.

이 패턴이 시사하는 바가 중요하다. 앞의 두 번은 "공식 문서 기준으로는 맞았던" 서술이 배포판을 거치며 어긋난 경우였다. 즉 이 책의 오류는 무작위가 아니라 버전 이동 지점에 몰려 있다 — 환경변수 이름, CLI 기본값, 새로 추가된 정책값. 검증하지 않은 나머지에도 같은 밀도의 오류가 있다고 보는 편이 안전하며, 특히 자체 릴리스 주기를 갖는 생태계 패키지(Nav2·MoveIt 2·ros2_control·Gazebo) 장들은 실행 검증이 전혀 없다.

그리고 3차가 보탠 교훈은 다르다 — 없는 것은 정오표에 포함되지 않는다. 오류는 읽다가 걸리지만, 완전히 빠진 주제는 독자가 그 존재를 모르므로 영원히 안 보인다. 3차에서 채운 다섯 가지 중 셋은 이 책이 스스로 "저기서 다룬다"고 적어 놓고도 다루지 않은 것이었다. 따라서 "이 책에 없으니 없는 기능"이라고 추론하지 말 것 — 이 책의 커버리지는 완전하지 않으며, 앞으로도 같은 종류의 빈칸이 남아 있다고 보는 편이 안전하다.

그래서 이 부록은 인용 목록이 아니다. 특정 URL·문서 제목·논문을 나열하면 그것이 정확하다는 인상을 주는데, 확인하지 않은 것을 그렇게 제시하는 것은 정직하지 않다. 대신 "무엇을 어디서 확인해야 하는가" 를 정리한다.

정직: 이 책의 어떤 서술도 1차 출처를 대체하지 않는다. 특히 명령 옵션·API 시그니처·기본값·버전 지원 상태는 반드시 원문으로 확인해야 한다. 이 책의 가치는 "무엇을 확인해야 하는지"와 "왜 그런지"에 있다.

A.5.2 1차 출처의 종류

정확성이 필요할 때 가야 할 곳들이다.

견해: "소스가 최종 진실"이라는 원칙을 편하게 받아들이라(15.5.4의 반복). 문서가 불명확하거나 낡았을 때 소스를 여는 것이 추측보다 빠르다. 특히 기본값·동작 순서·예외 처리는 소스에서만 확실히 알 수 있는 경우가 많다.

견해: --help가 CLI의 정본이다(A.1.1). 이 책의 CLI 레퍼런스(A.1)를 포함해 어떤 문서보다 우선한다.

A.5.3 주제별로 어디를 볼 것인가

A.5.4 이 책이 인용하지 않은 것

의도적으로 하지 않은 것들이다.

견해: "확인하지 않은 것을 인용 형태로 제시하지 않는다"가 이 책의 원칙이다. 그럴듯한 출처 목록은 신뢰를 주지만, 그중 하나라도 틀리면 전체의 신뢰가 무너진다. 없는 것을 없다고 말하는 편이 낫다.

견해: 대신 이 책은 (확인 필요) 표기를 촘촘히 썼다. 어느 문장이 검증 대상인지 독자가 알 수 있게 하는 것이, 확인하지 않은 출처를 붙이는 것보다 실질적으로 유용하다고 판단했다.

A.5.5 이 책을 검증하며 읽는 법

독자가 이 책의 정확성을 확인하는 방법이다.

견해: "직접 해 보는 것"이 이 책을 읽는 가장 좋은 방법이다. 이 책은 실행 검증 없이 쓰였으므로, 독자가 실행해 보며 읽으면 이 책의 한계를 넘어선다. 차이를 발견하면 그것이 여러분의 환경에서의 진실이다.

A.5.6 이 책의 내부 참조 체계

이 책 안에서 무언가를 찾는 방법이다.

각 장의 공통 구조:

견해: 각 장의 "함정 카탈로그"만 읽어도 실무적 가치가 크다. 전체를 읽을 시간이 없다면, 관련 장의 함정 표를 보는 것이 빠른 경로다. 대부분 증상 → 원인 → 대처 → 관련 장으로 되어 있다.

견해: "체크포인트"는 자가 진단용이다. 답할 수 없는 질문이 있으면 그 절을 다시 보라. 학습 여부를 확인하는 용도로 설계했다.

A.5.7 이 책의 유효 기간

언제까지 유효한가.

특히 빨리 낡는 장:

정직: 이 책은 Jazzy(2024-05 릴리스)를 기준으로 쓰였다. 시간이 지날수록 명령·API·도구 서술의 정확도가 떨어지므로, 원리 부분은 계속 유용하되 세부는 확인하며 읽어야 한다. 15.5.4에서 "블로그·영상의 배포판을 확인하라"고 한 것이 이 책에도 적용된다.

A.5.8 오류를 발견했다면

이 책에 틀린 내용이 있을 수 있다.

견해: 차이를 발견하면 여러분의 환경이 옳다. 이 책은 검증되지 않았고 여러분은 실행해 보았다. 그 차이를 기록해 두는 것(11.1.8의 사후 분석과 같은 발상)이 팀의 지식이 된다.

견해: 이 책의 (확인 필요) 표기가 완전하지 않을 수 있다. 표기가 없는 곳에도 버전 의존적 내용이 있을 수 있으므로, "명령·API·기본값은 항상 확인" 을 습관으로 두는 것이 안전하다.

A.5.9 함께 읽으면 좋은 것

이 책이 다루지 않거나 얕게 다룬 영역이다.

정직: 자매서 robotics(RB)는 집필 중이다. 위 표의 RB 번호는 robotics/docs/book/RB-00-목차.md가 선언한 장 번호이며, 장 번호는 2026-11-03에 새로 고정했다(1408장). 이전 계획(137장)의 번호와 다르다. 2026-11 시점에 새 번호로 작성이 끝난 것은 RB-01뿐이다. 나머지는 예고된 자리이므로 아직 내용이 없을 수 있다 — 찾기 전에 목차에서 상태(✅·⬜)를 확인하라. 번호는 밀지 않는 규약(CLD-03)이라 나중에 채워져도 위치는 그대로다.

견해: 이 책은 "ROS 2로 로봇 시스템을 만들고 운영하는 것"에 초점을 맞췄다. 각 영역의 이론은 그 분야의 교재가 훨씬 낫고, 이 책은 그 이론을 ROS 2에서 어떻게 쓰는가를 다룬다. 두 가지가 함께 필요하다.

견해: 이론이 부족하면 튜닝이 시행착오가 된다. 제어 게인을 추측으로 조정하거나 필터 파라미터를 근거 없이 바꾸는 것은, 이론을 모르기 때문인 경우가 많다. 실무가 막히는 지점이 이론을 공부할 시점이라는 신호다.