7.3 Example: SUN upconversion step by step

The following gives an example of the steps which might be followed to generate an SGML SUN from existing source in a LaTeX document and prologues of associated source files. An actual conversion might skip some of the steps below or use some more, but this should provide a useful reference for how to proceed. More discussion of the steps can be found in the previous subsections and in the code2sgml and latex2sgml command descriptions.

First, generate marked up prologues:

1. Identify the relevant source files (those for user-level subroutines or commands) from the source archive.
2. Use code2sgml to mark them up as SGML; if you want to generate copies of the source files marked up in SGML to be used in future as the primary source, do

   code2sgml this.f > new/this.f
   code2sgml that.f > new/that.f
   code2sgml other.f > new/other.f
   code2sgml -d this.f that.f other.f > new/routines.sgml

   but if you want to make a one-off conversion just for the sake of generating this copy of the SUN, do

   code2sgml -D this.f that.f other.f > routines.sgml

3. Assess how well the conversion went:
   • Examine any warnings which code2sgml wrote to standard error.
   • Check whether the resulting document conforms to the programcode DTD:

     parse -s routines.sgml

     (this will print errors to standard output if there is a problem - see the parse documentation for details).
   • Examine the marked up prologues by hand to see if the markup looks semantically correct. In particular keep an eye out for
     • Blocks marked up verbatim which shouldn't be
     • Blocks not marked up verbatim which should be
     • Single element ul lists which could more appropriately be marked up otherwise
4. If there have been problems, then either fix up the resulting SGML by hand, or modify the original source files and repeat the conversion. If there appear to be consistent differences in usage between the existing source prologues and what code2sgml is expecting, it may be worth tailoring the configuration file before attempting the conversion again; use one of the default files c2s.fortran or c2s.script which live in the same directory as code2sgml as a template:

   cp /star/bin/sgml/c2s.fortran ./c2sconfig
   vi c2sconfig
   code2sgml -c c2sconfig -D this.f that.f other.f > routines.sgml

5. The resulting SGML document can now be used for generating both the descriptions of commands or routines in the SUN and, if applicable, Starlink .hlp files for use by the HLP system (SUN/124). Because of the way that the files have been generated, they will contain only ASCII-like content. If you want to include more sophisticated content, for instance LaTeX representations of mathematics, the new prologues can be altered. If they will be used for generating HLP files (viewed on a character terminal) as well as the SUN descriptions, then alternative forms of such parts should be retained using the span element, e.g.

   <span media='tty'>
   <verbatim>
      x**n + y**n = z**n
   </verbatim>
   </span>
   <span media='print,screen'>
   <mequation>
      x^n + y^n = z^n
   </mequation>
   </span>

6. If the conversion is satisfactory, you may wish to check that the converted copies of the source files still compile (they certainly should) and replace the originals in the source archive.

The prologues having been marked up, the main text of the SUN must now be converted to SGML. This can be a somewhat iterative process depending on the success of the various stages.

1. Remove the appendix which contains command/subroutine descriptions from the LaTeX file.
2. Make preparatory adjustments to the LaTeX as advised in 7.1 Upconversion from LaTeX:
   • Remove low level HTML and LaTeX formatting commands where possible, especially in user macros
   • Ensure that figures, including \includegraphics-type commands, are contained within LaTeX figure environments
   • Remove (and make a note of) any LaTeX macro definitions which you want to remain as user macros instead of being expanded in the final document
3. Perform the conversion, specifying the location of the SGML command/subroutine documentation if applicable:

   latex2sgml -R routines.sgml sun321.tex

4. Assess how well the conversion went:
   • Attend to anything which latex2html itself complains about (the first part of the screen output of latex2sgml)
   • Look at the sun321.translog file, especially lines beginning with `4:' or lower numbers.
   • Check whether the resulting document conforms to the programcode DTD:

     parse -s sun321.sgml |& grep -v :W:

     (this invocation ignores warnings about missing Summary subdocument entities, which are harmless)
   • Examine the resulting document by hand to see whether the markup looks right semantically.
5. If there have been problems, then either edit the original LaTeX document accordingly and do the upconversion again, or edit the resulting SGML. In fact some combination of these techniques combined with repeating various parts of the checking and conversion process will probably be required - some trial and error may be necessary.
6. If you removed any LaTeX macro definitions to protect them from expansion in maths elements, replace them now within one or more mdefs elements in the SGML.
7. The routinelist element will have been inserted in the first appendix of the document. If this is not the right place, you may wish to move it.

sgml2docs --html sun321.sgml
sgml2docs --latex sun321.sgml

sgml2hlp routines.sgml > routines.hlp