With anyone on the internet able to create and edit pages on this wiki, pages could be created in a large number of different styles. This page is intended to suggest a "house style" for the wiki to ensure readability, especially in the longer articles. There are a number of formatting tools available to those writing pages on the wiki. They are documented on the http://www.usemod.com/cgi-bin/wiki.pl?[[TextFormattingRules|TextFormattingRules]] page of the UseModWiki website. This page is not intended as an instruction on how to use these rules, but rather to suggest how they can be used to produce a nicely presented and readable wiki page.

Page Titles

The title of every page is displayed in large text at the top of the screen, above the HomePage, RecentChanges and Preferences links. When reading a page, the title itself is a wiki link that shows "back links" to that page when clicked. (When editing a page, it is prefixed with the word "Editing", and is not a wiki link.) It is not, therefore, necessary to duplicate the title of the page within the page's content, as it is already displayed in "large, friendly letters" at the top of the screen.

Headings

There are four types of heading available in wiki pages, defined in a style sheet. The headers are produced as <h1> to <h4> style headers in the HTML produced by the wiki. All the header tags are in the same font and emboldened. They differ only in two respects: size and alignment. The <h1> tag is set at 16pt and the subsequent headers decrement at 2pts a time. The <h1> and <h2> tags are centre aligned, whilst the <h3> and <h4> tags are left aligned.

The <h1> and <h2> tags are used by the wiki for producing parts of the page format, most obviously the page title in the case of the former and important information like the "Preview:" header in the case of the latter. Only the <h3> and <h4> tags should therefore be used in wiki page content. <h3> should be used for section headings, for example "Preparing a Hard Disk" in a "tutorial" page or "HTML Editing Software" in a software listing page. The <code<h4></code> tag should be used for sub-headings within a section. "Creating partitions" and "Formatting partitions" might be examples in the former example, "Bluefish" and "vi" in the latter. Ensuring headers are used correctly makes the page more readable and helps the page develop a structure.

Capitalising letters degrades the readability of a header and should be avoided.

Headings are created by enclosing a comment in a number of equals signs, for example === My Header ===. (The spaces between the equals signs and the header content are important!) One pair of equals signs becomes an <h1> tag, two pairs of equals signs becomes an <h2> tag, all the way up to <h4>.

Obviously, the actual appearance of these tags will vary, and is beyond the control of the page writer, if users have their browser configured to use a client-side style sheet, or specified a different style sheet in the Preferences section of the wiki.

Horizontal Lines

Horizontal lines can be used very effectively to break up pages into small sub-sections. They are created using a string of at least four minus signs. You might want to use a horizontal line to separate comments or notes from the main content on a page.

Including Code

A lot of pages on this wiki include extracts from software code or text typed at the terminal in a monospace font. A similar font can be used on the wiki to help the reader distinguish between what should be typed at a terminal and what is explantory text. There are two ways of achieving this effect. One is to include &lt;code&gt; and &lt;/code&gt; tags around single words and phrases in a sentence, like this:

:Enter the command fdisk /dev/hda at the command prompt.

The second way is more suitable for larger sections of code or terminal responses. This involves placing the &lt;pre&gt; and &lt;/pre&gt; tags around the text. This creates consistently spaced output, similar to that displayed on the terminal, like this:

-rw-r--r--    1 tony     tony         2018 Feb 14 17:33 network.dia
-rw-r--r--    1 tony     tony         2018 Feb 14 17:28 network.dia~
-rw-------    1 tony     tony          746 Apr 12 03:00 nohup.out
-rw-r--r--    1 tony     tony           62 Apr  9 18:57 remotemail
-rw-------    1 tony     tony       127203 Apr  9 11:03 scanModem

Identifying your changes

There are some circumstances where a line stating major contributors to a page might be justified. For example, if one or more people have contributed to a long document, an attribution at the end of the page will not intrude into the reading of the text. More problematic are identifiers on comments and pages that include personal opinions.

When pages have been written from the perspective of an individual (for example, "I found that this software was no good") are edited by other people also writing the first person, the "voice" of the author can become confused in the mind of the reader. One common way that people try to get round this problem is to insert tags after a comment that they have made, for example:

"This new software from Mega Corporation is great, it makes my Linux system run 10 times faster than before. Not only that but it has helped me get several other people using Linux too!

:Fans of Free Software should be aware that the new software from Mega Corporation is not distributed under the GPL and you may be required to give your house to Mega Corporation in the event that they discover you've copied their software illegally. -- SomeUser

::I read on slashdot that this is just rubbish and that you can sue Mega Corporation if they try to take away your house! -- AnotherUser"

Perhaps it is best to avoid this type of comment entirely. For most types of documents, comments can be worded in the third person and included "in-line" with the existing comments. If you feel it is important to identify that you made a certain comment then try to picture the page in its entirety, as viewed by a new reader, perhaps one who has come across the wiki via a search engine. A mess of nested comments does not make the page easy to read!

Adding comments to a page that you attribute to others is also inadvisable, particularly if they were not expecting their comments to be included on a public website. This is can be a problem when summarising comments from the MailingList, for example the LinuxHints/BudgetLaserPrinter page. Some LUG members do not consider the MailingList to be a publicly accessible source of information and may not want their comments made in a more public forum. Anyone attributing comments on the wiki to other people should be sure to get their permission first.

StyleGuide (last edited 2010-05-28 17:05:10 by AdamTrickett)