Manual

Manual

Search

Prototype

See Parent page

After the screenshot is where any longer introduction to the topic belongs. As with the introduction at the top, this is optional.

Introductory Sentence

This optional sentence comes first on the page. It is nearly always omitted on pages in the Setup section of the manual, because those pages are self explanatory. If this page is for a special audience, this is the place to state it. The intro sentence should not contain links, because those would confuse the reader about whether it was an uplink or not. Any necessary links would belong in the longer intro below the screenshot.

Uplink

Every page requires an uplink to its parent. All approved patterns are listed in Uplinks.

Screenshot

After the uplink, it is strongly recommended, if at all possible, to show a screenshot representing this topic. There is almost always one single manual page matching up with each single window in the UI. This one-to-one relationship guides the decision on when to create new manual pages and how to name them.

For a large complex window, a manual page could use a screenshot of a tab area or a grid. There should usually be no reason to use the same main screenshot for two different manual pages.

Within the page, there should be outgoing Links and Redirects to each child page. There should also be cross Links to any far-flung related pages.

Programming

All requests and current jobs for the manual and website are tracked on a dedicated page. See Programming

Special XML Characters

There are only three characters that need special treatment in the xml:

Extended characters cannot be expected to work. This includes ellipsis and smart/curvy quotes. If apostrophes or quotes are causing a problem in a document, erase the character and type in a replacement from your keyboard.

Whitespace elements like carriage returns, tabs, and spaces are meaningless in xml. They are used by us to format the layout to make it more readable. For consistency, the Manual Publisher always adjusts whitespace upon saving.

xref

The xref (cross reference) element links to another page or website.

Internal links to other manual xml pages can be written with or without the text display element:

External links refer to truly external links, as well as to links to other pages on our website that are not xml manual pages. They should all be fully valid URLs, including the leading http:

To launch target in new tab or window, include target="_blank".
Example: <xref href="http://www.cnn.com" target="_blank">http://www.cnn.com</xref> http://www.cnn.com

p, br, sp

The most common element is a p (paragraph). Our css creates some whitespace after each p to visually separate the paragraphs. If you would like to start a new line without the whitespace, then use an empty br (break) tag at the end, like this:<br/>
Then type some more, still within the same paragraph. Br is also used to drop an image to the next line without adding whitespace. But this is rare, since images are usually between paragraphs and whitespace is desirable.

The <sp/> tag gives you the ability to force a space to remain.
Here are examples of a series of forced spaces           in the middle of a sentence,
and a forced space between two elements: uicontrol italics (because Microsoft removes it for some reason).

image

Images are usually placed between paragraphs, like this:

Paragraph after the image.

Images can also be within the paragraph, and dropped to the next line with a br, like this:

Continuation of same paragraph. Both of the above approaches should like identical to the reader.

Also, small images can be inline with a sentence like this. Images normally have 10 pixels of whitespace at the bottom, so an inline image needs to be set to zero pixels like this:
<image href="images/apptListIcon.gif" style="margin-bottom: 0px"/>

Lists

The following tags are used to created lists:

The use of lists should be a bit restrained. Try p and/or br tags, instead. An ordered list would not typically be used to organize a large section because it shifts everything to the right, makes the xml harder to read, doesn't leave space between list items, doesn't support sub-paragraphs, and adds complexity. Sometimes, you might use a list for a large section that is an actual sequence of steps. The uplink would not be included in the list.

White space rules:

Here is an example of additional text in the same paragraph as the list above it.

Here is a ul (unordered list) with a nested ol inside it.

Some followup text in the same paragraph.

Paragraphs within lists are not supported. Instead, use br tags to create lines as needed.

Title

These will soon be renamed h2 to match html. We will also add h3, which is a smaller bold black title.

uicontrol

uicontrols (user interface control) are often used to highlight buttons, entry fields, or menu items. They are currently just bold, but I'm considering surrounding each of these with a gray box.

term

Terms are often used to highlight permission names or settings.

note

Note: One of the lists above also contains a note. Notes can be on their own, or nested within a p element or li element. Notes have a little bit of built-in space around them and can be multi-line.

If a paragraph follows a note, like this, it can feel too tight. There are two approved solutions:

codeblock and codeph

Both of these change the font to courier monospace for showing queries or text files. Codeblock is the block version, and codeph is the in-line version. We will soon combine them into one. Here's a series of 5 codeblocks:

[Patient]

ID=17

Gender=Male

First=Mickey

Last=Mouse

And here is a codeph(codephrase) which shows in-line within a paragraph. Here is another: AutoActivatePatient=1.

filepath

A filepath is used to distinguish a file path location such as \\SERVERFILES\Storage\My\Emily

cmdname

Command Line Arguments are used in some bridge documentation. Here is an example from the Owandy Bridge. This bridge launches Quick Vision using command line arguments, then passes some data to Quick Vision using Windows API calls. Prior to version 6.7, it uses the hard-coded value of C /LINK for the command line.

pre

Problems and questions are currently using the pre tag:

Problem or Question

Answer is in a p tag.

This tag will soon be changed from "pre" to "probquest". There is currently too much space between the question and answer. That will be fixed in the future.

Tables

Simple table:

We use simpletable which looks like this
1 A
2 B
3 C

To edit an existing table in the XML, ensure that no error messages are displaying and simply double click anywhere inside the table while in the edit page window. Tables do not need to have headers. If a table does have headers, then the headers will always be bold and centered.

Quoted Text

We use Q (quoted text) for copyrighted material. Here is an example that could work for Canada Fee Schedules: "The ODA Suggested Fee Guide which is included in the Open Dental Software Inc. software and the copyright therein, is owned by the Ontario Dental Association and may be used solely in conjunction with the Open Dental software under licence from the Ontario Dental Association. The "ODA Suggested Fee Guide", "ODA Suggested Fee Guide for General Practitioners", "ODA Design" and "ODA" are trademarks of the Ontario Dental Association."

MsgBlock and MsgPhrase


"Msgblock"
"Another Msgblock."

A "msgph (message phrase)" contains in-line text of a message produced by the software.

Cite

This is a "cite".

VarName

A varname (variable name) is for a variable that must be supplied to the software.

Bold and Italics

bold is used for strength when other tags are not relevant matches.

italics are used for emphasis.

Help

Let's hold off on this for now. We might do it differently.

The help tag behaves just like a p tag, but it also allows our tools to extract the text and display it to users in OD. Within the help tag, there should be a uicontrol tag followed by some text. Lists are ok within help tags. Nested p tags should not exist; use br tags instead. To quickly convert an existing p tag to a help tag, right click and select "Convert to help". If you want to see all the help tags on a page, search for "<help". Better tools will gradually be added to help manage these tags.

Red text

In an emergency, red text can be put on a page like this. But this is only a temporary solution, and should not be used without asking Jordan. It only works within a single paragraph.
Some text in this sentence is <span style="color:red">in red</span>, but not all of it.
Some text in this sentence is in red, but not all of it.
Some text in this sentence is in red and bold, but not all of it.

fig

I made a mistake when I converted the fig tags. The figure captions were accidentally converted to simple paragraphs. There were 59 affected locations. It's easy to find them again by doing a search with notepad++ in the 181 xml folder. It's too hard to automatically undo my change, but we could later manually change them back to some sort of caption if it's important enough.

anchors

Anchors are hyperlinks to sections within a page. Anchors were used in some pages over the last few years but were deprecated in version 17.4. There are still some remnants at the tops of pages where the sections of a page are listed. Those should be removed. Anchors are unnecessary because our pages are short enough that the user can simply scroll down. Including anchors was confusing because users thought they were links to other pages.

YouTube Links

Add links preceded by the YouTube image in the style of the following examples: