5.3 Organising files

I described above how, for example, the Fortran-code DTD can allow you to mix program source code and SGML markup. A Fortran source file cannot be a complete SGML document on its own, however, even though it can be a fragment of a valid document, since there is no way to hide the required <!DOCTYPE ...> declaration from the compiler. The source file must therefore be part of a composite document.

Although the object that is pointed to by the General DTD's codecollection element is a single SGML document marked up using the programcode DTD, it need not be a single file. A suitable way to manage a collection of source code files, for documentation purposes, might be as follows.

We can return to the example in Section 5.1.1, and split our `hello world' example into two files, a skeleton file holding the general structure, and including an entity which refers to the source code:

<!DOCTYPE programcode PUBLIC "-//Starlink//DTD Fortran Source Code 0.7//EN" [
  <!ENTITY ptest-source SYSTEM 'ptest.f'>
]>
<title>The `hello world' program
<codegroup>
<title>Group title
<description>First test program
<routine>
<codeopener>
&ptest-source;

      subroutine helloworld (language)
*+
*   <routinename id=hi1>
*     helloworld
*   <description>
*     Greets the world with a sunny hello
*   <argumentlist>
*   <parameter given>
*     language = _integer
*     Selects the language to use.
*     0=english, 1=sanskrit.
*   <authorlist>
*   <author id=ng affiliation='Glasgow'>Norman Gray
*-
      write (*,*) 'ack!'
      end