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:
"open home.bzs.org""cd /home/sgml/public_html""ls" to see a list of the files in this directory."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."get example.sgml""cd /home/yourname/public_html/howto""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."put example.sgml""cd public_html/howto""ls" to make sure that the guide and example files are actually there."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."sgml2html -I example.sgml"."http://www.bzs.org/~yourname/howto". A list of the files in your
howto directory should appear.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.
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:
"cd public_html/howto" to get to your directory.
"joe filename.sgml". To learn how to use joe, refer to
editing with joe.
"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.
"sgml2html -I filename.sgml". This command creates an html file for each section of your
document as well as the table of contents.
"http://bzs.org/~yourname/howto" 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.