Linux Magazine Markup

Linux Magazine uses a simple scheme for marking up text. The scheme allows for emphasis of words, phrases, and product names; delineates blocks of code; and creates simple tables, among other things.

The marked-up text that you submit is then edited and ultimately processed by tools that produce the printed page (with the help of Quark) and HTML for the web site.

The Linux Magazine scheme is similar in spirit to the Plain Old Documentation (POD) format used in Perl documentation, and like POD, the intent is simplicity, not power. You need not learn an extensive vocabulary to write for Linux Magazine.

All articles have headers, sections of text separated by subheads, and may include special elements such as listings, figures, screen shots, and tables. All articles must end with a bio of you, the author.

Headers

All articles must start with four headers: HEAD, DECK, TOC_LINE, and AUTHOR.

• HEAD. This is the title of the piece. For columns, this is the name of the column. For features, this can be slightly humourous. Since this is a title, the HEAD should use title case.

• DECK. This is a short subtitle of less than ten words. For features, if the HEAD was humorous, then the DECK should be more serious and “academic.” The DECK should be written in sentence case and should omit the trailing period.

• TOC_LINE. This is a 25-40 word blurb that describes the article. It’s best if this is catchy to draw the attention of the reader.

• AUTHOR. Your name goes here.

Here’s an example:

HEAD: XML Schema Languages

DECK: Why and how to validate your XML
documents

TOC_LINE: Validating XML documents reduces
stress. Here are four different ways to do
it.

AUTHOR: Norman Walsh

Subheads

SUBHEAD: Framebuffer Kernel Options

To use framebuffer support, you must enable
it in your kernel. Many distributions ship
with this support active, but it’s easy to
disable it when you recompile your kernel. In
fact, if you don’t know what the options do,
it’s often safer to disable the framebuffer
support when you recompile your kernel.
Incorrect configurations can easily result in
completely black displays when you boot.

Text Effects

* B Choose
the fastest processor you can afford.

* B With disk
prices dropping to less than $1 per gigabyte,
stock up on hard disk space. 

Doing C< sort | uniq -c> would work,
but do you want to do this?  The following
code accomplishes the same thing. 

C<
perl -e ‘$c{$_}++ foreach (); 
	printf(“%7d %s”, $c{$_}, $_) foreach (sort keys %c);’
>

Sidebars

< BEGIN Sidebar One -- “Scheme vs. Lisp” >

To the uninitiated, Scheme and Lisp look a lot alike, but looks
can be deceiving.  There are actually quite a few differences
between these two languages.

< END >

Code Listings

The canonical “Hello, world!” program can be seen in Listing 1.

< BEGIN Listing One -- The “Hello, world!” program in Ruby >

C<
1 blah blah blah blah blah
2 blah blah blah blah blah
3 blah blah blah blah blah
4 blah blah blah blah blah
…
10 blah blah blah blah blah
>

< END >

Figures

A screen shot of this amazing thing can be seen in I


< BEGIN Figure One -- Screen shot of something  >
< INSERT FILE: screenshot.png >
< END Figure One >

Command Sequences

Now run the following commands:

C<
$ su2
Password: xxxxxx
# wall ‘Hello, everybody!’
>

Tables

< BEGIN Table One -- Tomcat environment variables >

Environment variable|Value

C|Your Java installation
directory.

C|The Tomcat installation
directory.

C|Command line switches to
pass to the Java Runtime Environment.

< END >

Biography

BIO: Glenn McAllister is a part-time
committer on the Jakarta Ant project.  He can
be reached at glenn@somanetworks.com.

Comments

[MS: this is a comment from Martin Streicher ]

[Ed.: This is a different comment notation ]

Miscellaneous

You can use I or

Gotchas and Suggestions