Active GUI element
Static GUI element
Code
WPS object
File/Path
Command line
Entry-field content
[Key combination]
Guidelines for Submissions to the VOICE Newsletter
Last updated: April 18, 2006
Content
- General
- Some general notes about how things work.
- Legalese
- Legal terms for submitting an article.
- Possible topics
- General and specific topics for future articles. Look here if you would like to write an article but don't know what to write about or aren't sure if your idea is suitable for the Newsletter.
- Preparation, content, and structure
- Information about how to write an article. Unexperienced authors can find detailed instructions for reviews, how-tos, editorials, reports, and interviews.
- Formatting and HTML coding
- Detailed information about what you should, can, and shouldn't do to structure and markup your article.
- Links
- Links to related pages and tools.
General
First and foremost, please do not hesitate to ask if you have questions regarding these submission guidelines.
The VOICE Newsletter is a project that is completely based on volunteer work, which applies to authors,
publishers, editors, and translators alike. Nobody gets paid other than by possible sponsoring by our readers (as if
that's going to happen).
The complete staff donates their time to this project, yet they have jobs, families, friends, and hobbies. Please
consider this and help to minimize waste of time by following the guidelines below.
The guidelines may seem a bit daunting at first but we have tried to provide enough ideas and information for even complete novices to writing and HTML to succeed. Depending on your level of expertise you will find that you can skip several parts.
Here is how it works: You write an article and send it to editor@os2voice.org. If it consists of more than one file, please pack them with Info-ZIP. Please be sure your article is a valid (X)HTML or plain text file. If you submit an article as plain text, you may use Usenet- or e-mail-style markup for bold and italics. (X)HTML files need to use the VOICE Newsletter styles (see below).
There is no requirement as to length, since this newsletter is only in XHTML and INF format. It can be as long or
as brief as necessary, so be thorough in your descriptions and commentaries. However, please remember that you are
not writing your master thesis, so you don't have to begin at the very beginning à la And first the
earth cooled...
The reader will get bored very soon if you begin the review of a word processor with a nicely
worked-out history of word processing software.
Your article will then be reviewed and run through a spell checker (something that you should also have done before sending the article). If there are any changes we think should be made that are not related to spelling or grammar, we will let you know and we can discuss them. We do not make any major changes without input and approval from the author. We will work on it with you to get it in shape. We are not professional editors, but we believe we have done some decent work on the Newsletter.
As to professionalism of writing, please refrain from vulgar and abusive language, illegal subject matter, and
slander/libel. While a casual writing style (writing as you would talk
) can be acceptable or make sense
in some cases — as a stylistic device, in editorials or glosses — we strongly encourage you to choose a
more professional approach in general (this does not mean that you cannot be funny). Our aim is to encourage
readership and author participation by presenting a tasteful, yet useful medium for OS/2 related information.
Legalese
Sorry, but alas we cannot spare you the following. It is required for our and your own safety.
By submitting an article for the VOICE Newsletter you grant VOICE the irrevocable and perpetual right to translate, publish, store, and distribute the article (defined as text, included images and code) via any media without any compensation. You also grant VOICE the right to apply modifications to the translation if required for better comprehensibility. Otherwise you retain the full copyright. By submitting an article you also assure that it is free from copyrights of third parties, or that these third parties agree to the terms mentioned above, and that you are liable for any possible copyright infringements in your article (text, images, or code).
Topics
If you are not sure whether your idea for an article is suitable for the Newsletter, have a look at the following list of general kinds of articles:
- Reviews of hard- and software including citing and evaluation of facts regarding installation, features, stability, and support.
- Comparative reviews of hard- and software products of the same kind, e.g. graphics adapters or office suits, including comparisons of properties like e.g. finish, installation, features, stability, and support. Teaming up with one or more other authors is advised due to the huge workload.
- In-depth guides covering installation, configuration and optimization of complex or hard to use products (so-called HowTos), e.g. OS/2 itself, Emacs, or TeX.
- Essays and comments regarding things that are going on in the world of (OS/2) computing.
- Presentations of OS/2-related projects and web sites like Odin, Netlabs, or OS2.org.
- Tips & tricks
- Introductions to programming in certain languages like, for instance, Ada95 or Python, or to special parts of programming with an eye on OS/2 specifics, e.g. PM/WPS or multimedia programming. (You may want to submit those to EDM/2, though.)
- Collections of information resources regarding a specific topic.
Here are some concrete suggestions for topics that we think are of particular interest:
Reviews
- Astronomy: Nightvision, PmAs, XEphem for XFree86/OS2
- Office: Accounting applications, LyX for XFree86/OS2 (a LaTeX GUI), Mesa 2
- Filemanagers: A big comparative review of, e.g. F, FC/2, FileStar/2, EF Commander, Connect/2, etc.
- Databases: Comparative and single reviews of Approach, DB2, DBExpert, MySQL, PostgreSQL
- Editors: Comparative and single reviews of Emacs, Enhanced EE, EPM, FED, FTE, MED
- E-mail clients: Comparative review of MR/2 ICE, PMMail, Polarbar Mailer, Emerald Mail, Gnus/Emacs, Pine, Snee/Vsoup, Yarn/Vsoup. Also single reviews of the less known packages are very welcome.
- Development: Free Pascal, GNAT, OpenWatcom, Virtual Pascal
- Graphics/DTP: DrawIt!, Embellish, GIMP, GMT, Gnuplot, Maul, Photo>Graphics, PhotoTiger, PMView Pro
- FTP clients: Comparative/single reviews of NcFTP, NFTP, emtec FTP, F, Handy FTP
- Newsreaders for OS/2: both comparative and single reviews of both PM and text mode applications. A few candidates: ProNews/2, Gnus/Emacs (w/ Changi?), Slrn/Slrnpull/Changi, Snee/Vsoup, Yarn/Vsoup/Souper.
- Multimedia: OS/2's weak point, so every package could be interesting. E.g., MP3 players like PM123 or z!.
- Networking/Internet: Links browser, FTP servers (Hethmon Brothers, Peter Moylan), mail servers (Hethmon, IPS, Weasel, Zero Toaster, ZxMail), HTTP servers (Apache, IPS, SRE, Xitami, Web/2)
- Games: Lincity for XFree86/OS2, Shisen/2, Stellar Frontier, emulators like VICE/2, MAME, etc.
- Tools: ePDF, Ghostscript/GSView, Junk Spy 2
- X11: reviews of ported X applications
HowTos
- Workshop desktop publishing with Maul Publisher
- Using Mozilla's new junk mail feature
- Connecting to and using databases with REXX
- Installing and using ported X11 applications
- Getting certain types of hardware to run on OS/2 (determining which drivers are required, which parameters have to be used, etc.)
- Creating PDFs on OS/2 (using Ghostscript 8 and GSView, PMPDF, or ePDF, as well as VTeX/Free)
- Extending EPM with macros
- Reading news and mail with Gnus/Emacs
- Reading news with Srln and slrnpull or Changi
- Reading news and mail with Snee and Vsoup
- Reading news and mail with Yarn and Vsoup or Souper
- No-cost IDE with gcc and Emacs
- GIMP or Photo>Graphics workshop
- PM programming with Ada95 (GNAT)
Reports
- OS/2 and eComStation events like Warpstock and Warpstock Europe, Warp Update Workshop, also other events that are somehow related
- Situations and developments in IT legislation
Interviews
- Interviews with people from the OS/2 world (developers, event organizers, etc.), e.g. Kendall Bennett, Daniela Engert, Jason A. Gow, Adrian Gschwend, Kim Haverblad, Mike Kaply, Christian Langanke, Sander van Leeuwen, Ulrich Möller, Rich Walsh
Preparation, content, and structure
Before you start, take some time to think about the target group of your article: Who are you going to write for? This question is extremely important as quite a number of things depend on the answer. The target group determines what kind of knowledge can be taken for granted, as well as specific areas of interest. Furthermore, different target groups face different kinds of problems, and have different ways of tackling these.
A few words on style. Dealing with the question of How to say it?
in-depth is way beyond the scope of this
document but we try to give some directions.
There are several levels where you can move between extremes. There is much room for variety but please consider the following:
- Colloquial vs. formal: While a casual writing style (
writing as you would talk
) can be acceptable or make sense in some cases — as a stylistic device, in editorials or glosses — we strongly encourage you to choose a more professional approach in general (this does not mean that you cannot be funny). - Funny vs. dull: People don't read you because you are funny unless you are really funny. Also, something that cracks you up doesn't necessarily do so for others. That does not mean that you have to bore your readers to death or cannot make an occasional joke, of course.
- Polemic/subjective vs. factual: Unless you are writing a rant or gloss, it is recommended to keep a very good distance from the polemic/subjective end of the scale. And even then, you may want to be very careful. If associated with zealotry, a writer can quickly lose his credibility.
- Digression-laden vs. concise: Be thorough and provide as much information as required. However, be careful that you don't stray from the path and your train of thought loses track. This may defeat the purpose and lose the readers' attention.
- Rich with stylistic devices vs. dry: Stylistic devices are usually a means for emphasizing or creating something. If used with care, they can make an article very lively, help you to maintain the readers' attention and create a lasting impression. If used excessively, however, they fail — if all is emphasized, nothing is.
Too much of a good thing can kill you.
Many things are more efficient in small doses.
All kinds of article types share some common characteristics:
- Your byline: Include your name, e-mail and a web site if you'd like. You can also give a brief biography including a picture of yourself if you want. This would be included in a small informational box.
- Introduction: Almost all types of articles begin with an introduction. Its purpose is to catch the reader's attention and, thus, should be short and to the point. A length of one paragraph is common, a second may be possible in some cases. In general, the introduction states the article's topic, provides a short outlook on the content, and briefly summarizes the result.
- Graphics can help a lot with explaining how things work. These can be photos, screenshots, or other illustrations. Remember to put in your document where you want the images to go if you don't use the XHTML format. It is advisable to create screenshots before the actual writing process. Otherwise you may be forced to repeat certain operations.
- Abbreviations, acronyms, and technical terms should be explained upon first usage. In the case of widely used computer abbreviations and acronyms, this will automatically be taken care of by our scripts.
- Resources: Please list URLs of web sites you refer to or titles of books you have taken information from.
- Summary: Provide a short summary/abstract of your article. This makes it easier for our readers to decide whether it will make an interesting read or not.
The following should give you a rough idea of what to include in different types of articles and how to do it.
Experience report
Essentially, this type of article describes a product, service, event, or problem, the key characteristic being that it presents the author's personal experiences. This is usually done diary-style or anecdotically, i.e., the facts and events have a chronological or associative relation, not one of content.
As a result, and compared to other article types, the experience report is the easiest on the writer but also the hardest on the reader. It can be quite entertaining but the scattered facts and its subjective approach make it hard for the reader to see what information is essential.
Due to the above, experience reports are not found in professional media, except for a very restricted set of purposes. Generally, they are only used to report cases of, e.g., extremely bad support, or as glosses (see below). As far as the VOICE Newsletter is concerned, also reports about events are acceptable in this form, although we recommend a mixture of experience report and normal report.
Reviews
A review presents your findings from a product test, a product being hardware, software, or a book. The following focuses on hardware and software but much also applies to book reviews.
If your article is a review, you should definitely read Esther Schindler's article How to write a product review from the November 2000 issue of Extended Attributes.
The article type of reviews has three subtypes that have slightly different purposes each:
- Review of a single product: This type primarily aims to answer the question whether the product is good.
- Comparative review of several products of the same kind: This comparison also aims at the product quality. The reader's main question, however, is which one of the products is best.
- Technology overview: With very complex products, the article becomes more of a description of different approaches to solving a problem and introduces the products as example implementations. Due to the high complexity, such articles don't deal with the matter in such in-depth ways but rather provide overviews and starting points for the reader's further investigations.
Preparations
- Read the documentation! Find out if it covers all features of the product, explains them in a comprehensible way, and is suitable for the target group.
- Use the product and keep your target group in mind. Start with simple tasks and gradually proceed to more complex ones. Find out what the product can and what it can't do. The most important question is how well the features are suited to solve the problem.
Content and structure
Essentially, the article should contain the following parts:
- Introduction: What is the problem the software aims to solve? Why did you choose this particular package? How did you go about deciding on it? What alternatives did you consider? What were your initial impressions about it?
-
Setup/Installation: Was it complete out of the box (or zip file), or did you have to purchase or find additional items like cables and drivers (this mostly applies to hardware)? Did you have to read the manual? Was there a manual, if so how good/helpful was it? Did you still have to boot to plain DOS or Windows to run any kind of setup or calibration software? What hardware are you using it with (major PC specs if applicable, i.e., CPU, RAM, HD) and what version of OS/2? Any minimum hardware/software requirements for this application? What kind of support is provided? Did you have reason to ask for help, if so how was the response?
Normally, installation itself shouldn't be talked about, since a well-working one is expected from every product. But if you had problems or you think that certain things have been solved in a very intelligent way, do comment on that. -
What is it capable of and how does it work: What does the manufacturer claim that the product can do? Does it hold to this promise? Don't recite the feature list! Deal with the features that are interesting for the reader instead. Give some details on how you use the application. No need to get into every detail, just the basics is fine. Be aware that your way of doing things isn't necessarily the same as our readers'. Graphics and figures are nice and help a lot in showing how a product works.
Many people seem to be tempted to write something like a user's guide in this case. If you are reviewing a product, don't write about which menu you have to select to invoke a feature. Better tell the reader how good that feature works. - Evaluation: List your detailled likes and dislikes here. In general, the readers will expect you to first list the likes and then the dislikes. Comment on usability, especially in regard to the target group. Is it better or worse than comparable products? Are you missing a feature which is essential for solving the problem? Did you have to contact the manufacturer or vendor for support?
- Conclusion/Final Thoughts: Are you satisfied with this product? List its main strong and weak points. Did you have to contact the manufacturer or vendor for support? If so was it any good? Can you give a comparison to any similar product as far as quality and general usability? Is it a good value? Would you make the same decision again, or advise others to buy it? For whom is it suitable?
- Resources: List any URLs for getting information about the device and any software used specifically with it, if any. Also give the manufacturer's suggested retail price and/or a general price range for it and possibly the vendor or vendors where it can be purchased.
How-tos
If your article is a How-to, i.e., it explains how to achieve certain things with certain applications, tool, etc., please mind the following:
- Restate what the problem was and what the steps and tools you used to solve it were.
- Try to bring the steps into a chronological order and leave out things that aren't related since they might just confuse the reader.
- Begin the article with a short description of the problem, maybe a statement about why you think it is worth the hassle, and perhaps a short lookout on how it can be solved.
- List the required tools (if not too much this can also be done at the very point in the process they are used at, perhaps at the beginning of each chapter). Do these tools require any other things? If complex preparations are required to use the tools, describe them before beginning with the description of the problem-solving itself.
- Is any extra-knowledge required to solve the problem that is not directly related to the
steps? Describe it prior to dealing with the problem-solving itself. Don't insert chunks of it in between like,
e.g.,
And, by the way, abc works by doing xyz.
- List the steps which are required to solve the problem.
- If there are different approaches and they take longer to deal with, create a separate chapter for each one. Don't mix alternatives in one paragraph so the reader doesn't get confused.
- Always take into account that the reader probably knows a lot less than you. Don't take power-user knowdledge for granted. So be detailed, but don't explain basics that aren't required for the reader to be able to reproduce the steps (and understand them).
- Don't list information that isn't really related to a specific step in that step's chapter/paragraph. If it could come in handy though, donate a separate chapter to it after the problem-solving process, or use the digression box style (see below).
- Troubleshooting information, i.e., how to determine what went wrong where, would be nice if the issue is a complex one.
- List sources where interested readers can obtain further information which deals with the background, digs deeper, etc.
Editorial/Gloss
Editorials give your personal opinion regarding a certain topic and often try to persuade the reader to agree with
you and, as a result, do certain things.
Glosses usually deal with a topic in an ironic or sarcastic manner. Sometimes, glosses are written as fake articles
of another type, e.g., reviews, reports, or interviews.
A common characteristic is the increased use of stylistic devices.
Editorials are not structured very strictly. Nevertheless, the following applies:
- Present the facts your opinion is based on and then draw strong conclusions.
- To make sure you reach your aim you may want to use stylistic devices for emphasis, humor, etc.
- Be sure not to provide too much background information on your topic. This will disrupt the build-up of tension and you will have to start at the beginning again.
- Make sure that you don't let your train of though lose track. Again, this will disrupt the build-up of tension.
- Editorials often end with an appeal to the reader.
Glosses that are faked articles generally follow the structure of the faked article type.
Report
Essentially, a report describes an event that the author has attended or a topic that the author has researched, the main difference to an experiences report being that the author himself takes a backseat and the focus lies on the topic.
While preparing the article, you may want to get some comments from people involved, i.e., visitors of an event or the ones concerned.
- As an introduction, provide brief information about the event or topic and state your main conclusion. Was the event any good? Is a future change going to improve the situation?
- List facts about sessions and products at the event or details of the topic. Depending on the complexity of the matter, you may want to devide this part and draw conclusions for the subsections. You can add comments from those involved to circumstantiate your conclusions. Do not rely on second-hand information for facts! Were you satisfied with a smaller part of the event? How did the number of visitors evolve? What is the essential statement that can be made regarding an aspect of the topic?
- Comment on the facts listed above. How did the event evolve over time? Does the event mirror developments? What are the consequences of the above facts in detail? Evaluate situations and developments.
- Draw a main conclusion. Were you satisfied with the event? What were the main strengths and weaknesses, the most important pieces of information? What is the essential statement that can be made regarding the topic? Is there a need for (further) change?
Interview
Interviews provide different ways to obtain answers to questions. The key question — which you have to
answer yourself — is What does the reader want to know?
or What information could be interesting for
the reader?
The answer to this determines who, how, and what you are going to ask.
There are different types and levels of interviews:
- With one person
- With more persons: In this case, you will have to cope with interaction between the interview partners. The kind of interaction depends on whether your partners are part of the same group, or opponents. While partners from the same group can complement each other, the presence of another person can also make people more wary of saying something wrong. Bringing together opponents can result in quarrels and you having to exercise control, which can be very difficult, but may also spark a lively and interesting discussion, or even lead to a slip of the tongue situation.
- Guided to informal: In a guided interview, you strictly go through your prepared questions, while an informal interview is more like a chat. The guided certainly is the quicker way and also ensures that no questions are forgotten. An informal style can make the partner feel more comfortable and, thus, more likely to answer more freely. On the other hand, there is danger of digressing often and too far.
- Personal or indirect: You can communicate with your partner synchronously (face to face, on the phone, in an internet chat) or asynchronously (by e-mail, mail, etc.). Synchronous communication ensures a certain level of spontaneity. When communicating asynchronously, both you and your partner have the opportunity to be more elaborate and prepared (in both positive and negative senses). When speaking to your partner in person, i.e., seeing the face and/or hearing the voice, you are in a better position to judge your partner's reactions. This also helps to avoid misunderstandings.
Interviews can have different kinds of focusses:
- A topic the interview partner is familiar with or concerned by (e.g., a product or law)
- Something the interview partner represents (e.g., a company, organisation, or project)
- The person itself
Depending on your target group, you may want to either choose a focus for an interview with a given person, or think about whom to ask about a given topic to get the desired information.
Preparations
- Once you have decided on the interview partner and the topic, find out more about both. You don't want to alienate your partner or the readers by showing that you don't really know what you are talking about. Also, background information will help you to find more interesting questions.
- Prepare your questions in advance. Even if you later decide to skip, add, or change questions, it is always wise to have something to rely on. Furthermore, you are likely to focus on your own areas of interest instead of the readers' if you come up with questions spontaneously.
- Think about the phrasing: What do you want to know and achieve? If you are going to touch somewhat sensitive matters, you may want to think about alternatives for different atmospheres/reactions. Who are you going to talk to? Think of possible interaction between partners.
Interviewing
Apart from the general rules of conduct, there are a few things more to consider:
- Respond to partner reactions. This is a key to a successful interview. Depending on the information that
answers provide, changes in the atmosphere, and interaction between interview partners, you may want to bring
forward or defer questions, or choose a different phrasing. If a discussion between your interview partners gets a
bit heated, or your partner doesn't really answer your questions, you may even have to
call someone to order.
- Do not push your partner into a role! What you know about your interview partner and the topic will cause you to be prejudiced. If your interview partner does not behave and/or respond as expected, you can try to find out why but do not try to force your partner to fit your image of him.
- Do not make yourself the focus. The reader wants to know about your interview partner and/or the topic. Always remember that your personal take on the matter is irrelevant.
Content and structure
- In the introduction, provide some facts about the interview partner and/or the topic. You may mention if the interview was done in a particular pleasant atmosphere.
- List the questions and answers.
- In general, you should edit and perhaps rephrase the interview to remove colloquial language. The level depends on the atmosphere. Of course, an interview that actually was a chat with much bantering shouldn't be cut down to the cold, hard facts only.
- If you jumped back and forth between different topics, reorder questions for a more straight train of thought.
- Maybe insert related photographs.
- Remove parts of the interview that are not interesting for the reader. If such parts help the reader to get a better impression of how the interview was like, you can leave them in.
Be careful not to change things in a way that creates false impressions! - Get authorisation from your interview partner. This includes providing him with the finished interview text. Your partner may of course request that you change edited parts of the interview.
Formatting and coding
Formatting the text in certain ways can increase readability a lot. VOICE uses XHTML and CSS to define article structure and presentation. Please ensure that your article conforms to the following to keep the Newsletter's interface consistent.
- Get our author package. It includes everything that is needed for the article body: CSS files, images, a definition file for PPWizard, and an empty XHTML file that loads the CSS. This provides you with everything you need to see what your article will look like.
- If you write your article in (X)HTML, make sure that you use the styles provided by our style sheets only. Additional styles will be dropped unless there is a very good reason not to do so.
- You do not need to rebuild the Newsletter design with header, footer, and boxes. This is automatically taken care of by PPWizard scripts. Just provide the layout which you want to use inside the article's body, and the data regarding yourself, program data, links, etc.
- Ensure that your HTML editor does not use absolute local links like C:\VOICE\feature_3.html.
- All URLs should be listed fully readable in the seperate references section, e.g., as http://hobbes.nmsu.edu and not Hobbes. The latter method is preferred inside the article's body.
Structure
For structuring an article and presenting information, the usual standard XHTML tags for headers, paragraphs, line breaks, lists (unordered, ordered, and definition), tables, etc. plus a number of special styles are available.
Headers
The first level header (<h1> tag) is reserved for the article title only, so article headers start at the second level. While XHTML supports up to six header levels, please avoid unneccessary complexity. In general, using the second to fourth level headers (<h2>, <h3>, and <h4> tags) should be enough.
No numbering of headers, please. The VOICE Newsletter is neither a scientific nor legal publication.
Paragraphs and line breaks
Use paragraphs and line breaks to illustrate your train of thought. Please note that while using long paragraphs with many line breaks is quite common in printed media, they are hard to read on a computer monitor.
Lists
Please use the different types of lists as they were intended to. Lists are not a replacement for headers!
Ordered lists should only be used if there actually is an order or priority in the sequence of list items, e.g., when consecutive steps for a setup are described. If the order is not important, the unordered list is the way to go.
When explaining a number of terms in a wider sense, e.g., terms, parameters, commands, etc., use a definition list. Please do not use tables for such purposes unless the information you present is tabularly and would require more than two columns.
Tables
Tables should be used to present tabularly information only. They are not a means for layout. If you want to list definitions of terms that would result in a two-column table, a definition list usually is the better alternative.
Always provide a caption that defines the table content. These should be numbered in the following way:
Tbl. 1. Performance test results for AMD Athlon processors
Provide headers that define the content of each column or row. Special styles are available for marking parts of a table or single cells.
Keep them simple: Please don't include images in tables and avoid nested tables since both kinds are not supported by IPF and make generating the INF version of the Newsletter very complicated. Furthermore, they make it hard for people with screen readers to understand the page.
Images
Images can be in just about any format, but we prefer PNG, JPG, or GIF. Note that the different formats are also suitable for different purposes. JPEG is likely to result in washed out fonts in screenshots of dialogs, for instance.
Try to keep them to 256 colors or less (this is a requirement of the INF version), and the smaller the file size the better, as some people download the Newsletter to read off-line. If the image width exceeds 600 pixels, you may want to consider using thumbnails in the text.
You may want to mark relevant parts of an image with colored arrows, circles, or boxes to direct the readers' attention.
Always provide alternative text for people with text-mode browsers or screen readers, please.
Add meaningful captions below images. Usually, they can repeat the alternative text. These should be numbered in the following way:
Fig. 1. LAN interface setup dialog
Styles
Please see the following tables for a list of available styles, notes on usage, and examples. We have tried to
keep style names as self-explaining as possible. Inline styles begin with a lower-case i
and block
element styles with a lower-case b.
Unless explicitely stated, styles inside paragraphs are applied by enclosing the text like this:
<span class="classname">text to use a style with</span>
Where a tag is given in angle brackets, it has to enclose the text like this:
<tag>text to use a style with</tag>
Name | Usage | Example | Classname/Tag |
---|---|---|---|
With special tags | |||
emphasis | A newly introduced term that is used for the first time in the article, terms in foreign languages, slightly emphasized things. | This was the first time a computer was used for such calculations. | <em> |
strong emphasis | A strong emphasis, e.g., for a warning. | Do not format your drive unless you have a working backup. | <strong> |
acronym | An acronym or abbreviation. If you move the mouse pointer over the acronym, an explanation is displayed that is provided via the title attribute. For many widely-used computer abbreviations and acronyms, this will automatically be taken care of by our scripts. | V.O.I.C.E | <acronym title="long description"> |
code | Any snippet of program code in a wider sense. E.g., HTML, CSS, REXX, C, Pascal. | SysSetObjectData() |
<code> or iCode |
keyboard input |
Keyboard input to be entered by the user. A |
[Ctrl-C] | <kbd> or iKeyboard |
quote | A quote from real persons or books, or program messages. Note that the browser adds quotation marks automatically. | You have selected to delete the file test.zip. Continue?or To be or not to be? |
<q> |
citation, quote source | The source of a quote. This could tell you whom the To be or not to be?quote from above originated from. |
Hamlet | <cite> |
variable, syntax | A variable, variable name, or program argument. Often used to explain command syntax. | directory or filename | <var> |
With classes | |||
address | All kinds of addresses. | 192.168.1.1 or comp.os.os2.bugs | iAddress |
command | A command that has to be entered at a command line and executed by pressing the Enterkey. |
unzip test.zip -d x:\temp | iCommand |
command output | Output that is displayed by a program at a command line. | unzip: cannot find either test or test.zip. | iOutput |
entryfield | Text that has to be typed in an entry field. | The quick brown fox jumps over the lazy dog. | iEntryfield |
files, paths | The name of a file or folder, or its partial or fully qualified path in the file system. | CONFIG.SYS, OS2\INSTALL, or C:\OS2\BOOT\OS2DASD.DMD | iFile |
GUI elements, active |
For active GUI elements, which cause some action to occur when clicked: menu items, push buttons, checkboxes, radio buttons, lists, combo boxes. A |
Browse or File > New | iGuiActive |
GUI elements, static | For static GUI elements, which are used for information purposes: window and dialog titles, group names. Groups are borders, usually surrounding several associated active GUI elements. | Shutdown | iGuiStatic |
WPS objects |
Workplace Shell desktop objects, both abstract and with a file system pendant. A |
Templates or Local System > System Setup > Mouse | iObject |
Unless explicitely stated, styles constituing paragraphs are applied by enclosing the text like this:
<div class="classname">text to use a style with</div>
or
<pre class="classname">text to use a style with</pre>
General purpose containers (<div> tags) can contain other markup constituing paragraphs itself.
Name | Usage | Example | Classname/Tag |
---|---|---|---|
summary | The summary of an article. Usually located directly after the title. |
Emacs is an extremely feature-rich and extensible editor. However, these qualities have a price: complexity. Many people have surrendered to the steep learning curve that has to be overcome before one can take advantage of all the program's goodies. To help you avoid the same fate, this article describes the installation and customization of the Emacs editor in great detail. |
<p class="bSummary"> |
quote | Quotes that extend over several lines. |
The VOICE bylaws state:
So this organization is about OS/2. |
<blockquote> |
Classes for general purpose containers (<div> tag) | |||
header | A general purpose header that can be placed above any paragraph-style markup |
A header
Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's
intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the
time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in
the mid-1980's, it was quickly becoming obsolete.
|
bHeader |
digression | A box that contains side notes and digressions that don't otherwise fit into the flow of the article. |
OS/2 history
Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's
intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the
time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in
the mid-1980's, it was quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit,
command-line based operating system. Microsoft worked closely with IBM up to version 1.3. While IBM worked on
the
guts,they worked on the new graphical user interface that was due for later versions. OS/2's kernel was developed by IBM from the ground up as the Personal Computer (PC) version of a mainframe operating system, with all of the time-slicing, stability, and other features previously existing solely on those high-end machines. |
bDigression1, bDigression2 |
entryfield | Several lines that have to be entered into an entry field or similar. |
The quick brown fox jumps over the lazy dog.
Then it escapes the hunter by hiding behind a bush. |
bEntryfield |
caution | An important note. |
While RSU is great to have on standard OS/2 systems, I don't recommend using it on eComStation systems.
The eCS Maintenance Tool provides its own method of installing FixPaks over the Internet, and it's
already much more advanced than RSU ever was. It also handles post-installation dependencies specific to
eComStation (like updating the dialog and icon resources), which RSU does not.
|
bCaution |
warning | A warning. Failing to abide by this instructions can lead to severe problems. |
Create a backup of your INI files before installing this software. It is still in beta state and could
completely break your WPS.
|
bWarning |
finished, checked | Notes about a larger section of work that has been finished and the consequences thereof. |
Now that we have finished the above configuration steps it is save to reboot the machine and start the server
for the first time.
|
bChecked |
reminder for later | Things to keep in mind. |
As you can see, the configuration steps executed above have changed the application's display the way we
wished. We need to keep this in mind for later, when we adapt the printout.
|
bPin |
success, ok | Specific characteristics that mark an operation's success. Something that is particularly positive about a piece of software or hardware. |
Congratulations! You have finished configuring the most versatile and complex editor ever developed!
|
bThumbsup |
Classes for preformatted text (<pre> tag) | |||
code | Several lines of arbitrary code. |
Example #1: xcenter.c from XWorkplace
SOM_Scope BOOL SOMLINK xctr_xwpMoveWidget(XCenter *somSelf, ULONG ulIndex2Move, ULONG ulBeforeIndex) { // XCenterData *somThis = XCenterGetData(somSelf); XCenterMethodDebug("XCenter","xctr_xwpMoveWidget"); return ctrpMoveWidget(somSelf, ulIndex2Move, ulBeforeIndex); } |
bCode |
command | Input and output at a command line. |
unzip notexist.zip -d x:\
unzip: cannot find either notexist or notexist.zip.
|
bCommand, bCommandOutput. Note that bCommandOutput can only be used with span tags inside a bCommand block. |
file content | Generic file content. |
Partial CONFIG.SYS
BUFFERS=100 IOPL=NO DISKCACHE=512,LW,32 MAXWAIT=1 MEMMAN=SWAP,PROTECT SWAPPATH=H:\ 10240 92160 BREAK=OFF THREADS=1024 PRINTMONBUFSIZE=2048,134,134 |
bFileContent |
In general, images have to inserted in general purpose containers (<div> tags). They are followed by a line
break and an image description.
Under certain circumstances, however, placing a caption may be completely superfluous or even ill-advised. In an
editorial, a cartoon with a caption that says Fig. 1. Cartoon explaining why xyz sucks
would be
unintentionally funny, for instance. Should that be the case and it is intended to let the text flow beside the
image, the image can be inserted directly into the corresponding paragraph and a class can be assigned to the image
itself.
Name | Usage | Example | Classname/Tag |
---|---|---|---|
image on its own | An image that has its own paragraph without text flowing to either side of it. |
Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in the mid-1980's, it was quickly becoming obsolete. Fig. 1. An image displayed on its own line Thus, OS/2 was born, initially as a 16-bit, command-line based operating system. Microsoft worked closely
with IBM up to version 1.3. While IBM worked on the |
bImageCenter |
left-justified image | An image with description and text flowing to the right of it. |
Fig. 2. An image displayed on the left side Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's
intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the
time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in
the mid-1980's, it was quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit, command-line
based operating system. Microsoft worked closely with IBM up to version 1.3. While IBM worked on the
|
bImageLeft |
right-justified image | An image with description and text flowing to the left of it. |
Fig. 3. An image displayed on the right side Operating System/2 (OS/2) was originally developed as a joint project between IBM and Microsoft. It's intention was to replace the antiquated Disk Operating System (DOS) as the operating system of choice. At the time, DOS was at version 3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in the mid-1980's, it was quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit, command-line based operating system. Microsoft worked closely with IBM up to version 1.3. While IBM worked on the "guts," they worked on the new graphical user interface that was due for later versions. OS/2's kernel was developed by IBM from the ground up as the Personal Computer (PC) version of a mainframe operating system, with all of the time-slicing, stability, and other features previously existing solely on those high-end machines. |
bImageRight |
left-justified image inside of paragraph | An image without description and text flowing to the right of it. |
Operating System/2
(OS/2) was originally developed as a joint project between IBM and Microsoft. It's intention was to replace
the antiquated Disk Operating System (DOS) as the operating system of choice. At the time, DOS was at version
3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in the mid-1980's, it was
quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit, command-line based operating system.
Microsoft worked closely with IBM up to version 1.3. While IBM worked on the |
iImageLeft |
right-justified image inside of paragraph | An image without description and text flowing to the left of it. |
Operating System/2
(OS/2) was originally developed as a joint project between IBM and Microsoft. It's intention was to replace
the antiquated Disk Operating System (DOS) as the operating system of choice. At the time, DOS was at version
3.x, and IBM and Microsoft both realized that with the advent of the Intel 80286 in the mid-1980's, it was
quickly becoming obsolete. Thus, OS/2 was born, initially as a 16-bit, command-line based operating system.
Microsoft worked closely with IBM up to version 1.3. While IBM worked on the |
iImageRight |
Besides the normal cells, the following is available for formatting tables:
Name | Usage | Example | Classname/Tag | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
caption | Describes the content of the whole table. |
|
<caption> Placed directly after the table tag. | |||||||||||||||
header | Describes the content of a column or row. |
|
<th> | |||||||||||||||
category header | A sub-caption that describes the content of the following table columns and rows |
|
<th class="category" colspan="x"> Note that this has to get a colspan attribute assigned with x usually being the actual number of columns the table consists of. | |||||||||||||||
marker color 1 | A backgroundcolor for marking a table cell. | Test | <td class="mark1">Test</td> | |||||||||||||||
marker color 2 | A backgroundcolor for marking a table cell. | Test | <td class="mark2">Test</td> | |||||||||||||||
marker color 3 | A backgroundcolor for marking a table cell. | Test | <td class="mark3">Test</td> |
Links
- How to write a product review by Esther Schindler
- The essential steps to writing an effective product review, by Esther Schindler, extended attributes, November 2000
- HTML Tidy
- A freeware tool for checking and formatting HTML code. It is also capable of correcting errors.
- WWW Consortium
- The WWW Consortium offers extensive informationen on the HTML standards defined by itself, an online validator for web pages, and more.
Again, if you have any questions regarding the submission itself or how to write an article, feel free to ask.
Thank you,
The VOICE Editors