14

SUN/199.12

Starlink Project
Starlink User Note 199.12

P W Draper
A J Chipperfield
M D Lawden

26 January 2009

Copyright © 2000-2004 Council for the Central Laboratory of the Research Councils
 Copyright © 2008-2009 Science and Technology Facilities Council

Star2HTML
Converting Starlink Documents to Hypertext

Version 1.6

User’s Manual


Abstract

Star2HTML lets you write (or convert) a Starlink document so that you can create two versions of it from a single source file. A paper version is produced by LATEX, and a hypertext version (suitable for browsing on the web) is produced by LATEX2HTML. You can tailor each version to its own medium by marking selected text as LATEX-only or HTML-only.

Star2HTML also includes a set of document templates for producing Starlink documents in a standard style (such as Starlink User Note). They also define new LATEX commands for adding extra links to the hypertext version of your document (without affecting the paper version).

This document explains these new facilities, and gives advice on good practice and on how to deal with some specific formatting problems when converting a document to hypertext. You are assumed to be familiar with LATEX.

The advice in this document, in particular that found in Section 5, covers the LATEX2HTML-based document conversion system and not the more modern tex4ht-based system.

Contents

1 Introduction
 1.1 Getting started
 1.2 Converting an existing document
 1.3 Some background
2 Using a template
 2.1 Changing place-holders
 2.2 Using SST macros
3 Adding links
 3.1 Internal links
 3.2 External links
 3.3 Links between Starlink documents
 3.4 Labelling sections
 3.5 Links to routine descriptions
4 Adapting to the media
 4.1 Selecting sections
5 Common conversion problems
 5.1 Things to avoid
  5.1.1 Raw TEX
  5.1.2 Parboxes
 5.2 Things that rarely look right
  5.2.1 Tabbing environments
 5.3 Irritants
  5.3.1 Unwanted blank lines
  5.3.2 Tildas in URLs
 5.4 Using the htmladdimg command to replace figures
 5.5 Hints from the Starlink Software Librarian
6 Finally
7 References
A The star2html command
B The xlabel command
C The structure of a converted hypertext document
D Changes in release 1.6
 D.1 Incompatibilities with previous documents
E Changes in release 1.5
F Changes in release 1.4
G Changes in release 1.3