IEEE

Help:Wikitext Formatting and Style Guide

SHARE |

From GHN

Jump to: navigation, search

The below formatting guide and manual of style is for editing the GHN in either Wikitext mode or with the Rich Text Editor disabled. The Rich Text Editor will attempt to view pages as they will show up and can insert unneeded formatting and can often be difficult to get a precise fit. The Wiki markup text is the preferred way to edit pages on the GHN.

It is recommend that when editing the GHN, the user has multiple tabs open so they can easily access the search engine, other relevant pages and lists and cut and paste text into the edit window to avoid typos. The GHN is case sensitive when it comes to article and file names.

When writing a topic article, it is recommended that the tone and technical level of the article be on a level that can be easily understood by the tech-savvy general public. For more detailed technical references and explanations, these should be in the form of attachments and references for those curious to read further.

Contents

General Formatting

'''(text)''' - will bold text

''(text)'' – will italicize text

<u>(text)</u> - will underline text

<blockquote>(text)</blockquote> - will indent text for longer quotes

Headers

Headers are defined by equal signs on each side of text. The largest possible header is:

= (text) =

This header should not be used and is typically reserved for page titles. The second largest header is:

== (text) ==

the third largest is is:

=== (text) ===

Each smaller header will be automatically indexed as a subheader when the table of contents is generated. It is recommended that == be the largest header used on the GHN. Only plain text should be contained in headers, do not link to anything, bold or italicize headers.

General Notes on Headers

Headers should only separate significant chunks of content. For biographies, do not break down each paragraph into separate headers. External links and sources should be under their own header called “Further Reading” at the end, which should be separate from “References”.

Linking

To a page on the GHN:

[[(link destination)|(how link appears in text)]]

To link to the Bell Labs page:

[[Bell Labs|Bell Telephone Laboratories]]

The link destination must exactly match the page title. For pages outside of the Main name space, such as Oral Histories, First Hand Histories, STARS and Milestones, you must specify the namespace prefix.

For example, to link to Thelma Estrin’s oral history:

[[Oral-History:Thelma Estrin|Thelma Estrin Oral History]] - will appear as Thelma Estrin Oral History

To link directly to a category page on the GHN:

[[:Category:(category)|(how link appears in text)]]

So to link to the category Automation, use:

[[:Category:Automation|a list of articles pertaining to automation]] - appears as a list of articles pertaining to automation.

To categorize an article rather than link to the category, see the Categorization section

To link to a page off of the GHN:

[(link destination) (how link appears in text)]

so to link to Google, one would type:

[http://www.google.com Search the Web] - appearing as Search the Web

General Notes on Linking

All external links off of the GHN and related items (archival materials, oral histories, milestones etc) to the topic should be listed under a header at the end called “Further Reading”. As many internal links should be included in an article as possible – good candidates for these would be proper nouns.

Lists and Spacing

Bulleted Lists

For bulleted lists, use the format of:

*item 1
*item 2
**item 2.1
*item 3
*item 4

which will appear as:

  • item 1
  • item 2
    • item 2.1
  • item 3
  • item 4

Numbered Lists

For numbered lists, use:

#item 1
#item 2
##item 2.1
##item 2.2
#item 3
#item 4

which will appear as:

  1. item 1
  2. item 2
    1. item 2.1
    2. item 2.2
  3. item 3
  4. item 4

General Spacing Notes

Do not space items with <br> tags. The GHN will automatically between paragraphs. Do not indent text.

Images and Supporting Documents

Inline photos

To make a photo appear inline, use:

[[Image:(filename)|(mode)|(justification)|(size)|(caption)]]

Mode can be thumb or frame. Thumb displays a thumbnail and is preferred almost all the time. Justification can be either left, center or right. In most cases, aside from when the table of contents is appearing, right justification should be used. Size is in the format of (pixels)px, and goes by the width of a picture. So to display a photo at 400 pixels, use “400px” for the size field.

To insert a picture of Charles Babbage with a right justified thumbnail, use:

[[Image:Babbage.jpg|thumb|right|Charles Babbage]]

which will appear to the right.

Charles Babbage
Charles Babbage

Direct linking

To link directly to an image or document, use:

[[Media:(filename)|(caption)]]

So to link to Hering_-_wattless_flux.pdf, use:

[[Media:Hering_-_wattless_flux.pdf|Wattless Flux, by Carl Hering]]

which appears as:

Wattless Flux, by Carl Hering

This is the preferred way to link to a non-image supporting document, including Acrobat .pdf files, Word documents, spreadsheets or powerpoints. It is preferred that images be inserted in the article themselves.

Metadata linking

To link directly to an image or document’s metadata page, use:

[[:Image:(filename)|(appearance in text)]]

So to link to the metadata page for Zworykin.jpg, use:

[[:Image:Zworykin.jpg|A picture of Vladimir Zworykin]]

which will appear as:

A picture of Vladimir Zworykin

This should rarely be used, but in the case that it is, it will typically be more for documents. When a picture is displayed inline, it typically enhances the article and the thumbnail will automatically link to the Metadata page, so this is the preferred way of displaying a picture.

Multimedia

Audio

To insert an mp3 on the GHN, use the code:

<flashmp3>(filename)</flashmp3>

So to insert the file “138 - beverage - clip 1.mp3”, use the tag:

<flashmp3>138 - beverage - clip 1.mp3</flashmp3>

which appears as:

Flash video (local)

To insert a flash video on the GHN, use the code:

<flvplayer>(filename)|(height)|(width)</flvplayer>

432x282 is typically used as height and width for videos embedded on the GHN. To imbed Larson Collection - 50 - Packard.flv, use:

<flvplayer>Larson Collection - 50 - Packard.flv|432|282</flvplayer>

which appears as:

Video from IEEE.tv

To imbed videos hosted on IEEE.tv, use the following tag:

<ieeetv>progId=(video id)|width=(width)</ieeetv>

IEEE.tv allows the option to share the video – under the “Share” tab, you can see the “Embed” tab. Here you will find the embed link code, an example of which is: <script type="text/javascript" src="http://ieeetv.ieee.org/player/embed.js?video_id=127666&width=500"></script>

The ID appearing after the “video_id=” tag is the video id tag, so in this case it would be “127666”. To embed this video on the GHN, use:

<ieeetv>progId=127666|width=500</ieeetv>

which appears as:

Video from YouTube

To embed a video from YouTube, use the format:

<youtube>(video id)</youtube>

The video id appears in the end of the URL. For example:

http://www.youtube.com/watch?v=B8DwthVf-Wg

Links to a video of Morton Subotnick’s “Silver Apples of the Moon”, the first electronic record commissioned by a record company. The video id appears after the v= statement, in this case would be “B8DwthVf-Wg”. So to embed this on the GHN, one would use:

<youtube>B8DwthVf-Wg</youtube>

which appears as:

Tables

Tables can be inserted in the text using the following format:

{| cellspacing="1" cellpadding="1" width="(size)" border="1"
|-
| (text)
| (text)
|-
| (text)
| (text)
|}

Tables can be of any size with as many columns. Each space between the – rows will indicate a different column, and a – will indicate a break in row. For example, the beginning of a table used in for section chairs:

{| cellspacing="1" cellpadding="1" width="600" border="1"
|-
| '''Period'''
| '''Name of the Chair'''
|-
| 1995-1996
| Dr. A. K. Aggarwal
|}

Which will appear as:

Period Name of the Chair
1995-1996 Dr. A. K. Aggarwal

Tables must be closed with the } character on the last line.

Table Templates

2x2:

{| cellspacing="1" cellpadding="1" width="600" border="1"
|-
| '''Column 1'''
| '''Column 2'''
|-
|
|
|}

3x3:

{| cellspacing="1" cellpadding="1" width="600" border="1"
|-
| '''Column 1'''
| '''Column 2'''
| '''Column 3'''
|-
|
|
|
|-
|
|
|
|}

4x4:

{| cellspacing="1" cellpadding="1" width="600" border="1"
|-
| '''Column 1'''
| '''Column 2'''
| '''Column 3'''
| '''Column 4'''
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Categorization

The extension SelectCategory will show a hierarchical tree of all the categories you can choose to tag an article on the GHN. However, right now it does not allow the user to select an appropriate index term. We would like to integrate this function in the future.

However, in the meantime all categorization done through checking the boxes in the category tree will index by the first letter of the article title. This is appropriate for such terms like Transistors, Capacitors, Electricity, or other subjects like this. It is not appropriate for proper nouns such as Thomas Edison, Charles Townes or George Westinghouse, nor is appropriate for articles with titles like “Early History of Electricity” or “Wartime applications of Radar”.

Proper nouns should be indexed by last name, so the index term for Thomas Edison would be “Edison”, and the index term for Charles Townes would be “Townes”. Articles like “Early History of Electricity” should be indexed by technical subject, so this would be indexed under “Electricity”, likewise “Wartime applications of Radar” would be indexed under “Radar”. IEEE Organizational Units should be indexed by the first letter of the proper name of the unit, so “IEEE Karachi Section History” would be indexed under “Karachi”.

For cases like “Transistors”, “Capacitors”, etc where the first letter of the article title is sufficient, check any appropriate categories in the category tree. Select as many or as few as needed to describe the article in question – use your judgment, typically any subject mentioned in any amount of detail beyond a passing mention may be worth tagging.

For cases where it is not appropriate to use the first letter of the article title, use the following format:

[[Category:(category name)|(index term)]]

Currently the categorization for Franklin Pope is:

[[Category:Telegraphy|Pope]] [[Category:Energy|Pope]] [[Category:Power generation|Pope]]

Unless the categorization of current pages is wrong, do not remove categories from the article.

References

References should use the Cite extension which allows for easy inline references. To create a reference in the text, use the code:

<ref>(reference text)</ref>

So to insert the citation "Dr. Michael I. Pupin Dies in Coma at 76, " New York Times, Mar. 13, 1935., use:

<ref>"Dr. Michael I. Pupin Dies in Coma at 76, " New York Times, Mar. 13, 1935.</ref>

To use a citation more than once, first give it a name:

<ref name="(refname)">(text)</ref>

So "Dr. Michael I. Pupin Dies in Coma at 76, " New York Times, Mar. 13, 1935. would become:

<ref name="pupin"> "Dr. Michael I. Pupin Dies in Coma at 76, " New York Times, Mar. 13, 1935.</ref>

and to use it again, use:

<ref name="pupin" />

To list the references at the end of the article, use the tag:

<references />

This should be under its own section called “References”. See the section on Headers for information on how to format this.