Course Report

Sgc
%TOC%

---++ Introduction

The report for this course is written in <nop>DocBook, an XML-based language widely used in the industry for writing technical documentation. The source of the report is distributed as an GNU Autotools package, which can easily be built on your local machine and is continuously built by our buildfarm. The latest version is available at:

   * http://nix.cs.uu.nl/dist/courses/sgc-report-unstable-latest/manual/

The report can also be downloaded at:

   * http://nix.cs.uu.nl/dist/courses/sgc-report-unstable-latest

---++ Installation Instructions

We advice you to work on the report at a Linux system with [[http://www.cs.uu.nl/wiki/Trace/Nix][Nix]] installed.

---+++ Install Dependencies

<!--
   * Set NIXPKGS = http://nix.cs.uu.nl/dist/nix/nixpkgs-0.9pre4279/pkgs
-->

Install dependencies by clicking on the following links and opening the files with =/nix/bin/nix-install-package=.
   * [[%NIXPKGS%/docbook-ng-5.0pre20050724-pto-i686-linux.nixpkg][docbook-ng-5.0pre20050724-pto]]
   * [[%NIXPKGS%/docbook-xsl-1.69.1-i686-linux.nixpkg][docbook-xsl-1.69.1]]
   * [[%NIXPKGS%/libxml2-2.6.22-i686-linux.nixpkg][libxml2-2.6.22]]
   * [[%NIXPKGS%/libxslt-1.1.14-i686-linux.nixpkg][libxslt-1.1.14]]
   * [[%NIXPKGS%/jing-tools-20030619-i686-linux.nixpkg][jing-tools-20030619]]
   * [[%NIXPKGS%/batik-1.6-i686-linux.nixpkg][batik-1.6]]
   * [[%NIXPKGS%/jre-1.5.0-i686-linux.nixpkg][jre-1.5.0]]

and optionally (if not available on your system, which is unlikely)
   * [[%NIXPKGS%/autoconf-2.59-i686-linux.nixpkg][autoconf-2.59]]
   * [[%NIXPKGS%/automake-1.9.6-i686-linux.nixpkg][automake-1.9.6]]
   * [[%NIXPKGS%/subversion-1.2.3-i686-linux.nixpkg][subversion-1.2.3]]

You might have to redo this if you are going to work on a different machine next time, since the installation is machine specific.

---+++ Checkout, Configure, and Build

Checkout report:
<verbatim>
$ svn checkout https://svn.cs.uu.nl:12443/repos/sgc-report/trunk/ sgc-report
</verbatim>

Configure the report using:
<verbatim>
$ ./bootstrap
$ ./default-config.sh
</verbatim>

Build report:
<verbatim>
$ make manual
</verbatim>

The report will now be available in =mandist/manual/index.html=.

---+++ Working at Home

For working at home, we advice to install Nix and use the installation instructions. If this is not possible for you (e.g. if you are stuck with Microsoft Windows), then you can just install the dependecies yourself. You need to configure the package in a different way for this, so you cannot use =default-config.sh=.

You can also write in the report without actually building it, but make sure that the XML is valid <nop>DocBook, otherwise the build in the buildfarm will fail and others authors might not be able to compile the report.

---++ Writing Documentation

---+++ <nop>DocBook Resources

[[http://www.docbook.org/tdg5/en/html/docbook.html][DocBook 5.0: The Definitive Guide]] explains the <nop>DocBook language and provides a reference guide to the elements of the language. The [[http://www.docbook.org/tdg/en/html/docbook.html][previous edition]] of the Definitive Guide is at some points a bit more complete, but shoud only be used if you are looking for examples. In the documentation of the <nop>DocBook XSL stylesheets there is a chapter that explains the use of [[http://www.sagehill.net/docbookxsl/ModularDoc.html][XInclude in DocBook]].

---+++ Examples

Nix Manual:
   * https://svn.cs.uu.nl:12443/repos/trace/nix/trunk/doc/manual/

Stratego/XT Manual
   * https://svn.cs.uu.nl:12443/repos/StrategoXT/strategoxt-manual/trunk/doc

---+++ Editor

For writing <nop>DocBook, the [[http://www.thaiopensource.com/nxml-mode/][nxml-mode]] in Emacs is an excellent choice, since this will validate <nop>DocBook inside your editor. Using a different editor will severly slow you down, since <nop>DocBook is a rather verbose language. Therefore, auto-completion (ctrl-cf) and validition is very helpful.

Install:
   * [[%NIXPKGS%/emacs-21.4a-Z-i686-linux.nixpkg][emacs-21.4]]
   * [[%NIXPKGS%/nxml-mode-20041004-i686-linux.nixpkg][nxml-mode-20041004]]

From the directory =config-helpers= in the report, copy the file =.emacs= to your home dir:
<verbatim>
$ cp .emacs ~
</verbatim>

Make a directory =~/.myemacs=
<verbatim>
$ mkdir ~/.myemacs
</verbatim>

Copy the following files to =~/.myemacs=:
<verbatim>
$ cp cua.el ~/.myemacs
$ cp schemas.xml ~/.myemacs
</verbatim>

Start emacs with:
<verbatim>
$ /nix/var/nix/profiles/default/bin/emacs
</verbatim>