HTML to MAML Converterを使ってみた
久々のブログ（はてなに移転して初）で、久々のSandcastle Help File Builderでございます、はい。
今回もustやったのでそのまとめをしようかと
SHFBのMAMLとやらを弄る 第三回
HTMLからMAMLを生成するだけです。それだけです。
HTML to MAML Converterの入手方法
Sandcastle Help File Builder（今回も以下SHFB）の最新版のインストーラで順番にたどっていけば入れられるはずです。わかりにくいので一応画像貼っておきます→
実際にやってみよう！！
重要：これ結構簡単
とりあえず今回はこんなHTMLで試してみました。
<!doctype html> <html> <head> <title>てすと1</title> </head> <body> <h1>セクション1</h1> <p>あーあー</p> <table> <tr> <td>あーあー</td> <td>いーいー</td> </tr> </table> </body> </html>
テキトーです。それ以外の何でもない。まぁHTMLはHTMLです。これで変換に成功してるんだから結構ひどいの書いても大丈夫じゃないかな？
では変換。コマンドプロンプトに下のを打ち込むだけ。
ConvertHtmlToMaml HTMLが入ってるフォルダ MAMLの出力先
1ファイルなら一瞬で終わります。で、出力結果はこんな感じ
MAML
<?xml version="1.0" encoding="utf-8"?> <topic id="6af36d32-57ca-4a9b-9ae3-1d6bf4bf3eea" revisionNumber="1"> <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink"> <introduction> <para>TODO: Move introduction text here</para> </introduction> <section><!--h1--> <title>セクション1</title> <content> <para>あーあー</para> <table> <row> <entry>あーあー</entry> <entry>いーいー</entry> </row> </table> </content> </section> <relatedTopics> </relatedTopics> </developerConceptualDocument> </topic>
ContentLayoutファイル
<?xml version="1.0" encoding="utf-8"?> <Topics> <Topic id="6af36d32-57ca-4a9b-9ae3-1d6bf4bf3eea" visible="True" title="てすと1" /> </Topics>
「TODO: Move introduction text here」っていうのが気になりますね。英語わからないので断定は出来なけど、自分でここに書けってことかな？と理解しておきます。ConversionRules.xml内にintroductionタグに関することは載ってなさそうですしね。
というわけでこんな感じにMAMLが生成されるということが分かりました。使うか使わないかは、あなた次第です！！（どこかのパクり）
Sandcastle Help File Builderのビルドを高速化する
本当に遅いです、うんざりするほど遅いです。で、今日もまたSHFBいじってたらいい感じに高速化してくれる方法を見つけたので紹介します。
ProjectPropertyのComponentConfigurationsを開いて、頭にCachedが付くのを全部Addするだけ。終わり。
これで次の次のビルドからそれなりに速くなります。僕の環境だと6分以上かかったのが2分程度になりました。でももうちょい速くなって欲しい…。
ヘルプドキュメントにサンプルをつける
http://www.ustream.tv/recorded/14117093
このustのまとめです。
こんかいはサンプルというか使い方の説明として実際に動きそうなコードを載せてみましたー。もちろんあのイミフなMAMLとやらで。
時間が時間なのでちゃちゃっとコード載せて終わらせたいと思います。
<example> <code lang="cs" title="C# サンプル"> <![CDATA[ IJsonItem result = Json.Parse(@"{ ""a"":10, ""b"":""text"" }"); ]]> </code> <code lang="vbnet" title="VB サンプル"> <![CDATA[ Dim result As IJsonItem = Json.Parse("{ ""a"":10, ""b"":""text"" }") ]]> </code> </example>
exampleにはいくつも突っ込めるようです。
codeはこのとおりlang属性によって自動的に色付けされます。結果はこんな感じ
title属性は付けなくても大丈夫です。lang属性の値についてはSHFBのヘルプのCode Block Componentに載っています。表なので誰でも読めるかと。
このように簡単にコードが貼れることが分かりました！以上です
Sandcastle Help File BuilderのMAML初級
前回の続きです。昼間のustでやったことのまとめです。初歩的なことすらわかってませんが日本語情報がないので書きます。
Content Layoutファイルを作る
プロジェクトを右クリックして[Add]→[New Item]→[Content Layout]で拡張子.contentファイルを適当なところ（プロジェクトと同じフォルダが無難）に保存します。このファイルは自作ページをまとめるファイルのようです。自作ページを作る
ContentLayoutファイルをProjectExplorerでダブルクリックすると新しい子ウィンドウが表示されるはずです。SHFBではContent Layout Editor Windowと呼んでるらしい。Find IDの下のListBoxで右クリックして[Add Sibling Topic]→[Standard Templates]→[Conceptual]で拡張子.amlファイルを保存します。これがXMLを拡張したMAMLと呼ばれるものらしいです。このファイルを編集してページを作ります。サンプル
<?xml version="1.0" encoding="utf-8"?> <topic id="80af5af4-1fe1-4d1b-9fab-8f2d680f91c6" revisionNumber="1"> <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink"> <introduction> <para>冒頭に表示されます。</para> </introduction> <section> <title>セクション1（省略可）</title> <content> <para>内容</para> </content> </section> </developerConceptualDocument> </topic>
動くかどうかなんて知りません（未検証の言訳）。SHFBのソースコードに入ってるヘルプのソースが一番参考になるかと。
大体の構造は見ればわかりますよね（だんだんテキトーになってきた）。introductionが冒頭でsectionが中身です。sectionタグをたくさん置けば中身を分けることもできます。paraが文字のようです。ほかにも使えるタグはあるのですがこれくらいしかわかってないので説明しません。
「タイトルを設定するタグがないじゃないか！」
これはContentLayoutEditorで設定します。下のPropertyGridのTitleという項目を編集してください。
自作ページをトップページに設定する
これは簡単です。トップページにしたいトピックを選んでContentLayoutEditorの左上にあるチェックをクリックするだけです。結論：SHFBのヘルプの日本語版落ちてないかな…。
ではまた
Sandcastle Help File Builderでカスタムページを追加する
やっとまともなこと書くときがやってきましたー！
昨日初めてSandcastleHelpFileBuilder v1.9.3.0（以下SHFB）でドキュメント作るのに成功したのでついでだからいろいろいじってみました。SHFBに不具合があったのかSandcastleにパッチ当てたからなのか前のライブラリがVBだったのがいけなかったのか…。わからん。
で、ページを自作したいと思ったんですよ。それでググってみたけど全然見当たらないし、あっても古いバージョンの情報だったのであんまり意味がない…。
それでいじりまくってたら見つけたんですよ！というわけでその工程を載せます。
- とりあえず普通にSFFBでプロジェクトをつくります。この辺はほかのサイトでいくらでも乗っているのでググってください。
- さぁいよいよページを自作しますよ！ProjectExplorerの城アイコンのプロジェクト名を右クリックします。そのメニュー[Add]→[New Item]と辿っていくと[Html page]というのがあるのでクリック！
- HTMLファイルを適当な場所に保存します。プロジェクトファイルと同じフォルダに保存すると目次に表示されないようなのでプロジェクトファイルのフォルダのサブフォルダに突っ込みましょう。フォルダが本アイコンになりHTMLがページになります。HTMLのtitleタグが表示名になります。HTMLはSHFBで編集することもできますし、エディタ使ってもたぶん大丈夫かと（未検証）
- あとはビルドするだけ♪なんですがすごい時間かかる…。僕の環境では6分ちょいでした。30秒くらいでできないものか。。
というところまでわかりました。あとは自作したページをトップページにしたいけどググっても見つからない…。英語読めないからプロパティを一つ一つ読んでいくこともできないし、うーん。
ということでまだまだ実用的なレベルまで検証できてません…。また何かあったらブログに書きたいと思います。
