| Previous | Contents | Index |
There are some things to keep in mind when you create index entries.
the most important thing is to place the index entries so the topics can be CORRECTLY LOCATED. If an entry is placed incorrectly, the topic will not be on the page shown in the index. |
To achieve proper positioning of index entry tags in the SDML file:
<p>
<x>(Dogs)
Learning about dogs is interesting...
<x>(Cats)
Learning about cats is interesting...
<x>(Horses)
Learning about horses is interesting...
etc...
|
<chapter>(Creating an SDML file)
<x>(SDML file)
<x>(Creating SDML files)
<p>
To create an SDML file...
<head1>(Learning to Write Documentation)
<x>(Writing documentation)
<x>(Learning to write)
<p>
Writing documentation is...
|
<list>(numbered)
<x>(Dogs)
<le> List of dogs...
<x>(Cats)
<le> List of cats...
etc...
<table>(Animal Table)
<table_setup>(2\10)
<x>(Animal table)
<table_heads>(Type\Number)
<x>(Domestic animals)
<table_row>(Domestic\text...)
or
<table_row>(Domestic<x>(Domestic animals)\text...)
etc...
|
To learn more about index tags and placement, you can refer to the Using Global Tags and Producing Online and Printed Documentation manuals.
7.5.2 Index Entries in the Sample Manual
We are now going to edit the SAMPLE_MANUAL.SDML file and
<front_matter>
<title_page>
<comment>(*****************************************************)
<comment>(****** I n s e r t T i t l e h e r e *********)
<comment>(*****************************************************)
<title>(This is Our\Sample Manual)
<abstract>
This document shows the parts and elements of a manual.
<endabstract>
<endtitle_page>
<copyright_page>
<print_date>(January 1995)
<p>
This is the copyright page for the sample manual.
<p>
<copyright_date>(1995 ABC Company, Inc.)
<endcopyright_page>
<comment>(***** The table of contents prints here ****)
<contents_file>
<comment>(*****************************************************)
<comment>(****** S t a r t P r e f a c e h e r e *******)
<comment>(*****************************************************)
<preface>(7) <comment>( be sure to check page number )
<p>
<head>(Purpose)
<p>
The purpose of this document is to show what parts a manual contains.
<p>
<head>(Intended Audience)
<p>
This document is intended for new users who are learning how to use
DECdocument.
<endpreface>
<endfront_matter>
<comment>(*****************************************************)
<comment>(****** S t a r t c h a p t e r s h e r e ******)
<comment>(*****************************************************)
<chapter>(Body of a Manual)
<x>(Body of a manual)
<x>(Manual body)
<p>
The main part of a manual is the body. The body consists of one or more
<x>(Chapters in body)
chapters. The chapters can contain paragraphs of text, tables, lists,
examples, etc. You can have as many chapters as you want to include.
<chapter>(Sample Chapter - Dogs\sample_doc_chap)
<x>(Dogs)
<head1>(Dog Groups and Breeds)
<x>(Dog groups and breeds)
<p>
There are many <emphasis>(groups\bold) of dogs. Each group type will
perform a different specialized task. One group is used for herding, one
is used for hunting, another is used for searching and so on. Within each
group, there are numerous <emphasis>(breeds\italic) of dogs. For example,
<x>(Hunting group)
in the hunting group, there are
<sample_text>
<list>(numbered)
<x>(Labrador Retrievers)
<le> Labrador Retrievers
<list>(unnumbered)
<le> Black in color
<le> Chocolate in color
<le> Yellow in color
<endlist>
<x>(Golden Retrievers)
<le> Golden Retrievers
<x>(Pointers)
<le> Pointers
<le> etc.
<endlist>
<endsample_text>
<p>
<head2>(Selecting a Dog\select_dog)
<x>(Selecting a dog)
<x>(Family pet)
<x>(Bonding)
<p>
<emphasis>(Before you get a dog), you should consider what type of dog you want and
what the dog will be used for. If you just want a family pet, some breeds
are better than others. Some breeds tend to bond to only one person while
others will bond to all family members. <underline>(Selecting the right
breed of dog is very important.)
<p>
<table>(Dog Sizes and Weights)
<table_setup>(3\6\12)
<table_heads>(Size\Weight\Example)
<x>(Dogs<xsubentry>Size)
<x>(Dogs<xsubentry>Weight)
<x>(Dogs<xsubentry>Examples)
<table_row>(tiny\1-15 lbs\Chihuahua<line>Toy Poodle)
<table_row>(small\15-30 lbs\Cocker Spaniel<line>Boston Terrier)
<table_row>(medium\30-60 lbs\Irish Setter<line>Collie)
<table_row>(large\60-100 lbs\German Shepherd<line>Retrievers)
<table_row>(giant\over 100 lbs\Great Dane<line>St. Bernard)
<endtable>
<line>(indent\4\bigskip)
Dogs come in all shapes and sizes.
<example>(Dog Picture)
<x>(Picture of a dog)
<x>(Dog picture)
<code_example>(keep)
D O G |
|
V
@____/\
| ^ | \
|______| /
|-------------
/ \
\ /
-------------
/ \ / \
_/ _/ _/ _/
<endcode_example>
<endexample>
<note>
<x>(Best friends)
Dogs can be best friends.
<endnote>
<comment>(*****************************************************)
<comment>(****** S t a r t a p p e n d i x h e r e ******)
<comment>(*****************************************************)
<appendix>(User Notes)
<x>(User notes)
<p>
This page can be used for notes.
<endappendix>
<index_file>
|
We will now create the sample manual.
The following command is used to process the SAMPLE_MANUAL.SDML file and create a PS output file which can be printed on a PostScript printer. The output file will be called SAMPLE_MANUAL.PS.
When we give DECdocument the command to process the SDML file, we need to tell DECdocument that we want a table of contents and an index. To do this, we will add qualifiers to the end of the command. The qualifiers are prefixed with a "/" slash and they are /contents and /index. Here is the command:
If you want to create a file that you can type out at your terminal or print out on a line printer, you can specify the MAIL or TERM destination. For example:
If MAIL is used, the output file will be SAMPLE_MANUAL.TXT. If TERM is used, the output file will be SAMPLE_MANUAL.TERM.
The pages following are what the completed sample manual looks like.
Often, it is desirable to set up an SDML file skeleton so users have a starting point and can fill in the blanks. That way, all manuals will have the same basic format and output appearance.
DECdocument allows you to create letters and memos. When you create a letter or memo, you can use most of the tags previously described and also some specific letter tags.
This chapter will describe some of the letter tags and how to create a letter. The example file we will use will be called SAMPLE_LETTER.SDML.
8.1 Sender Address <FROM_ADDRESS> Tag
The first thing we want on our letter is the sender's name and address.
DECdocument uses the <FROM_ADDRESS> tag to identify this
information. The sender text will be placed at the top of the page on
the right side. You can have a maximum of five text lines. The text
lines are enclosed in parentheses and separated by the backslash "\".
The format is:
<FROM_ADDRESS>(address line 1\address line 2\etc. . .)
<from_address>(Molly Smith\1234 S. Main Street\Valleyview, Ohio 34567) |
There are two options you can use for the letter date. You can use the <DATE> tag which will place the current system date or the date you supply in your letter. You can also use the <MEMO_DATE> tag where you supply the date.
You can refer to Section 5.4, The<DATE> Tag, which describes date tag usage.
The <MEMO_DATE> tag prefixes the date with the word "Date:" in
bold type and this would not be desirable for some letter types (i.e.
business letters). The format for the memo date tag is:
<MEMO_DATE>(memo or letter date)
This example:
<MEMO_DATE>(January 1, 1995)
Produces:
Date: January 1, 1995
We are going to use the <DATE> tag in our letter with some <P> tags for spacing because this is a business letter.
<from_address>(Molly Smith\1234 S. Main Street\Valleyview, Ohio 34567) <p> <p> <date>(January 1, 1995) <p> |
We now want to add the name and address of the person we are sending
the letter to. The <TO_ADDRESS> tag is used for this. This tag
works like the <FROM_ADDRESS> tag. The "to" text will be placed
at the left margin. You can have a maximum of five text lines. The text
lines are enclosed in parentheses and separated by the backslash "\".
The format is:
<TO_ADDRESS>(address line 1\address line 2\etc. . .)
<from_address>(Molly Smith\1234 S. Main Street\Valleyview, Ohio 34567) <p> <p> <date>(January 1, 1995) <p> <to_address>(Sam Jones\4321 6th Street\Sunnytown, Nebraska 43210) |
You can use whatever salutation text is appropriate for the particular
letter. The <SALUTATION> tag is used for the salutation text. The
format is:
<SALUTATION>(text)
<from_address>(Molly Smith\1234 S. Main Street\Valleyview, Ohio 34567) <p> <p> <date>(January 1, 1995) <p> <to_address>(Sam Jones\4321 6th Street\Sunnytown, Nebraska 43210) <salutation>(Dear Mr. Jones:) |
You can use the global DECdocument tags in the body of your letter. We will add some text to our letter sample.
<from_address>(Molly Smith\1234 S. Main Street\Valleyview, Ohio 34567) <p> <p> <date>(January 1, 1995) <p> <to_address>(Sam Jones\4321 6th Street\Sunnytown, Nebraska 43210) <salutation>(Dear Mr. Jones:) <chead>(RE: Order Number ABC-6565) <p> Would you please double my order for dog biscuits and dog bones. I have just acquired two more large dogs and a puppy and will be needing these supplies. <p> Please add the "Training Puppies" book, item number TP-435, to my order. <p> Thank you very much for changing my order. I am looking forward to the arrival of the products. |
The <CLOSING> tag is used for the closing. The closing text will
be placed at the bottom of the page on the right side. You can have a
maximum of five text lines. The text lines are enclosed in parentheses
and separated by the backslash "\". The format is:
<CLOSING>(text line 1\text line 2\etc...)
<from_address>(Molly Smith\1234 S. Main Street\Valleyview, Ohio 34567) <p> <p> <date>(January 1, 1995) <p> <to_address>(Sam Jones\4321 6th Street\Sunnytown, Nebraska 43210) <salutation>(Dear Mr. Jones:) <chead>(RE: Order Number ABC-6565) <p> Would you please double my order for dog biscuits and dog bones. I have just acquired two more large dogs and a puppy and will be needing these supplies. <p> Please add the "Training Puppies" book, item number TP-435, to my order. <p> Thank you very much for changing my order. I am looking forward to the arrival of the products. <closing>(Sincerely,\Molly Smith\Dog Breeder) |
If you want to send a copy to someone, you can use the <CC> tag.
If you want to send several copies to various individuals, you can use
the <CCLIST> tag. The copy name or list will be placed at the
bottom of the page on the left side. The formats are:
<CC>(receiver text)
and
<CCLIST>
<CC>(receiver text 1)
<CC>(receiver text 2)
<CC>(receiver text 3)
<ENDCCLIST>
<from_address>(Molly Smith\1234 S. Main Street\Valleyview, Ohio 34567) <p> <p> <date>(January 1, 1995) <p> <to_address>(Sam Jones\4321 6th Street\Sunnytown, Nebraska 43210) <salutation>(Dear Mr. Jones:) <chead>(RE: Order Number ABC-6565) <p> Would you please double my order for dog biscuits and dog bones. I have just acquired two more large dogs and a puppy and will be needing these supplies. <p> Please add the "Training Puppies" book, item number TP-435, to my order. <p> Thank you very much for changing my order. I am looking forward to the arrival of the products. <closing>(Sincerely,\Molly Smith\Dog Breeder) <cc>(Purchase folder) |
Our SAMPLE_LETTER.SDML file is completed and DECdocument can now process the file.
When you create a letter or memo, you need to use a different doctype. The doctype you will use is LETTER.
You can create a PS, TXT or TERM output file. The commands are:
The sample letter will appear as shown on the next page.
There are other tags that can be used for letters and memos. The "Using the Letter Doctype" section in the Using Doctypes and Related Tags manual gives an example of a letter and a memo and describes all the letter and memo tags that are available.
With DECdocument, you can create articles. When creating articles, you can use most of the global tags and also some specific tags used for articles.
This chapter will describe some of the article tags and how to create an article. The example file we will use will be called SAMPLE_ARTICLE.SDML.
The article we are going to write will be 2-columned and the first line of the paragraphs will be indented.
9.1 The Title Section
When you create an article, you start with the title section.
The title section contains the name of the article and sometimes a
summary line. This is similar to a manual except that you have a title
section instead of a title page.
The title section contains the following tags:
<TITLE_SECTION>
<TITLE>(title text)
<SUBTITLE>(subtitle text)
<ENDTITLE_SECTION>
The <TITLE_SECTION> and <ENDTITLE_SECTION> tags identify the title section. These two tags are used specifically for articles. That is, they cannot be used for any other doctype.
The <TITLE> and <SUBTITLE> tags identify the title and subtitle, if there is one. These tags can be used with some other doctypes.
We will start the SAMPLE_ARTICLE.SDML file with the title text.
<title_section> <title>(Country Living) <subtitle>(Where Every Day is an Adventure) <endtitle_section> |
You can have what is called running titles and running feet in your article. Running titles are one or two lines of text that appear at the top of the pages in the article. Running feet is a single line of text that appears, with the page number, at the bottom of the article pages.
The formats for the running title and feet tags are:
<RUNNING_TITLE>(top line of text)
or
<RUNNING_TITLE>(top line of text 1\top line of text 2)
<RUNNING_FEET>(bottom line text)
These two tags can be used with some of the other doctypes.
<title_section> <title>(Country Living) <subtitle>(Where Every Day is an Adventure) <endtitle_section> <running_title>(Life in the Country) <running_feet>(Country Life) |
You can put author information in an article by using the author tags. There are several tags that can be used. These tags can ONLY be used with the ARTICLE doctype.
The <AUTHOR> tag is used for the author's name. You can also
append some optional information using the "\" backslash to the author
name text. NOTE: There is another form of the <AUTHOR> tag that
can be used with other doctypes.
<AUTHOR>(author name)
or
<AUTHOR>(author name\optional information)
The <AUTHOR_AFF> tag is use to give the organizational
affiliation of the author.
<AUTHOR_AFF>(affiliation text)
The <AUTHOR_ADDR> tag is used for address information. You can
specify one to six lines of text. The text is separated by the "\"
backslash.
<AUTHOR_ADDR>(address line 1\address line 2\etc. . .)
We will add some author information to our article text.
<title_section> <title>(Country Living) <subtitle>(Where Every Day is an Adventure) <endtitle_section> <running_title>(Life in the Country) <running_feet>(Country Life) <author>(June Bugg\Writer) <author_aff>(<emphasis>(The Country Gazette) Newsletter) <author_addr>(Route 4 - Backcountry\San Diego, California) |
If you want to put in comments about the article or material in the
article, you use the <ABSTRACT> tags. The abstract tags can be
used with other doctypes. The format is:
<ABSTRACT)
text
<ENDABSTRACT)
A short abstract will be added to the article.
<title_section> <title>(Country Living) <subtitle>(Where Every Day is an Adventure) <endtitle_section> <running_title>(Life in the Country) <running_feet>(Country Life) <author>(June Bugg\Writer) <author_aff>(<emphasis>(The Country Gazette) Newsletter) <author_addr>(Route 4 - Backcountry\San Diego, California) <abstract> The change from city living to country living can be very exciting. It might even be a little bit hazardous at times. <endabstract> ---- body of file goes here, later ---- |
The main body of text (subject matter) will be added later. The next sections will describe tags that can go at the end of the SDML text file. |
| Previous | Next | Contents | Index |