Next Previous Contents

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 "element", "entities, "attribute", "literal", and delimiter". 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). Note that the tags omitted but they still are implicitly there. In some cases, a tag doesn't enclose anything, like the url tag for a link to the internet. Such tags are themselves elements. 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, the parts of the document that they should have enclosed are still elements for the missing tags.

An entity is like a macro definition. For example, one could define the name "list" to mean the various types of lists. Then this name list is used only in the dtd to specify, for example, that a list may occur within 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. But there's also another type of entity that can be used inside a document and that's one that defines a special character such as amp;etago for </ (end tag open). You would use this when you want to, for example, put </article> in the middle of a sentence to explain what it means so that the software that converts LinuxDoc doesn't think it's really at the end of the article.

8.3 Literals and Delimiters

A "literal" is a name of something, like the name one clicks on in an html link. It may be one or more words long. A delimiter is what separates something from something else. For a "quote" the last " is the closing delimiter. So for name="my website" the literal is 'my website' and the delimiters of this literal are the two " marks, the first " an opening delimiter and second " a closing delimiter. So if a "literal is missing a closing delimiter it means that you neglected to put an ending " after a name.


Next Previous Contents