Previous Next Contents

6. What happens after the document is written?

6.1 What is SGML and how do I use it?

SGML stands for "Standard Generalized Markup Language" and is similar to HTML in many ways. Documents formatted with SGML follow a specific protocol regarding sectioning, sub-sectioning, and moving between sections. The majority of the documents on the Insulin Pumpers Homepage, including this one, are formatted with SGML. Those little arrows to direct you forward and backward through the document are part of the SGML formatting. SGML will automatically create its own table of contents for all of the sections and sub-sections and present it at the beginning of the article.

To prepare a document for SGML markup, the author needs to decide what the major sections are and if there will be any subsections. Articles / FAQs / HowTos on the IP website will always have at least two sections. One of the sections is the standard copyright notice which appears at the end. The "body" of the document can be one section, or broken into two or more. It depends on the complexity of the subject.

In addition, an "abstract" will need to be written. This is the description which appears at the beginning of the article when it is on the web site. It is automatically italicized and encased between two horizontal lines. The abstract should be a brief synopsis of the topics covered in the article.

To learn how to do the SGML markup, download the SGML Tools User's Guide and the Example document into your directory. Here are the specific steps to follow:

  1. Open a ftp connection to by typing "open"
  2. You will be prompted to enter your username and password.
  3. Type "cd /home/sgml/public_html"
  4. Type "ls" to see a list of the files in this directory.
  5. Type "get guide.sgml". This puts the file into your current local directory on your hard drive so that you can play with it. This may be your Windows Desktop or somewhere in your word processor. (To find out what your current local directory is, type "lcd ." (note that is: "lcd {dot}"). The file will show up with all the sgml tags so you can see what they look like. You may consider printing these files (both the guide and the example) so that you can really study the sgml syntax.
  6. Type "get example.sgml"
  7. Type "cd /home/yourname/public_html/howto"
  8. Type "put guide.sgml". This will put the file into your howto directory on the server. From here you will be able to translate it into html so you can see what the document looks like on the net.
  9. Type "put example.sgml"
  10. Open a telnet connection to
  11. Type "cd public_html/howto"
  12. Type "ls" to make sure that the guide and example files are actually there.
  13. Type "sgml2html -I guide.sgml". This converts the user's guide to html so that you can view it on the web with your browser. The "-I" part adds the arrows to navigate through the sections.
  14. Type "sgml2html -I example.sgml".
  15. Minimize the telnet and ftp windows and navigate to your internet browser prompt.
  16. Type "". A list of the files in your howto directory should appear.
  17. Locate the files named guide.html and example.html. These are the main html files which contain the table of contents for each of these files. Note that the sgml2html command created a separate html file for each section of the documents. Open each of the files to see how they look in hypertext. Print the documents out and compare them with the sgml versions of the same documents.

By comparing the sgml and html versions of these files you can learn how to use the sgml tags. You can ignore the part in the guide about downloading the sgml tools. This has already done and the tools are on the Unix server for us to use. The "meat" of the user's guide starts with the section titled "Writing Documents With SGML-Tools". Information on including links to other websites is included in the section titled "Cross References". Once again, viewing both the html and sgml versions of the user's guide will help you understand how this works. Please note that there are some special characters which need a "macro" in order to work in sgml. (A macro will substitute a string of characters for the special character.) The user's guide contains a complete list of these characters and their corresponding macros. Again, if this is overwhelming, there are people on the IP development list who actually enjoy doing SGML markups and will help.

6.2 How do I get my document onto the website?

You can learn to do this yourself, or ask another member to help. It is not difficult, once you know where you are going! An overview of the steps involved follows:

  1. Upload the document via FTP to your howto directory.
  2. Once the document is in your HowTo directory, you can access it through a telnet connection. In telnet, type "cd public_html/howto" to get to your directory.
  3. You can now do any editing you need to with "joe", an on-screen editor. Joe is a little funky to use, but handy for quick fixes. To open the file so that you can edit it with joe, type "joe filename.sgml". To learn how to use joe, refer to editing with joe.
  4. Open a second telnet window so you can check the SGML formatting for bugs. Leave the first telnet window open so that you can edit the document there. In the second telnet window, change to your howto directory again and type "sgmlcheck filename.sgml". Note: Substitute the name of your file for "filename". This check will tell you which specific line(s) have problems with the SGML syntax. Make any necessary corrections (in your first telnet window) and run sgmlcheck again. If you run sgmlcheck and it just comes back with the prompt, congratulations!! You don't have any errors and can proceed to the next step.
  5. After the SGML is bug-free, convert the document to html by typing the following command: "sgml2html -I filename.sgml". This command creates an html file for each section of your document as well as the table of contents.
  6. Now you can go onto the web and take a look at your document. Leave the telnet windows open (minimize them) and go to "" to see what is there. ("yourname" is your user name that you were given when you joined the IP-dev group.) Open the document which is called filename.html. This is the table of contents for your article with the sections and sub-sections highlighted in blue hypertext. Read through your article and test all links to other sites. Make sure that the formatting is how you want it. If you need to make some changes, go back to the telnet window which has the document open and use joe to make changes. If the changes are substantial, you may want to go back to the source file in your word-processor and make the changes there, and upload it via ftp again. If you make any changes, you will need to run the sgmlcheck and sgml2html commands again and ask your browser to "reload" the document.
  7. At this point, you can ask other Ip-dev list members to critique / proofread the document by letting them know where to look for it.
  8. When you are completely satisfied with the article's presentation, think up a "hotlink" name and short description for the website and let Michael know via e-mail. The hotlink is the hypertext which appears on the website so others can access your article.

Previous Next Contents