Formatting your text
Formatting your Text? |
Submit articles as plain text files, saved as “Western (ISO Latin 1).
Tags are used to emphasize the text in certain passages (titles, listings, images, etc.). Below is a brief outline of the formatting tags.
Paragraphs |
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 should include more than just text, please include screenshots, boxouts, tables, or diagrams. These items are movable elements, so you cannot 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 images as "Figure X:".
Images |
Images 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 screenshots or other visual elements.
SVG is a good format for diagrams or flowcharts. If you use a different format, ensure that you enclose both the source format and a PS, EPS or PDF version. JPEG and TIFF are suitable for photos.
PNG and GIF are suitable for screenshots. When you create a screenshot, make sure that it contains only the relevant screen areas, instead of empty space. Try to select a color scheme that has good contrast between the background and the font colors so it is easy to read. Remember that fonts – especially menus – need to be legible in the printed magazine, so try not to include too much in a screenshot.
Figures are indicated as follows:
@Bi:Fig1.png |
The caption should describe what you can see in the picture and emphasize the important aspects of the picture. Use a sentence like the following to refer to the figure in the body text:
@L:Figure 1 shows the simulation of a 90 degree turn as a desktop game written in Go with racing animation. |
Or:
@L:...the simulation of a 90 degree turn as a desktop game written in Go with racing animation (Figure 1). |
Tags in the text body |
Body text always begins with the @L: tag. Tags always refer to the entire paragraph that follows.
Text markups such as bold, italic, and code font are indicated by tags in angled brackets. 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:
<U>http://www.world.wide.wait.net/index.html<U> |
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:
@LI: |
is slightly too long. Preferably:
@LI: |
Boxouts and Tables |
Listings longer than a couple of lines should be in a separate Listing boxout. Make sure that you supply only complete (that is executable) scripts and sourcefiles, as they will be made available to our readers.
Boxouts always have a title(@KT:). Normal text in a boxout is boxout text (@KL:). Listings in boxouts are still formatted using @LI::
@KT:Listing 1: xy.c ... |
In addition to code, boxouts can contain additional information, such as glossaries, interviews, or a different aspect of the main topic that does not fit into the main body of text.
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:
@TT:Table 1: Character |
You can save tables as spreadsheets (.csv or similar) to help ensure the correct formatting.
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:
@IT:Info
[2] Carl Corner: The Kernel -- Compiling Made Easy, |
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:
@IT:The Author |
Typical Problems |
- too many abbreviations (e.g., etc.)
- 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
- figures, tables, boxouts not referenced in the text
- no subtitles, or subtitles too short
- file formats, such as HTML or PDF, instead of plain text
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
Latest Cinnamon Desktop Releases with a Bold New Look
Just in time for the holidays, the developer of the Cinnamon desktop has shipped a new release to help spice up your eggnog with new features and a new look.
-
Armbian 24.11 Released with Expanded Hardware Support
If you've been waiting for Armbian to support OrangePi 5 Max and Radxa ROCK 5B+, the wait is over.
-
SUSE Renames Several Products for Better Name Recognition
SUSE has been a very powerful player in the European market, but it knows it must branch out to gain serious traction. Will a name change do the trick?
-
ESET Discovers New Linux Malware
WolfsBane is an all-in-one malware that has hit the Linux operating system and includes a dropper, a launcher, and a backdoor.
-
New Linux Kernel Patch Allows Forcing a CPU Mitigation
Even when CPU mitigations can consume precious CPU cycles, it might not be a bad idea to allow users to enable them, even if your machine isn't vulnerable.
-
Red Hat Enterprise Linux 9.5 Released
Notify your friends, loved ones, and colleagues that the latest version of RHEL is available with plenty of enhancements.
-
Linux Sees Massive Performance Increase from a Single Line of Code
With one line of code, Intel was able to increase the performance of the Linux kernel by 4,000 percent.
-
Fedora KDE Approved as an Official Spin
If you prefer the Plasma desktop environment and the Fedora distribution, you're in luck because there's now an official spin that is listed on the same level as the Fedora Workstation edition.
-
New Steam Client Ups the Ante for Linux
The latest release from Steam has some pretty cool tricks up its sleeve.
-
Gnome OS Transitioning Toward a General-Purpose Distro
If you're looking for the perfectly vanilla take on the Gnome desktop, Gnome OS might be for you.