20. DocのHTML変換へんかん

nepl3-doc-html はDoc coreとmarkupへ依存いぞんする純粋じゅんすいbackendであり、ファイル・DOM・guest意味処理いみしょりを実行じっこうしない。言語中立げんごちゅうりつの値あたいは interfaces/doc-html.json に定義ていぎする。本章ほんしょうのlocal入口いりぐちは、外部要求がいぶようきゅうが一ひとつもないArticleまたはSentenceをHTML fragmentへ変換へんかんする制約せいやくを持もつ。Sentence単独たんどくの入口いりぐちはArticleとは別べつの型かたで準備済じゅんびずみであることを表あらわし、phrasing fragmentを返かえす。Ruby・Anno・BreakにはArticleと同おなじ変換規則へんかんきそくとCSSを使つかう。rootはclass nepl-sentenceのspanとし、空白くうはくを保持ほじするが、Article用ようの余白よはく・背景はいけい・fontは設定せっていしない。単独たんどくSentenceのanchorとrefは、そのSentenceだけの名前空間なまえくうかんで検査けんさする。前方参照ぜんぽうさんしょうを認みとめ、重複定義じゅうふくていぎ・複数表示経路ふくすうひょうじけいろ・未解決参照みかいけつさんしょうを拒否きょひする。周囲しゅういのArticleやforeign文書ぶんしょから暗黙あんもくにlabelを取とり込こまない。Article内ないのSentenceには、従来じゅうらいどおりArticle全体ぜんたいの規則きそくを適用てきようする。準備計画じゅんびけいかくはDocumentSyntaxのrootを含ふくむdigestと全すべての外部要求がいぶようきゅうを保持ほじする。NDF受信側じゅしんがわはrootに対応たいおうするArticleまたはSentenceの検査けんさを再実行さいじっこうし、送信側そうしんがわの計画けいかくとの一致いっちを要求ようきゅうする。document shellと固定こていCSSの配布はいふは、後述こうじゅつの開発かいはつhostが担当たんとうする。一般いっぱんpage/asset/foreign解決かいけつと完全かんぜんなReport操作そうさは、このlocal入口いりぐちの責務せきむに含ふくめず、別べつの統合経路とうごうけいろで扱あつかう。

LocalHtmlRequest はDocumentSyntaxとRenderOptionsを所有しょゆうする。request codecはDocの構造こうぞう・source閉包へいほうを再検査さいけんさし、optionsをraw値ちとして復元ふくげんする。実行準備じっこうじゅんび prepare_local は、Docの要求発見ようきゅうはっけんとlabel検査けんさを実行じっこうする。外部要求がいぶようきゅうがあれば完全かんぜんなplanをNeedsResolutionとして返かえし、空からfragmentへ変かえない。この拒否きょひは、外部がいぶURIの合法性ごうほうせいやMath式しきの意味いみエラーを判定はんていしたものではない。要求ようきゅうがなければoptionsとlocal backend制約せいやくを検査けんさし、対象たいしょうdocument/optionsを借用しゃくようする非公開ひこうかいconstructorのPreparedLocalArticleを発行はっこうする。

ParallelModeは、Rows、Columns、Single(language,fallbacks)のいずれかとする。Singleの言語げんごタグは共通きょうつうLang規則きそくに従したがい、候補こうほの重複ちょうふくはASCII case-insensitiveで拒否きょひする。各かくParallelは、指定していlanguageから明示めいじfallback順じゅんに一致いっちするvariantを選えらび、存在そんざいしなければMissingVariantとする。空からSentenceは、存在そんざいするvariantとして保持ほじする。Rows/Columnsは、元順もとじゅんの全ぜんvariantを表示ひょうじする。各表示出現かくひょうじしゅつげんのdata-nepl-groupは生成せいせいelementの番号ばんごうから決定けっていし、同おなじDoc nodeを複数表示ふくすうひょうじしても出現しゅつげんを区別くべつする。

Articleはclass nepl-docと言語げんごを持もつarticle、titleはh1とする。SectionはUTF-8 byteの小文字こもじhexにn-を付つけたidと見出みだしを持もち、sectionの入いれ子こごとにlevelを増ふやす。6を超こえる見出みだしは、role=heading/aria-levelのdivとする。Anchor/Referenceも同おなじid写像しゃぞうを使用しようする。Paragraphはdivとし、連続れんぞくSentence/Parallelをpへまとめ、子こBlockは独立どくりつdiv内ないへ出だし、前後ぜんごのpを閉とじる。子この元順もとじゅんと空白くうはくを保持ほじする。

Sentence/Concatはspan、Emphasis/Strongはem/strong、明示めいじBreakはbrとする。Ruby/Annoは型付かたつきspanと固定こていCSSを使つかい、base/reading/全ぜんnoteを別要素べつようそとして保持ほじする。Tableはheaderのthead、順序付じゅんじょつきtbody/trとth/td、列れつalignmentの固定こていclassを使つかう。空表くうひょうは、空からtableのままにする。Listはul/ol、itemはliとBody、明示めいじcheckboxは状態じょうたいを持もつ表示ひょうじspanとする。HTMLのol.start範囲はんいを超こえるU64はListStartとして拒否きょひし、丸まるめない。RawCodeはfigureの任意にんいcaptionにlanguageHintを保持ほじし、pre/codeには元もとTextを置おく。hintをparser実行要求じっこうようきゅうへ変かえない。

renderはHTML arenaを反復構築はんぷくこうちくし、全生成ぜんせいせいnode・属性ぞくせい・文字列もじれつ・処理待しょりまち・深ふかさをBudgetへ計上けいじょうする。全結果ぜんけっかを共通きょうつうmarkup validatorへ通とおす。本文ほんぶん/属性ぞくせいのXML不適合ふてきごうやHTML内容不適合ないようふてきごうは、型付かたつきMarkup失敗しっぱいとする。これらを削除さくじょして成功せいこうにしない。出力しゅつりょくfragmentの深ふかさは256までとし、超過ちょうかはOutputDepthとして元もとDoc nodeを示しめす。これはbrowser出力しゅつりょくprofileの限界げんかいであり、入力意味にゅうりょくいみモデルを平坦化へいたんかする規則きそくではない。文書ぶんしょshellは残のこりの閲覧側深度えつらんがわしんどを含ふくめて検査けんさし、実じつbrowserで再確認さいかくにんする。

RenderedFragment はdocumentDigest、RenderOptions、HtmlRequest、ElementOrigin(element,node)列れつを保持ほじする。elementは出力しゅつりょくarena、nodeは明示めいじDoc arenaの番号ばんごうで、生成せいせいしたText/elementごとに一ひとつの原因げんいんを出力順しゅつりょくじゅんで保持ほじする。元もとDocのSpan/Origin/source表ひょうを参照さんしょうし、架空かくうの生成せいせいsource位置いちを作つくらない。固定こていstylesheetはcrateのassets/doc.cssであり、HtmlPolicy自己申告じこしんこくやfragment単体たんたいを、CSS配布済はいふずみの証明しょうめいとしない。

portable rendered値ちは、prepared document/optionsを明示めいじして受うけ取とる。schema・markup・32byte digestを検査けんさした後あと、同おなじbackendで再生成さいせいせいし、正式値せいしきちのcanonical CBORに NEPL3.Doc.Html.Fragment.v1 とゼロbyteを前置ぜんちしたdigestを比較ひかくする。改変かいへんmarkup、原因対応げんいんたいおうの欠落けつらく・変更へんこう、別べつdocument/optionsの結果けっかを、raw受信じゅしんしたproofとして採用さいようしない。これは現在げんざいの純粋じゅんすいlocal変換へんかんの再実行比較さいじっこうひかくであり、将来しょうらいの外部がいぶrendererの授権じゅけんや完全かんぜんなArtifact検査けんさを代行だいこうしない。全体ぜんたいの停止ていし・資源しげんUsageは、同おなじBudgetで単調たんちょうに保持ほじする。

local入口いりぐちと要求発見ようきゅうはっけんだけで、T23やT21を完成かんせいにはしない。ページの外部がいぶリンク・画像がぞう・foreign表現ひょうげんを含ふくむ正式要求せいしきようきゅうを満みたしてから、16章しょう/18章しょうに従したがって.nepld正本せいほんへ切きり替かえる。

開発かいはつhostによるローカル文書ぶんしょの書かき出だし

nepl3-tools doc-html export <input.nepld> <new-directory> は、共通きょうつうの標準ひょうじゅんDoc source処理しょりからlocal HTMLを生成せいせいし、document.html、assets/doc.css、manifest.json を新あたらしいディレクトリへ書かく。既存きそんの出力しゅつりょくは上書うわがきしない。入力にゅうりょくはUTF-8、読取よみとり上限じょうげんは10,000,000 bytesとし、上限じょうげんを超こえた内容ないようを解析かいせきしない。生成せいせいを完了かんりょうしてから出力しゅつりょくディレクトリを作つくる。I/O途中とちゅうの失敗しっぱいでは不完全ふかんぜんなディレクトリが残のこり得うるため、manifestは最後さいごに書かき、失敗しっぱいを成功せいこうにしない。

この入口いりぐちは開発用かいはつようhostであり、検査済けんさずみbootstrap fixtureをGrammar compilerへ渡わたしてpackageを構成こうせいする。正式せいしきCLI、生成せいせいpackage配布はいふ、suite、全資源解決ぜんしげんかいけつの完成かんせいとは区別くべつする。source読取よみとり/検査けんさ、lower、prepare/render/serializeは、それぞれ明示めいじした独立どくりつBudgetを持もつ。manifestのUsageはその単位たんいで記録きろくし、文書全体ぶんしょぜんたいが一ひとつのBudgetで完走かんそうした記録きろくへ読よみ替かえない。ファイルI/OとmanifestのJSON整形せいけいは、hostの責務せきむである。

shellは固定こていHTMLと検査済けんさずみfragmentだけから作つくり、stylesheetはbackendの同おなじ固定こていbyte列れつを配布はいふする。CSPは既定きていの取得しゅとく・script・formを禁止きんしし、同おなじoriginのstylesheetだけを許可きょかする。manifestは入力にゅうりょく、Profile、Doc schema、生成せいせいHTML/CSSのdigestと表示ひょうじoptionsを保持ほじする。現在げんざいの形式けいしきはlocal export用ようの記録きろくであり、17章しょうのKaTeX資源しげんbundleや汎用はんようArtifactの境界検査きょうかいけんさを代行だいこうしない。HTTPの非ひroot pathとJavaScript無効むこうの実じつbrowserで、生成物せいせいぶつを検査けんさする。外部がいぶpage/asset/foreignが必要ひつような文書ぶんしょはNeedsResolutionのまま拒否きょひし、リンクや埋うめ込こみを落おとしたHTMLを書かき出ださない。

固定こていCSSのbaselineと対応範囲たいおうはんい

Rubyはreadingを第だい1行ぎょう、baseを第だい2行ぎょうとし、baseline-source:lastでbase側がわのbaselineを外そとへ公開こうかいする。Annoはbaseを第だい1行ぎょう、notesを第だい2行ぎょうとし、baseline-source:firstを使つかう。空からの先頭行せんとうぎょうを挟はさまない。これにより、入いれ子このbaseも内側要素うちがわようそが公開こうかいするbaselineで整列せいれつする。明示改行めいじかいぎょうを含ふくむbaseの場合ばあい、Rubyは最後さいごの行ぎょう、Annoは最初さいしょの行ぎょうが整列基準せいれつきじゅんになる。高たかさを仮定かていした固定こていoffsetやJavaScriptで合あわせない。

この指定していは CSS Inline Layoutのbaseline-source と Gridのbaseline規則きそくに基もとづく。Inline Layoutは草案そうあんであり、仕様しようの存在そんざいだけを全ぜんbrowserでの実装証拠じっそうしょうこにしない。生成文書せいせいぶんしょの対応たいおうbrowserは、固定こていCSSとの実試験じつしけんで確認かくにんする。幅はばが狭せまい場合ばあいにもRuby/Annoの内部ないぶを任意位置にんいいちで分割ぶんかつせず、max-contentの一ひとつのinline boxとして保持ほじする。長ながいbase/reading/notesやpre内ないcodeは横よこにはみ出だし得うるため、hostの閲覧えつらん・印刷いんさつprofileは、その表示ひょうじと移動手段いどうしゅだんを別途検証べっとけんしょうする。

baseline-source:first/lastの両方りょうほうを利用りようできないbrowserでは、同おなじspan構造こうぞうにinline-tableの固定こていCSSを適用てきようする。readingは上側うえがわ、notesは下側したがわのtable-captionとし、baseを持もつ唯一ゆいいつの行ぎょうからbaselineを公開こうかいする。Rubyのbaseはinline-blockとして最終行さいしゅうぎょうのbaselineを、Annoのbaseはtable-cellとして最初さいしょの行ぎょうのbaselineを公開こうかいする。DOMの順序じゅんじょや注釈内容ちゅうしゃくないようを変更へんこうせず、HTMLの表要素ひょうようそやJavaScriptを追加ついかしない。この代替だいたいはWebKitで基底文字きていもじが本文ほんぶんより下さがる不具合ふぐあいへの対応たいおうであり、型付かたつきmarkup・意味正規形いみせいきけいは変更へんこうしない。

代替だいたいの根拠こんきょは CSS2のinline-block baseline と tableのbaseline規則きそくである。対応たいおうpropertyの有無うむだけで合否ごうひを決きめず、実際じっさいのproduction HTMLとCSSをChromium・Firefox・WebKitで表示ひょうじし、本文ほんぶんとのbaseline、読よみ・注釈ちゅうしゃくの上下配置じょうげはいち、複数行ふくすうぎょうの基準きじゅん、入いれ子こと前後行ぜんごぎょうの高たかさ予約よやくを検査けんさする。文書内ぶんしょないのJavaScriptは無効むこうとする。この静的文書せいてきぶんしょの検査けんさはWasm・Playground・支援技術しえんぎじゅつによる実操作じつそうさの受入うけいれを代行だいこうしない。