8. Jargon in Error Messages

8.1 Introduction

You really shouldn't need to read this section unless either you're either having problems or you're curious about how sgml and linuxdoc work. Error messages may contain words like "elements", "entities", and "attributes". Various elements, entities and attributes are defined for linuxdoc in the "Data Type Definition" (or dtd) for LinuxDoc. The dtd doesn't define them in sentences but uses a rather cryptic format to define their syntax (but not their semantics).

8.2 Elements

An "element" is something like a tag. But it's a much broader concept. Elements exist not only in linuxdoc but in all sgml languages like say html. Your entire document is partitioned into elements. But elements are nested, which is to say that some elements may occur within other elements. If you use the <article> tag for your document, then all of the document is the <article> element, except for the very first tag which says that what follows is linuxdoc. And within this article element are nested many other elements.

For example, each paragraph is an element, even though the paragraphs are separated from each other by blank lines instead of tags. But there's an implicit tag surrounding each paragraph and the software that parses a linuxdoc writing will actually insert these missing tags. It will also insert end tags (closing tags) where you didn't need to write any. In this way, linuxdoc saves you a lot of time. So an element will consist of a start tag and the end tag (for this start tag) and everything in between (often including other elements and their tags). In some cases, a tag doesn't enclose anything, like the url tag for a link to the internet. Such tags are elements also. Within the article-element are found sect-elements (sections) starting with <sect>. Then within sect-elements are often found sect1-elements (subsections), etc.

There are few cases where an element occurs but the use of both start and end tags are optional. So even if you have no such tags in your document, they may still exist as elements.

8.3 Entities An entity is like a macro definition. For example, one could define aname "list" to mean the various types of lists. Then this name listis used only in the dtd to specify, for example, that a list may occurwithin a paragraph. It's just a shorthand for the writer of a dtd.This kind of an entity is never used in a linuxdoc document. Butthere's also another type of entity that can be used inside adocument and that's one that defines a special character.