| Previous | Contents | Index |
Some additional text has been added to the end of the SDML file to complete the report example.
<front_matter> <title_page> <title>(Dogs and Cats - Together) <running_title>(Dogs and Cats) <running_feet> <abstract> This is a short report about dogs and cats living together. <endabstract> <author>(Sara Cook\Pet Shop Owner\Tins Inn, Maine) <signatures> <byline>(Julian Rose\Editor) <byline>(Jackie Rose\Associate Editor) <p> <p> <p> <date>(January 1, 1995) <endtitle_page> <endfront_matter> <chapter>(Report Summary) <p> This report will tell what it is like to raise dogs and cats together. <p> As a general rule, dogs do not like cats and cats do not like dogs. Dogs tend to chase cats because cats run when they see dogs. Actually, dogs think that cats want to be chased and this is just a game. If a cat does not run, the dog might ignore it. <p> It is possible for dogs and cats to live in harmony. Creating this environment does take some time and lots of patience. <p> <head1>(Topics in This Report) <p> There are several topics that will be discussed in this report. The topics are listed in the following outline. <p> <outline>(Report Topics\Dogs and Cats) <level>(1\Dogs need) <level>(2\This is outline level 2) <level>(3\This is outline level 3) <level>(4\This is outline level 4) <level>(5\This is outline level 5) <level>(6\This is outline level 6) <level>(1\Cats need) <level>(2\Feeding) <level>(3\A good cat food; canned or dry) <level>(3\Water) <level>(3\Grass or lettuce) <level>(3\Cat treats) <level>(2\Care) <show_levels>(bold) <level>(3\Shelter) <level>(3\Litter box) <show_levels>(off) <level>(2\Toys) <show_levels>(italic) <level>(3\Scratching post) <level>(3\Toys containing catnip) <level>(3\Toys with bells) <level>(3\Paper bag) <show_levels>(off) <level>(2\Training) <endoutline> <head1>(Kittens and Puppies) <p> Very young kittens and puppies get along well because neither has had any bad experiences with the other. <p> Kittens can co-exist with grown dogs. After a day or two of checking each other out, they get to know each other and get along just fine. <p> Puppies can co-exist with grown cats. Cats tend to stand off a bit and ignore puppies. But puppies are playful and very often the cats come to enjoy having playmates. |
The SAMPLE_REPORT.SDML file is completed and ready for DECdocument to process.
When you create a report, you need to specify the REPORT or REPORT.TWOCOL doctype.
You can create a PS, TXT or TERM output file. The commands are:
The processed sample reports appear on the next pages. The first output example will show the results using the REPORT doctype. The second example will show the results using the REPORT.TWOCOL doctype.
There are a number of other tags that can be used for reports. The "Using the Report Doctype" section in the Using Doctypes and Related Tags manual gives examples of reports and describes all the report tags that you can use.
This manual has shown you how to get started using DECdocument. You have learned that the tags in your SDML text file and the command line tell DECdocument what you want done. You have become acquainted with many of the commonly used tags so you can create formatted documents. With this knowledge you can easily learn how to use the other features that DECdocument has available.
This chapter will describe some of the other DECdocument features. It will tell about online help, book profiles, other DOCUMENT qualifiers, how to make a glossary and provide information on some of the other tags.
11.1 Online Help is Available
You can get online help for DECdocument. To get help, enter
HELP DOCUMENT at the $ prompt.
The following screen will be displayed:
DOCUMENT
Invokes the DECdocument document production system that lets you
create documents in many different formats for a variety of output
devices.
Additional information available:
Parameters Description Qualifiers
/BATCH /CONDITION /CONTENTS /DEVICE_CONVERTER /DIAGNOSTICS
/ELEMENT /INCLUDE /INDEX /KEEP /LIST /LOG /MAP
/MASTER_INDEX /OUTPUT /PRINT /PROFILE /SYMBOLS
/TAG_TRANSLATOR /TEXT_FORMATTER
/GENERATE_SYMBOL /FORMATTER Release_Notes Global_Tags
Doctypes_and_Related_Tags /GRAPHICS
DOCUMENT Subtopic? GLOBAL_TAGS
|
There are a number of topics that you can get information on. For example, if you want information on global tags, you can enter GLOBAL_TAGS at the DOCUMENT Subtopic? prompt and the global tags screen will be displayed.
DOCUMENT
Global_Tags
The following is a list of all the global tags.
Additional information available:
<ABSTRACT> <ACCENT> <ALIGN_AFTER> <ALIGN_CHAR>
<ALIGN_NUMBER> <AMPERSAND> <APPENDIX> <BACKSLASH>
<BOX> <CALLOUT> <CALLOUT_REF> <CALLOUTS> <CENTER_LINE>
<CHAPTER> <CHEAD> <CHECK_FOR_INCLUSION> <CO> <CODE_EXAMPLE>
<COMMENT> <CONDITION> <CONTENTS_FILE> <COPYRIGHT_DATE>
<COPYRIGHT_PAGE> <CP> <CPAREN> <DATE> <DEFINE_BOOK_NAME>
<DEFINE_SYMBOL> <DEFINITION_LIST> <DEFINITION_LIST_HEAD>
<DEFLIST_DEF> <DEFLIST_ITEM> <DELAYED> <DOCTYPE>
Press RETURN to continue ...
|
You can press [Return] and see all the global tags listed. If you want information on a specific tag, you can enter that tag at the DOCUMENT Global_Tags Subtopic? prompt. For example, if you enter <DATE> to get information on dates, the date screen will be displayed.
DOCUMENT
Global_Tags
<DATE>
Format
{ FULL }
<DATE>[( { date text })]
{ }
DOCUMENT Global_Tags Subtopic?
|
You can enter another tag if you want more information.
To exit out of the Document Help Facility, keep pressing [Return] until you are back at the $ prompt.
11.2 Book Elements and Profile SDML Files
In Chapter 7 you created a short manual. If you were to create a
manual with many large chapters, you might want to break the SDML file
into smaller SDML files. For example, you could have an SDML file for
the front matter, SDML files for each of the chapters and SDML files
for each of the appendix sections and glossary (if you have one).
When you do this, you have created book elements. Each of the
separate SDML files is a book element.
When you want to put your book together, you use a profile
SDML file. The profile SDML file contains a list of the book elements.
The book elements are the separate SDML files that make up the book.
When you create a profile SDML file, you use the <PROFILE> tags
and the <ELEMENT> tag. The tag formats are:
<PROFILE>
book elements
<ENDPROFILE>
A profile SDML file contains:
The following example shows the profile SDML file, APP_PROFILE.SDML, that was used to create this manual (book).
<profile> <element>(app_front.sdml) <comment>(***includes table of contents***) <element>(app_overview.sdml) <comment>(Chapter 1 - overview info) <element>(app_tags.sdml) <comment>(Chapter 2 - tag info) <element>(app_using_tags.sdml) <comment>(Chapter 3 - using tags) <element>(app_dogs.sdml) <comment>(Chapter 4 - sample doc file) <element>(app_more_tags.sdml) <comment>(Chapter 5 - more tags) <element>(app_center_tags.sdml) <comment>(Chapter 6 - centering tags) <element>(app_manual.sdml) <comment>(Chapter 7 - create manual) <element>(app_letter.sdml) <comment>(Chapter 8 - create letter) <element>(app_article.sdml) <comment>(Chapter 9 - create article) <element>(app_report.sdml) <comment>(Chapter 10 - create report) <element>(app_misc_info.sdml) <comment>(Chapter 11 - general info) <element>(app_errors.sdml) <comment>(Appendix A) <element>(app_ref_manuals.sdml) <comment>(Appendix B) <element>(app_glossary.sdml) <index_file> <endprofile> |
Notice that the <INDEX_FILE> tag has been placed in the profile SDML file instead of in one of the element SDML files. This way you know that you have included it (if you want an index).
There are three requirements when you build a book using a profile SDML file. These requirements are:
When you are ready for DECdocument to build the book, you use the document command just as you did for a single SDML file. To process a profile file called SAMPLE_PROFILE.SDML, the commands to create a PS, TXT or TERM output file are:
In this case, the output files will be called SAMPLE_PROFILE.PS, SAMPLE_PROFILE.TXT or SAMPLE_PROFILE.TERM.
Creating separate SDML files as book elements and using a profile SDML file is very useful when you are not sure how you want to arrange your manual. This allows you to move chapters around as you want.
11.3 Including Files
If you have some text that is repeated numerous times throughout your
SDML file(s), you can put the text in a separate SDML file and use the
<INCLUDE> tag to include it wherever you want in the other SDML
file(s). The format is:
<INCLUDE>(file_name.SDML)
You can INCLUDE SDML files in other SDML files and in profile SDML files.
The Using Global Tags manual contains detailed information on the <INCLUDE> tag and how it can be used.
11.4 Other DOCUMENT Command Qualifiers
In previous chapters, you learned how to use the /contents and
/index DOCUMENT command qualifiers to create a table of
contents and an index. There are other qualifiers that you can use to
cause DECdocument to perform specific procedures. Here are some of
the other qualifiers:
You can use as many qualifiers as are appropriate. There are times when you would use no qualifiers. There are other times when you might want to use several qualifiers.
The Command Summary and Processing Messages manual provides information on all the command qualifiers and how they are used.
11.4.1 /LIST Qualifier
The /list qualifier will create a file which contains
the DECdocument processing informational messages and error messages,
if there were any errors during processing. The file has the extension
of LIS (i.e. SAMPLE_MANUAL.LIS, SAMPLE_PROFILE.LIS).
See Appendix Section A.2, Creating a LIS File for more information on list files.
11.4.2 /OUTPUT Qualifier
If you want to give the destination file (i.e. PS file) a specific name
or locate it in a different directory, you can use the
/output qualifier with a file specification. Here are
two examples.
This command:
document sample_doc.sdml general ps/output=test_doc
will create TEST_DOC.PS as the output file.
This command:
document sample_doc.sdml general ps/output=user:[ps_files]sample_doc
will create SAMPLE_DOC.PS and place the file in the USER:[PS_FILES] directory.
11.4.3 /CONDITION Qualifier
If you have a situation where you are creating the same document for
several people and you would like the document to contain some specific
text for each person, you can use the /CONDITION
qualifier and the <CONDITION> tags to achieve this.
Let us say that you want to send a letter to Sandy and a letter to Tony. The text of the letter will be the same but you want their names in each of the letters.
To start with, in your SDML file, you will use the <CONDITION>
tags. The format is:
<CONDITION>(condition)
Text to use if the condition is set on
<ENDCONDITION>
Here is how you would use the <CONDITION> tags in your SDML file:
<condition>(sandy) <p> Dear Sandy, <p> How is the weather in Florida? <endcondition> <condition>(tony) <p> Dear Tony, <p> How is the weather in Alaska? <endcondition> |
When you want to create Sandy's letter, you would use this command with
the /CONDITION qualifier:
document my_letter.sdml letter ps/condition=sandy
When you want to create Tony's letter, you would use this command:
document my_letter.sdml letter ps/condition=tony
You can refer to the Using Global Tags manual for information on how to use multiple conditions.
11.4.4 /SYMBOLS Qualifier
In a previous chapter you learned how to use the <DEFINE_SYMBOL>
tag. There is another tag that you can use for books. This is
the <DEFINE_BOOK_NAME> tag. When you use the <REFERENCE>
tag to reference a book name, the book name will be printed in
italic.
If you have lots of text and/or books to define, you can create a symbol SDML file (i.e. MY_SYMBOL_DEF.SDML). The symbol file should only contain symbols defined with the <DEFINE_SYMBOL> and <DEFINE_BOOK_NAME> tags.
If you use a symbol file, you need to tell DECdocument about this
file when you issue the DOCUMENT command. To do this, you use the
/symbols qualifier. Here is the command you would use:
document myfile.sdml general ps/symbols=my_symbol_def.sdml
11.4.5 One Use for the /DEVICE Qualifier
There is one other qualifier that might be useful when you are creating
manuals and books. This is the /device qualifier.
If you are creating a 2-sided (front and back of a page) manual or book, you want the first page of the table of contents, preface, chapters, appendices, glossary and index to start on the right side. That is, when you open your 2-sided manual, all the even numbered pages will be on the left and the odd numbered pages will be on the right.
Since a chapter might end on an odd numbered page, you need to insert a
blank page to make the next odd numbered page fall in the right place.
When you are creating the final copy of your manual or book, you can
use the /device qualifier to create blank pages so the page numbers
come out correctly. To do this, you use this command:
document myfile.sdml general ps/device=blank
11.5 Creating a Glossary
A glossary contains a list of terms and definitions.
The terms are normally in alphabetical order. To create a glossary, you
use several tags. These tags are:
<GLOSSARY>
<GTERM>(term text)
<GDEF>(definition text)
<GREF>(glossary cross-referenced term)
<ENDGLOSSARY>
The following example shows a small glossary.
<glossary>(Glossary\my_glossary)
<gterm>(animal)
<gdef> A four-legged critter.
<gterm>(cat)
<gdef> A small four-legged critter with a long tail that meows.
See <gref>(animal).
<gterm>(dog)
<gdef> A four-legged critter with a short or long tail that barks.
See <gref>(animal).
<endglossary>
|
Normally a glossary is given the name "Glossary" and a symbol name. If
you want to call it something else, you can provide a different name in
parentheses following the <GLOSSARY> tag. For example:
<glossary>(My List of Terms\my_glossary)
You can refer to the glossary in this manual for an example of PS output.
| Previous | Next | Contents | Index |