3.2. Adding a new webpage to an existing site

3.2. Adding a new webpage to an existing site
Prev	3. Content creation and modification	Next

There are two ways in which a file can be added to an existing site.

By inserting an XML file into the existing structure - by which means the file becomes an integral part of the Website
By adding an external file of some description. It may be considered part of the site, but from the Website perspective, it is not integral to it.

Each of these will be considered

3.2.1. Adding an xml file to the Website, using the `layout.xml` file

As shown earlier, the heart of the layout of a Website is the layout.xml file. For the examples used here it is repeated below, Example 2.

Example 2. Adding xml files using layout.xml

<layout xmlns="http://docbook.org/ns/docbook">
  <toc page="maketea.xml" filename="index.html">              
    <tocentry dir="prepare" page="prep.xml" filename="prepare.html">   
      <tocentry page="ing.xml" filename="ingredients.html"/>
      <tocentry page="teapot.xml" filename="teapot.html"/>
      <tocentry page="prep.k.xml" filename="prep.kettle.html"/>           
    </tocentry>
    <tocentry page="proc.xml" dir="procedure" filename="procedure.html">                     
      <tocentry page="proc.k.xml" filename="proc.kettle.html"/>
      <tocentry page="brew.xml" filename="brew.html"/>  
      <tocentry page="pour.xml" filename="serve.html"/>                           
    </tocentry>
  </toc>
</layout>

This is the area of interest in the layout.xml file

As an example of adding a deeper structure and more xml files, assume that the brew.xml content (How to brew tea) suddenly became oh so very complex! We now wish to detail how it is done in India and China. The decision is made that a small section is needed, with a few introductory paragraphs and two further files, one each describing brewing tea in India and China (brew.india.xml and brew.china.xml).

The change to the layout file is as follows:

Add a dir attribute to the file which will become a section start (tocentry page="brew.xml"
Insert new tocentry elements within the updated tocentry> element (for both brew.india.xml and brew.china.xml)
Create the two new files
Rebuild the Website

Simple as that! Well, not quite. Firstly the modified layout.xml file. This is shown in Example 3

Example 3. The updated layout file

<layout xmlns="http://docbook.org/ns/docbook">
  <toc page="maketea.xml" filename="index.html">              
    <tocentry dir="prepare" page="prep.xml" filename="prepare.html">   
      <tocentry page="ing.xml" filename="ingredients.html"/>
      <tocentry page="teapot.xml" filename="teapot.html"/>
      <tocentry page="prep.k.xml" filename="prep.kettle.html"/>           
    </tocentry>
    <tocentry page="proc.xml" dir="procedure" filename="procedure.html">                     
      <tocentry page="proc.k.xml" filename="proc.kettle.html"/>
      <tocentry dir="brew" page="brew.xml" filename="index.html">  
        <tocentry page="brew.india.xml" filename="india.html"/>    
	<tocentry page="brew.china.xml" filename="china.html"/>
      </tocentry>
      <tocentry page="pour.xml" filename="serve.html"/>                           
    </tocentry>
  </toc>
</layout>

	brew/brew.xml becomes the section heading, containing the two new files
	The two new files are referenced in the new section

Section 5.4discusses it further but for now I want to introduce the role that file id values play in Website. At the top level each Website file contains a root element which looks something like Example 4. The omitted content is all valid to the Website dtd.

Example 4. A new Website page, (brew.india.xml)showing a basic outline

  
<?xml version="1.0" encoding="iso-8859-1" ?>


<webpage navto="yes" xml:id="brew.india"
   xmlns="http://docbook.org/ns/docbook">                
<head>
<title>Brewing tea </title>                        
<summary>Brewing tea in India</summary>
  <keywords>tea, brewing, india, India</keywords>   
</head>

<section>
<title> ...  </title>
<para> ... </para>


</section>
</webpage>

Note that the xml:id value is identical to the filename, without the xml extension

Also that the example uses xml:id (rather than id)

This (for these examples) provides the link between the xml filename and the xml:id within the file itself. Given brief filenames, they can be used as the file id value. From now on I shall use id rather than the longer xml:id

This is a very convenient convention - not a requirement. It helps in relating html files back to the xml file.

It also ensures that file id values are unique! Hopefully, if your filenames clash, your editor may warn you. If id values clash, that is a rather more subtle error

The simplicity of this linkage makes it easy to determine which file requires modifying. The flaw in this system is that it is more normal to view the html version, from which it is necessary to determine the xml filename, which is what is modified. If this can be done (the example shows that it can be difficult), then a simple sequence shows which file to modify.

View the html files. Find the one to modify.
From the html filename, deduce the xml file to modify.

The constraint on using brief names for the xml filename is there simply to allow the id value on the webpage element. The id values must be unique to the site and if they reflect the xml files then there is a good chance that they will be. This level of simplicity reduces the workload when maintaining a site over a number of years

	Note
	A final note to reduce work. If you keep a file such as that shown in Example 4 as a template, (without the actual content), you can re-use it repeatedly, by modifying the `id` value and the titles, each time you want to create a new page! Saves having to re-create it all the time. Such a file is part of the example in Section 8 - see topic.xml

3.2.2. Adding an external non-xml file to a Website

It may be that the Website discusses some software and provides an example. This could be a plain text file, a Microsoft Word document or even another html file. When this is the case, all that is needed is a way of linking from an existing xml file (which is a part of the Website) to the external file.

	Links to non html targets
It is a courtesy to the reader to warn her if the target of a link is other than html. Consider if the link is to a Microsoft Word document, or a Powerpoint presentation, an SVG animated graphic or a spreadsheet. You need to be confident that your reader and their installed software can process the filetype. This is not possible with any confidence on a site on the internet. Such a warning could be an addition to the link, e.g. specify the link, then add text indicating the filetype. E.g. link text - PDF file, 200Kb. This provides the information the reader needs to decide if they wish to follow the link

Links to non html targets

It is a courtesy to the reader to warn her if the target of a link is other than html. Consider if the link is to a Microsoft Word document, or a Powerpoint presentation, an SVG animated graphic or a spreadsheet. You need to be confident that your reader and their installed software can process the filetype. This is not possible with any confidence on a site on the internet.

Such a warning could be an addition to the link, e.g. specify the link, then add text indicating the filetype. E.g. link text - PDF file, 200Kb. This provides the information the reader needs to decide if they wish to follow the link

For Website, as with Docbook, there are a number of ways of linking to an external file. For example,

<para>  Please see  <link xlink:href="downloads/mypdfFile.pdf">this file</link> (A PDF file, 200kb) </para>

Since the file is not a part of (the xml version) of the Website, the internal linking system cannot be used, hence the use of the link element (tdg description ) is used.