If presented with subroutine or command descriptions in a SUN then latex2sgml will turn them into SGML like the rest of the text in the document. However, it will not make a very pretty job of it; the proper way is to mark these up using the Programcode DTD, and reference the resulting document via a codecollection element in the main document, as described in Section 5.
If the corresponding source files are written with prologues
in the normal Starlink style, then a source code upconverter,
code2sgml,
is provided which
can mark these up as SGML conforming to the Programcode DTD.
It can behave in different ways according to how you wish to
organise the files - it can either produce a set of files
which are still the same compilable source code as before but can
also be included directly into an SGML document,
or it can produce a document containing just the marked up prologues
to be included. Which it does is controlled by the -d
and -D flags.
To invoke the source code upconverter in the simplest instance, simply type
and you will see what the marked up source code looks like. The form of the prologue is kept as closely as possible to its original format, and all the SGML markup is guaranteed to be hidden from the compiler in comments (in the very rare case that this is not possible the upconverter will exit with a fatal error). By default, only comment lines between the `code2sgml file.f
*+' and `*-',
one comment line immediately after that, and a comment line at the
end of the file (or before the next prologue) are changed in any way.
If the -1 flag is given, then only the first prologue
in a given file is marked up.To make actual use of the marked up prologues you must turn them somehow into a full SGML document. This can be done in two ways. The command:
will make a single monolithic SGML document containing the marked up prologues, though not the body of the code from the files in question. The original files are left untouched. Alternatively, you can docode2sgml -D x.f y.f z.f > converted/routines.sgml
The first three lines write new versions of the given source files into a new directory, and the last line writes a container SGML document which has a minimum of necessary heading and footing, and includes the named files by reference. The new source files will look exactly the same to the Fortran compiler (only comment lines have changed), and may if desired be used as the new primary copies of the source code.code2sgml x.f > converted/x.f code2sgml y.f > converted/y.f code2sgml z.f > converted/z.f code2sgml -d x.f y.f z.f > converted/routines.sgml
Either way, you now have a Programcode document which can be
included in a codecollection element
in an SGML SUN.
The individual routines can then be referenced from the main document
using the coderef element;
a document (in directory converted)
in which this was done might contain the following
excerpts:
<!DOCTYPE sun PUBLIC "-//Starlink//DTD Starlink SUN//EN" [
<!ENTITY routine.documentation SYSTEM 'routines.sgml'>
]>
...
See description of <coderef id=x collection=xyz>routine x</coderef> ...
...
<routinelist><codecollection doc=routine.documentation id=xyz>Where the original prologues follow the normal Starlink (SST) conventions for comment formatting, conversion is usually quite good and the output may not need much further attention to make it into final SGML for document production. However, it may not be possible to infer the logical structure of the text by looking at its physical form, so it is always a good idea to look at the SGML output of the program. If there are consistent usages in the original which are not being understood by the converter it may be worth setting up and experimenting with a configuration file as explained in the code2sgml documentation. To a limited extent this can enable the converter to work with source files using different conventions for comment syntax, header titles, list format, and so on.