Mary McRae wrote:
> Hi Arshad,
>
> The template guidelines are available here:
> http://docs.oasis-open.org/templates/OASISSpecificationTemplateGuidelinesV4.0.ht
> ml
>
> I'm not sure what specific questions Allen has - Allen, feel free to send any
> questions directly to me and I'll try to answer.
Hi Mary,
I looked at the referenced document but did not find what I think
should be in every document.
With my background in technical writing I am used to having a
section early in the document that defines typographic and
nomenclature standards used throughout the document.
It would look something like:
====================
Formatting legend
Format Meaning
Italic Information that the user must supply
Bold Elements that the user must type exactly
as shown
Ellipsis (...) Parameter that can be repeated several
times in a command line
Between brackets ([]) Optional items
Between braces ({}); Choices separated by pipe (|).
Example: {even|odd} from which the user
must choose only one
Courier font Code or program output
=============
Obviously this (which I grabbed from an old document) is not the
right structure for a TC standard, but issues like inconsistent use
of Courier in some of the <(element name)>s but not in others, the
use of abbreviations, the proper use of bold face and italic, Roman
versus sans serif, and capitalization, and dozens more that come up
in creating a complex document, need to be clarified so that a
reader new to the document has a clue as to what action is being
explained or what is a key term that is in the glossary, etc.
Having a table of usage allows for consistency across documents that
is beneficial to all.
Allen
