epub 作り方を横書き技術書に絞るなら、文章だけでなく、章の境界、画像参照、コードブロック、表を入力段階で分け、ウィザードでは横書き・章順・目次対象を決めます。この記事では全四章、図版三点、コード二点、表二点のAPI入門書を例に、EPUBへ渡す設定までを扱います。実機確認で確認済みなのは無画像標本の構造であり、画像・表紙入り標本は検査が未合格です。全端末検査やストア提出も完了したとはみなしません。
横書き技術書では四種類の部品を先に分ける
技術書の入力は、本文、図版、コード、表を別の役割として扱います。本文は章の説明を担い、図版は本文から参照され、コードは改行と空白を保ち、表は行と列の対応を伝えます。ワープロ上で見た目を合わせただけでは、リフロー時にどの部品か判別しにくくなります。
標本は「導入」「認証」「エラー処理」「付録」の四章です。導入章には図1、認証章には図2と図3、エラー処理章にはコードAとコードB、付録には表1と表2を置きます。各部品に一意な名前を付け、本文側の参照語と一致させます。
章の境界を見出しと改ページで固定する
四章の先頭には同じレベルの見出しを置き、章を分けたい位置へ改ページ記法を入れます。見出しレベルが途中で飛ぶと、本文の見た目が整っていても目次候補の階層が読み取りにくくなります。H1を書名、H2を章、H3を節というように、標本内の役割を固定します。
改ページは章の開始を作るために使い、ページ数を固定するためには使いません。リフローEPUBでは画面幅や文字サイズでページが変わるからです。四章が四つの章候補としてウィザードへ渡ることを確認し、紙面のページ番号は入力しません。
図版三点はファイル名と代替テキストを対応させる
図1は認証の流れ、図2はトークン構造、図3は失敗時の分岐とします。画像ファイル名を figure-01-auth-flow.png のように役割が分かる形にし、本文の画像記法には「認証要求から応答までの流れ」のような代替テキストを入れます。単に「画像」と書くと、参照先を失ったときにどの図か判断できません。
本文中の「図2を参照」という語と、画像記法の図番号が一致するかを検索します。画像が三ファイル存在し、本文の記法が三件あり、参照語も三件なら入力側の数がそろいます。画像寸法や圧縮率の最終採否は完成物検査へ渡します。
コードブロック二点では空白と長い行を観察する
コードAは三行のリクエスト例、コードBは六行のエラー処理例です。どちらもコードブロックとして囲み、本文の字下げ記号と混ぜません。インラインコードは変数名や短いコマンドだけに使い、複数行の例を一行扱いにしないことが重要です。
横書きでは英数字の向きは自然でも、長いURLや一行のJSONが画面幅を超えることがあります。入力段階では意味を壊さない折り返し位置を決めるか、説明用に短縮した標本を使います。すべての端末で同じ折り返しになるとは断定しません。
表二点は列見出しとセルの意味を単独で読めるようにする
表1はHTTP状態コード、表2は設定値の既定値を示します。最上段に列見出しを置き、「値」「説明」だけでなく「状態コード」「発生条件」のように対象が分かる語へします。空欄セルを見た目の余白として使わず、該当なしならその意味を書きます。
列数が多すぎる表は小さい画面で読みにくくなります。標本では三列までに絞り、補足は表の直後の本文へ移します。表を画像化すれば見た目は固定できますが、文字選択や読み上げが失われるため、本記事の基本手順にはしません。
入力記法と生成XHTMLの対応を確認する
横書きプレビューでは、見出し、図版、コード、表がそれぞれ別の要素として現れるかを見る手順を取ります。ただし、このプレビュー画面で記事固有標本を確認する操作は未実施です。画面上で見えたこととしてではなく、読者が行う入力確認として扱います。
一方、実機確認の無画像標本では、横書きのltr指定と、見出し、表、コードブロック、ルビが生成XHTMLへ変換されたことを確認しました。Markdown全仕様を扱う汎用エンジンとは書かれていないため、対応一覧にない拡張記法を前提にしません。
ウィザードでは横書きと段落方式を先に決める
シリーズ情報のページで横書きを選び、言語、ファイル名、段落方式を設定します。技術書の説明段落は字下げより段落間隔が読みやすい場合がありますが、作品全体で一つの方式にそろえます。コードブロック内の空白を本文段落の設定で整えようとはしません。
単巻の標本として巻選択を行い、原稿ファイルを指定します。四章の元原稿が一つなら改ページから章候補を作り、複数ファイルなら選択漏れがないようファイル名を照合します。
章順と目次対象は四章の役割で選ぶ
チャプター順で、タイトルページ、目次ページ、導入、認証、エラー処理、付録の順に並べます。本文四章は目次へ掲載し、タイトルページと目次ページ自身を章項目として重ねません。付録を目次へ載せるかは読者が参照する独立単位かで決めます。
図版名やコード例の小見出しをすべて目次へ入れると、章を探す目次が細かくなりすぎます。標本では章H2のみを主要項目とし、H3の節は必要なものだけに限定します。これは完成物のnav検査ではなく、ウィザードへ渡す選択です。
表紙は設定候補として分け、画像入り検査は保留する
メタデータのページで表紙画像を選び、作品名と版が画像内の表示と一致するかを見ます。本文中の図版三点と表紙を同じ連番へ入れず、cover-api-guide-v1.png のように別役割だと分かる名前にします。
公開資料では表紙選択と画像のEPUB格納が案内されています。実機確認の画像・表紙入り標本でもZIP内に画像資産と参照はありましたが、EPUB構造検査がmissingImagesを報告して不合格となりました。そのため、表紙を正しく登録できた、画像参照が合格したとは扱わず、設定候補の選択までに留めます。画質、色味、販売先の寸法要件も別の確認です。
図版参照表で三点の入口と出口を結ぶ
図版ごとに、図番号、本文の参照文、画像記法、実ファイル名の四列を作ります。図1の参照文があるのに記法がない、図3の記法があるのに本文から呼ばれない、といった片側だけの状態を見つけるためです。三行すべてで四列が埋まれば、図版をEPUB入力へ渡す準備ができます。
同じ画像を二章から参照する場合は、実ファイルを複製せず参照行を二つにします。ファイル数と参照数が常に同じとは限らないため、標本では一対一であることも明記します。
コードの言語名と本文の説明を対応させる
コードAはHTTPリクエスト、コードBは例外処理です。ブロックの直前に「何を確認する例か」を一文で置き、直後に期待する結果を書きます。コードだけを並べると、リフロー後にページをまたいだとき説明との対応を失いやすくなります。
タブと半角空白を混ぜると見た目の差が読者設定で変わるため、標本は半角空白へそろえます。コードの実行可否をEPUB生成の合格条件にはせず、内容検証済みのコードを入力として受け取ります。
表が横幅を超える場合の戻り先を決める
横書きプレビューで表2の三列が窮屈なら、まず長い説明を表の外へ移します。次に列見出しを短くし、それでも意味が保てない場合だけ二つの表へ分けます。文字を小さくして押し込むことを最初の解決にしません。
変更後は行見出しと本文中の「表2」参照を確認します。表を分割した場合は表2-A、表2-Bのように参照も更新し、ウィザード設定ではなく入力原稿へ戻った変更として残します。
確認済み構造と未完了の画像検査を分ける
実機確認の無画像標本では、nav、NCX、OPF、spine、横書き方向、表とコードのXHTMLを確認済みです。ただし、それはこの記事の四章、三画像、二コード、二表をすべて通した結果ではありません。記事固有標本では、nav.xhtmlの四章、spineの読む順、二コードと二表のXHTMLを期待値として「横書き技術書EPUBの生成後検査」へ渡します。
三画像の格納、画像参照、表紙登録は、実機確認の画像入りEPUB構造検査が未合格のため判断待ちです。本記事の完了は「設定と入力の準備」、「横書き技術書EPUBの生成後検査」の完了は「記事固有生成物の構造と表示の検査」と分けます。同じEPUBを扱っても中心作業と結論を重ねません。
設定完了は四章・三図・二コード・二表で判断する
出力前の確認画面で、横書き、四章の順序、四つの目次対象、表紙ファイル名を読みます。原稿側では図版記法三件、コードブロック二件、表二件が残っていることを確認します。どれかの数が違えば、出力ボタンではなく入力原稿または章選択へ戻ります。
この時点で得られる結論は「横書き技術書の部品とウィザード設定をEPUB生成へ渡す準備ができる」です。共通の無画像標本では構造を確認できましたが、記事固有の四章標本と画像・表紙入り経路は合格済みではありません。nav.xhtml、spine、全画像、端末別表示の検査は「横書き技術書EPUBの生成後検査」へ残します。まず四章標本を作り、Rune Studioの商品ページで対応記法とウィザードの範囲を確認してください。
