F.2.2 Decisions from 1999 September 24 meeting, Durham

F.2.2.1 Packaging and Installation

Multi-platform support deferred.

No action required.

Everything packaged as one lump. Norman and Martin to decide how to arrange packing details (build, installation).

dvi2bitmap incorporated into package.

Makefile to support all standard targets.

Done

Do not produce document summaries when sgmlstar is installed.

Done.

No documentation processing when standard packages are installed. Each package has printable (optional), HTML and SGML.

Documentation build at export time. HTX and LaTeX documentation included in package, but no SGML. This is because SGML files can, in general, include files from elsewhere, either as simple inclusions (as is the case for the DTD documentation in this document), or as subdocument references (as is the case for any program source code marked up in the programcode DTD. This makes packaging of the SGML source not necessarily trivial. It can, of course, still be done if we feel there's a need for it, but it's not done in the case of this package.

F.2.2.2 Running Down Converters

Need simple commands sgml2latex and sgml2html instead of makefile, leaving no temporary files (even in the event of failure), and doing all necessary processing (maths, backmatter, etc).

Script sgml2docs provided. See notes above.

All HTML files to go in a .htx sub-directory; The document name should not be included in the HTML file names; The top level HTML file should be index.html; Need shorter names for html files; There should be no links within the .htx directory.

All done.

Need a fix for line breaks within tags in htx index file; Findme, showme and hlink should all work.

Jade output now normalised in a post-processing step, and the HTX programs now work.

F.2.2.3 Hyperlinking

Must be able to process documents which refer to other starlink documents which are not available (i.e. allow unresolved FPIs); Must function in the absence of some (or all) document summaries; In the absence of referenced documents, the URLs referring to the unavailable documents should produce standard HTX remote reference to the document server at RAL.

Supported, by making the error-handling code much more sophisticated. See above.

There should be an ID index page at the end of the HTML version, containing links back to referenced points within the document. Each page should have a link to the start of its entries in the ID index.

Done

Keep open the possibility of using document summaries as an option. For the moment, we will not generate or distribute such summaries (but we may change this later).

Use of document summaries is still the documented way, but I've added a note that the public identifier can be unresolved without error.

F.2.2.4 LaTeX Output

Everyone to pass commented LaTeX output to Mark or Norman.

Done at meeting.

Table of contents: move it to the front.

Done. Settable through --options flag to sgml2docs.

Look-and-feel: reproduce original LaTeX appearance.

Page size fixed.

Down-converter should have two flags (defaulting to yes) to indicate if each appendix or section should start on a new page.

Done. Settable through --options flag to sgml2docs.

Tables: implement alignment, rules, colspan.

Done. Implementation is not complete, but has most of LaTeX functionality.

Authors should manually replace tabbing environments within LaTeX documents before running the up-converter. The up-converter should issue a warning if it finds a tabbing environment.

No action needed.

Optional inclusion of section headings in table of contents will not be supported.

No action needed.

Need increased sloppiness in line wrapping.

I haven't addressed this here, since it's only RH 6.0 which is affected by a distribution bug, and RH 6.1 is already available.

Verbatim text (displayed only) needs to be a bit smaller.

Done.

F.2.2.5 HTML Appearance

Look-and-feel: be guided by ease of implementation, but if possible, try to reproduce the current style (for instance, do not specify a background colour).

??

Navigation buttons: retain the system used by latex2html.

??

Move the abstract off the front page.

??

RAL links should be combined into the CCLRC link.

??

Down-converter should only add the standard copyright statement (available from MJB).

??

Hard copy: retrieve .ps files from RAL server.

??

Section numbers: keep them in the HTML, but slim down their use in the table of contents.

??

Alignment of in-line gifs and bitmaps needs to be corrected.

Done