1. NewbieDoc writer instructions

Jesse Goerz

Revision History
Revision v0.123 March 2001Revised by: jwg
Initial release.

1.1. The Lay of the land

What's in an sgml document? An sgml document in it's most basic form looks terribly similar to an html document. In fact, html is derived from sgml. Below is an example of what a sgml document looks like.

To illustrate a common error I have intentionally made several mistakes in the preceding example. All of the id parameters are of an incorrect format and I used the same "id" name twice. If I tried to "build" this sgml file with an sgml parser it would return an error like this: Which just simply means you can't have spaces or underscores in the name of your "id" attribute, and you need to be careful not to duplicate id names in your document. This may seem trivial right now, but it will be important later so remember this example.

1.2. The hierarchy

Next we have many chapters. The chapters of our book are represented by different types of categories. For instance, because we are writing about Linux we may have a chapter on system administration, networking, text editors, and/or utilities. Each of these chapters would itself contain many sections. For example, the text editors chapter could contain a section on vi, joe, emacs, and/or ed. Putting all these sections in the text editors chapter makes them easy to organize and easy to change if we need to.

Since I didn't go into to much detail earlier, I'm going to cover a little bit more then just the entities. On the first line you have what is known as the DTD or Document Type Declaration. This is just a fancy way of saying what type of document it is. In this case it's a chapter. In the earlier example we looked at a section. Take a minute and compare the two. One thing to take note of is that not only are their names different but the section DTD ends with a ">" right after //EN". The chapter DTD, however, does not end until after all the entities have been declared. Also note that the entities are all inside their own little container; they have a starting bracket and an ending bracket, and only then does the DTD terminate with a ">".

Once the entities are declared in the DTD, think of them as variables holding a pointer or URL link to the file included within them. Now that they are declared you can import the files they point to by invoking them as an entity. This is done by preceding the name of the entity with the "&" (ampersand) and ending it with a ";" semi-colon. Once again, look at the chapter file above to see an example.

Note

It is important that you distinguish the difference between entity declarations and entities. Entity declarations hold the directions to get to a file, but they do absolutely nothing until they are told to. Entities invoked within the document like " &sourceforge-guide; " in the preceding example tell their declarations to import the file into the document right at that point.

1.3. NewbieDoc document conventions

Note

Remember index.sgml in the root of /newbiedoc? That is the cover and table of contents of the book; it is what holds it all together. The administrators use that file to do the book build. Contained inside index.sgml are all the entity declarations.

Even though vi.sgml and joe.sgml's entity names are different (vi and joe respectively) I chose to include their subdirectory names in their entity names as a precaution. Both of these editors are very commonly brought up in howto's and usually have their own section with a link. The name of the link is usually vi or joe. To avoid confusion and a possible conflict we use their subdirectory name along with their filename as the entity name.

As you can see, now that I have appended "-howdy" to the end of the link, it is highly unlikely that when the administrators do a book build and all the section documents are imported into one file to be processed that the links will have conflicts.

1.4. Basic templates

1.5. Adding new documents

New documents should be added to the appropriate chapter subdirectory. Using the previous example, if I added a new section document for emacs it should go into the text-editors directory. I would then add an entity in the text-editors.sgml file pointing to this new file, and an entity declaration in the index.sgml file. Before committing to cvs it is a good idea to "build" the chapter with your sgml parser and make sure everything builds without errors.

Here's a quick checklist:

1.6. Updating your documents

The only thing different about updating your documents versus adding them as new documents is you have to trace down and update all the entities and entity delcarations if you happened to change a filename.