Formatting your text

Articles must be submitted as normal ASCII format files. Don't worry about these terms: In fact this is the default character code for Linux and even Windows more or less respects it.

Simple tags are used to emphasize the text in certain passages (titles, listings, pictures, and so on). These tags are kept as short as possible to avoid unneccessary typing. The following section briefly outlines the format tags.

The various text elements, such as titles, normal body text etc, are separated by special tags. Tags always use the following format @XX:. Our texts comprise the following major elements:

• A top line that describes the subject (@D:)
• An imaginative main headline/title (@T:)
• An intro (@V:)
• Author name (@A:)
• The text itself (@L:)
• Subtitles (@ZT:)
• An author boxout with a short c.v. (@IT:)

You only need to insert a tag when the format changes. If you have several paragraphs of body text that follow each other, a single @L: at the start of the line will suffice. Of course, paragraphs can comprise several lines of body text. A paragraph break will not occur until indicated by a an empty line (newline character) or the next tag occurs.

An article can never comprise only text. Pictures and other layout elements (boxouts, diagrams) enliven the textflow. After all, who would be interested in reading an article made up entirely of boring text and without illustrative graphics, neat screenshots, or informative listings. Remember that pictures, tables and boxouts are movable elements, so you cannot simply refer to them by saying "as the picture shows" or "as shown below". Instead, you will need to refer to a Figure by number. Identify your pictures figures as "Figure X:", unless of course, your article only contains a single picture.

Humans find it easier to digest visual rather than verbal information. Pictures do not waste valuable space in the magazine, but make it easier for the reader to understand what will mainly be complex technical topics. While you are writing, you should be thinking about how you can make it easier for your readers to understand you, by adding graphics and screenshots!

The question as to suitable image file formats is sometimes difficult to answer. Xfig is a good choice for graphics (that is diagrams, flowcharts, overviews). The format is easy for us to process (our editors all use Linux machines, of course), and to convert to high-quality Postscript. If you do use a different format, ensure that you enclose both the source format and a PS, EPS or PDF version. Our layouters often replace fonts and colors to reflect the typical look and feel of Linux Magazine. JPEG and TIFF are suitable for photos. In case of doubt, simply ask the editorial staff.

PNG and GIF, but definitely not JPEG, are suitable for screenshots. When you create a screenshot, make sure that it contains only the relevant screen areas, instead of empty space. The color scheme you choose should reflect typical European taste and not cause garish blobs in Linux Magazine. Remember that fonts - especially menus - need to be legible in the printed magazine. So restrict the size of any application windows you grab to 800x600 pixels at the most.

Figures are indicated as follows:

The caption should describe what you can see in the picture and thus emphasize the important aspects of the picture. Use a sentence like the following to refer to the figure in the body text:

Or:

Body text always begins with the @L: tag. Tags always refer to the entire paragraph that follows. Two asterisks, instead of a space (as in Red**Hat) represent a protected space that cannot be wrapped. It has a similar function to in HTML.

Text markups such as bold, italic and so on are indicated by tags in angled brackets. Please note that these tags are not terminated HTML style! Short commands, such as "rm -rf *" or file and directory names should be placed in the body text as follows <C>Code<C>. This will appear as follows: rm -rf *. Other possible markups are <I>italics<I>, "quotes" or in extremely rare cases <B>bold<B>. You can even add URLs to the body text, using the <U> tag to indicate them, as in:

A Listing comprising only one or two lines can be introduced by the @LI: tag on a separate line of body text. Listings are printed in a non-proportional font with 41 characters per line. If the line happens to be longer, make sure that you separate the line. Use §§ to indicate the line-wrap (this character should not occur in normal listings). For example:

is slightly too long. Preferably:

It makes sense to place longer listings in a Listing boxout. Listings can be supplied as separate files. Make sure that you supply only complete (that is executable) scripts and sourcefiles, as they will be stored on an FTP server.

Too many lines of code in the body text make an article difficult to read. You should therefore consider placing code in a boxout of its own and refer to the boxout in your article. Of course, we are aware that this is not always feasible, but you should at least try.

Boxouts always have a title(@KT:). Normal text in a boxout is boxout text (@KL:). Listings in boxouts are still formatted using @LI::

In addition to code, boxouts can contain additional information, such as glossaries, interviews, or simply a different aspect of the main topic that does not fit into the main body of text. This are all permissible and even desirable, but try not to overdo things.

Tables are similar in appearance to boxouts and start with the @TT: tag. The individual lines of a table must occupy one line of your source text; the columns should be tab-separated:

You can save our layout staff and us a lot of headaches by supplying tables as spreadsheets (Star Office, Applix ...) at least in a spreadsheet compatible format (.csv or similar). There is some danger of information landing in the wrong columns otherwise.

The Info section includes references to URLs or literature. Again these can take the form of a boxout that is introduced by @IT:Info where the references are placed in an @IL: area:

Use square brackets [1] in the text to refer to a footnote in the Info section.

The author boxout is similar to the Info boxout and is introduced by:

• making too much use of abbreviations (e.g., etc., US$)
• over use of the passive form
• changing the narrative perspective too often (one, you, I, we)
• not enough illustrations, no captions, or captions not descriptive enough
• no subtitles, or subtitles too short
• file formats, such as HTML, Latex, Star Office or Word instead of ASCII text