ホームページ wiki 2011-10-23

オンラインマニュアルのメンテナンスについて

概要

概要

JDのマニュアルは更新作業を簡素化するためXMLで記述し、JDがリリースされた時にXSLTプロセッサでHTMLに変換する方法をとっています。

また、この文書は"svn+ssh://ユーザー@svn.sourceforge.jp/svnroot/jd4linux/jd/help"の作業コピーを起点としています。

ポリシー

ポリシー

一部のWebブラウザだけではなく、多くの環境で閲覧出来る事を目標にしています。

変換後のHTMLに対して

内容の更新について

内容の更新について

SVNリポジトリにあるXMLは随時変更します。

これ以降のYYYYは2011などの年数に読み替えて下さい。

各ファイルで使用しているXMLの書式について

全体の仕様はxml/main.xsl及びxml/document.dtdに書かれています。

また、以下に挙げる物はxml/main.xslの他に独自の要素を追加しています。

  • history.xsl (history.xml, YYYY.xmlで使用)

CSSについて

CSSは全てxml/main.cssに書かれています。

新規にファイルを追加する

  • 他のファイルやxml/main.xslに書かれているコメントなどを参考に作成して下さい。
  • XSLTスタイルシートに対応しているWebブラウザ(Firefoxなど)で追加したページの表示を確認する。

  • SVNリポジトリを更新する。

    $ svn add xml/追加したファイル
    $ svn commit -m "コメント" xml/

更新履歴を書く

xml/YYYY.xmlの要素<release>の中に一行ずつ簡潔に書きます。

基本的にプレーンテキストですが、「&」→「&amp;」「"」→「&quot;」などの変更を必ずします。

年が変わる場合

更新履歴は年ごとに分けているので、年が変わる場合は以下の作業をします。

  • 前年のフォーマットを参考にxml/YYYY.xmlを作成する。
  • xml/history.xmlの要素<history>に以下を追加する。

    <year>YYYY</year>
  • XSLTスタイルシートに対応しているWebブラウザ(Firefoxなど)で全てのページの表示を確認する。

  • SVNリポジトリを更新する。

    $ svn add xml/YYYY.xml
    $ svn commit -m "コメント" xml/

JDリリース時の作業について

JDリリース時の作業について

JDがリリースされた時には以下の作業を行います。

  • xml/YYYY.xmlの要素<release>を変更する。

    <release version="major.minor.micro-releaseYYMMDD" date="YYYY/MM/DD(W)">
  • XSLTプロセッサを使用してXML(xml/*.xml)を元にHTML(任意の場所/*.html)に変換する。

    $ make manual OUT=任意の場所 [JAVA=/path/to/java, SAXON=/path/to/saxon]

    現在はXSLTプロセッサにSAXONを使用しています。

    ファイルを追加した場合はMakefileを修正する必要があるかも知れません。

  • 変換したHTMLが正常に閲覧可能かどうかWebブラウザで確認する。

  • 任意の場所/以下のファイルをJDのWebサイトにアップロードする。(gFTP等でも可能)

    Webサイトに設置するマニュアルはリリース番号ごとにディレクトリを分けています。

    リリース番号例( 2.8.2-110808 → 282 )

    $ cd 任意の場所
    $ sftp ユーザー名@shell.sourceforge.jp:/misc/groups/j/jd/jd4linux/htdocs/manual/
    sftp> ( mkdir -pm 775 リリース番号 && chgrp -c jd4linux リリース番号 ) && cd リリース番号
    sftp> mput *
    sftp> chgrp -cR jd4linux * && chmod -cR g+w *
    sftp> ls -al
    sftp> quit

    グループについて

  • 実際にWebブラウザでアクセスして確認する。

    http://jd4linux.sourceforge.jp/manual/リリース番号/