Vlrfsasm講習/設定

フォルダ

フォルダは、必ずページごとに作りましょう。ページのhtmlと同名がいいでしょう。

例えば、start/start.htmlのようにします。

batファイル

作ったバッチフォルダ内に、vc.batを作りましょう。中身は以下です。

vc.batCOPYCOPIED!

call %toolDir%\bat\pre.bat
call %toolDir%\bat\main.bat %targetDir%\start.vlra
exit /b

ただし、赤下線部は、次々項で作る.vlraファイルの名前に合わせて変えてください。

本文ファイル

次に、vkhc.txtファイルを作り、そのままにしておいてください。次章で書き方を解説します。

なお、前項のvc.batではこのファイルを指定しませんでした。名前を固定する代わりに、指定する手間を減らしています。詳しくは、技術的な解説を参照してください。

vlraファイル

それでは、start.vlraを作りましょう。もちろん、出力するhtmlがstart.htmlでなければ、そちらの名前に合わせるのがよいでしょう。

パス

HTMLで画像などを表示するときには、画像ファイルのパスを指定します。パスの指定方法には2種類あります。

「絶対パス」では、www.ktpc.tokyoから目的のファイル名まで全てを書きます。ブラウザはこのアドレスにアクセスし、サーバーからデータをもらいます。

「相対パス」では、HTMLファイルが置かれているディレクトリを基準にして書きます。../と書くと、親ディレクトリを指定できます。

以下の例では、www.ktpc.tokyo/le/le.htmlを基準としています。

どちらにも長所と短所がありますが、本HP内から本HP内のパスを指定する際は、相対パスがよいでしょう。まず、ほとんどの場合、見ての通り短く書けます。また、コンピュータのローカルのファイルからの相対パスは、同様にローカルのファイルを参照するため、インターネットなしでもリンク切れを起こしません。インターネットに繋がっていても、コミット内容の反映には時間がかかるので、やはり相対パスが有利です。

絶対パスの長所は、1つのパスが、どのファイルにおいても同じ意味を持つことです。相対パスでは、階層構造を考慮する必要が出てきます。

本変換器では、両者の利点を活かす折衷案を用意しています。hp.getRelativePath関数は、www.ktpc.tokyoを基準とした相対パスを引数に取り、HTMLファイルのディレクトリを基準とした相対パスを返します。

さて、前置きが長くなりました。hp.getRelativePath関数は、HTMLファイルのパスを知らなければ動作しません。これを指定するのが、hp.path関数です。引数なしの定数関数として定義してください。返り値は、www.ktpc.tokyoを基準とした相対パスを指定します。HTMLファイルの名前まで指定してください。他の用途もあります。

HTML

HTMLには、文章の記述以外にも、検索という用途があります。このため、本変換器でも以下の3つを設定するようにしています。なお、引数なしの定数関数として、必ず全てを定義してください。

キーワードは,区切りで複数指定できます。

なお、例は本章のページのものです。

CSS

本変換器によるHTMLのスタイルを定めるCSSファイルは、https://www.ktpc.tokyo/tool/vlrfsasmKtpc/style/default.cssです。しかし、講習ごとにスタイルを変える、あるいは新しいスタイルを追加する、といった需要もあるでしょう。そこで、定数関数hu.extraCssPathを定義します。返り値にはCSSファイルのパスを指定してください。なお、使わない場合でも、空文字列を返す関数として定義しておきましょう。

また、default.cssと同フォルダにnarrow.cssが入っていますが、これはスマホ向けです。hu.extraNarrowCssPathも同様に定義してください。画面の幅によって、追加で適用されるようになります。

これらのCSSファイルの優先順位は、以下の表で下のものほど高いです。つまり、スタイルの衝突時には、下のものによって上書きされます。

講習目次

テンプレートの1つめは、講習資料の目次向けです。

講習資料目次COPYCOPIED!

{hm.linkType; ; (hm.linkType.lectureIndex)}

このように定義すると、メニューが自動で生成されます。先ほどのhp.pathできちんと指定しないと、ここで自身へのリンクが含まれてしまうので、注意してください。講習の一覧は、tool/vlrfsasmKtpc/le/lectureList.vlraで定義されています。新しい講習を追加する際には、ここを更新し、他の講習者にも目次ページの更新を依頼してください。

講習各章

テンプレートの2つ目は、講習資料の各章のページを想定しています。

講習資料目次COPYCOPIED!

{hm.linkType; ; (hm.linkType.lectureChapter)}

このテンプレートでは、これに加えて4から6個の定数関数を定義する必要があります。

講習名と目次パスCOPYCOPIED!

{hm.lectureName; ; "Vlrfsasm講習"}
{hm.lectureTopPath; ; "../vlrfsasm.html"}

前章と次章COPYCOPIED!

{hm.previousChapterPath; ; "../structure/structure.html"}
{hm.previousChapterName; ; "仕組み"}
{hm.nextChapterPath; ; "../body/body.html"}
{hm.nextChapterName; ; "本文"}

なお、ChapterPathを空文字列にすると、リンクは生成されません。このとき、対応するChapterNameは使われないので、定義する必要はありません。

第1章の例COPYCOPIED!

{hm.previousChapterPath; ; ""}
[previousChapterNameは省略]

題

本変換器は、hc.content関数の返り値を、本文として組み込みます。

また、hc.title関数は、文字列を1つ引数にとって、題名のHTML要素を返します。

本章の設定の一部EXPANDCOLLAPSECOPYCOPIED!

{hc.content; ;
  ('
    (hc.title "Vlrfsasm講習/設定")
    [節1]
    [節2 ...]
  )
}

節

節を返す関数は2つあります。

hc.articleは、第一引数に節の見出し、第二引数に節の内容をとります。内容は、次項で解説する項を1つ以上入れるか、またはc.emptyにしてください。

hc.articleCaは、見出しの次に引数が1つ増え、節全体の概説を入れることができます。こちらには、項ではなく、次々項の段落群を入れてください。

項

項は、hc.sectionで生成します。第一引数に見出し、第二引数に段落群を指定しましょう。

段落群

ここでは「段落群」という言葉を用いますが、これは単に「段落」というと一段落限定のように見えるからです。実際には、1個以上のいくつでも段落を含められます。

さて、段落群の内容は次章で記述します。見た目は異なるものの、実質的には定数関数を定義するだけです。

関数の返り値は、関数を呼び出せば得られます。呼び出しには名前が必要です。作者の命名規則は、ht.<節名>.<項名>というものです。

まず、接頭辞はht.とします。hはHTML、tはtextを指していたのだと思いますが、記憶は曖昧です。ともかく、他の場所では使っていないので、これを使っておけば衝突を避けられます。

節名と項名については、英単語1語がよいでしょう。もちろん、vlrfsasmの符として正しければ、何でも構いません。

例

面倒なので、実際に本章の設定ファイルを見てください。

なお、本章では、概説なしのhc.articleを使っていません。