Vlrfsasm講習/設定

概要

本章では、HP内のページを記述するための準備を解説します。また、ページの本文のうち、題や見出しについても解説します。中身の解説は次章です。

ファイル

まずは、必要なファイルを準備しましょう。ここでは、start.htmlを生成することにします。

フォルダ

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

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

batファイル

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

vc.batCOPIED!
  1. call %toolDir%\bat\pre.bat
  2. call %toolDir%\bat\main.bat %targetDir%\start.vlra
  3. exit /b

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

本文ファイル

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

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

vlraファイル

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

設定

ここで解説する要素のうちいくつかは、ページを開いた際に直接に見るものではありません。しかし、変換器の動作や、検索時のヒット率に関わる、重要なものです。

以下の内容は全て.vlraファイルに書いてもらいます。各講習でテンプレートを用意し、編集しつつ複製すると楽でしょう。

パス

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

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

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

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

絶対パス相対パス
www.ktpc.tokyo/le/vlrfsasm/vlrfsasm.htmlvlrfsasm/vlrfsasm.html
www.ktpc.tokyo/index.html../index.html

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

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

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

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

HTML

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

項目関数名
キーワードhh.keywordプログラミング,講習, Vlrfsasm
説明hh.description駒場東邦物理部(KTPC)部員向けVlrfsasm講習の資料です。
hh.title設定 - Vlrfsasm講習 - 駒場東邦物理部

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

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

CSS

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

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

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

CSSの優先順位
default.css
narrow.css
hu.extraCssPath
hu.extraNarrowCssPath

メニュー

本HPの各ページ上部には、メニューが表示されます。メニューの内容もページによって変えることができますが、テンプレートを用意しています。テンプレートの選択は、hm.linkType関数を定義して行います。

講習目次

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

講習資料目次COPIED!
  1. {hm.linkType; ; (hm.linkType.lectureIndex)}

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

講習各章

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

講習資料目次COPIED!
  1. {hm.linkType; ; (hm.linkType.lectureChapter)}

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

講習名と目次パスCOPIED!
  1. {hm.lectureName; ; "Vlrfsasm講習"}
  2. {hm.lectureTopPath; ; "../vlrfsasm.html"}

前章と次章COPIED!
  1. {hm.previousChapterPath; ; "../structure/structure.html"}
  2. {hm.previousChapterName; ; "仕組み"}
  3. {hm.nextChapterPath; ; "../body/body.html"}
  4. {hm.nextChapterName; ; "本文"}

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

第1章の例COPIED!
  1. {hm.previousChapterPath; ; ""}
  2. [previousChapterNameは省略]

本文構造

いよいよ本文に入ります。なお、前述の通り、本文の内容を書くのは次章からです。

本節では、節と項の構造を説明します。

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

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

本章の設定の一部COPIED!
  1. {hc.content; ;
  2. ('
  3. (hc.title "Vlrfsasm講習/設定")
  4. [節1]
  5. [節2 ...]
  6. )
  7. }

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

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

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

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

段落群

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

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

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

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

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

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

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