DLXS Style Guide

From DLXS Documentation

(Difference between revisions)
Jump to: navigation, search
(→Linking)
Current revision (18:17, 9 July 2008) (edit) (undo)
(→DLXS Custom Styles)
 
(56 intermediate revisions not shown.)
Line 1: Line 1:
-
<big><font color= "green">(DRAFT! a work in progress)</font></big>
+
= Basic Wiki Formatting =
 +
== Creating New Pages ==
 +
To create a new page, simply begin by editing a current page and enter the markup to link to the page you want to create. <nowiki>[[Name of page]]</nowiki>. Save the current page and then click on the red link to go directly to the edit mode of the new page.
-
= Basics =
 
== Page Titles ==
== Page Titles ==
Line 8: Line 9:
Pages pertaining to specific classes should include that class in their page title. Ex. “Mounting the Collection Online” should be "Mounting the Text Class Collection Online."
Pages pertaining to specific classes should include that class in their page title. Ex. “Mounting the Collection Online” should be "Mounting the Text Class Collection Online."
 +
 +
== Sections & Paragraphs ==
 +
 +
{| cellpadding="15" cellspacing="0" border="1"
 +
|-
 +
|'''Sections:''' using four or more headers on a page will create a table of contents (TOC) to appear in front of the first header.
 +
|<pre><nowiki>
 +
= Section =
 +
 +
== Sub-section ==
 +
 +
=== Sub-sub-section ===
 +
 +
==== Sub-sub-sub-section ====
 +
</nowiki></pre>
 +
|-
 +
|'''Paragraphs:''' leave a blank line between paragraphs
 +
|<pre><nowiki>Line one
 +
 +
Line two</nowiki></pre>
 +
|}
 +
== Text Formatting ==
== Text Formatting ==
Line 17: Line 40:
! Example
! Example
|-
|-
-
|Citation
+
|Bold
-
|Use when you need to display code that is used by the wiki
+
|
-
|<nowiki><cite>lorem ipsum</cite></nowiki>
+
|<nowiki>'''Bold text'''</nowiki>
-
|<cite>lorem ipsum</cite>
+
|'''Bold text'''
|-
|-
-
|pre
+
|Italic
-
|Use when displaying '''large chunks of code''' that you want to set apart from rest of text
+
|
-
|<nowiki><pre>lorem ipsum</pre></nowiki>
+
|<nowiki>''Italicized text''</nowiki>
-
|<pre>lorem ipsum</pre>
+
|''Italicized text''
|-
|-
-
|code
+
|Bold & Italic
 +
|
 +
|<nowiki>'''''Italicized & Bold text'''''</nowiki>
 +
|'''''Italicized & Bold text'''''
 +
|-
 +
|Inline code
|Use when displaying '''in line code''' (code embedded in other text) and '''names of scripts'''
|Use when displaying '''in line code''' (code embedded in other text) and '''names of scripts'''
|<nowiki>This is a sentence with <code>a bit of code</code> in it.</nowiki>
|<nowiki>This is a sentence with <code>a bit of code</code> in it.</nowiki>
|This is a sentence with <code>a bit of code</code> in it.
|This is a sentence with <code>a bit of code</code> in it.
|-
|-
-
|nowiki
+
|Blocks of code
-
|Use when you need to display code that is used by the wiki
+
|Use when you want to display large blocks of code and keep original formatting. ''<nowiki><code> should always go outside <pre></nowiki>''
-
|<nowiki><nowiki><code>lorem ipsum</code></nowiki></nowiki>
+
|<nowiki><code><pre><ul>
-
|<nowiki><code>lorem ipsum</code></nowiki>
+
<li class="list">list item 1</li>
 +
<li class="list">list item 2</li>
 +
</ul></pre></code></nowiki>
 +
|<code><pre><ul>
 +
<li class="list">list item 1</li>
 +
<li class="list">list item 2</li>
 +
</ul></pre></code>
 +
|-
 +
|Keep original formatting of text (not for code)
 +
|Use when displaying '''non-code text''' that you want to set apart from rest of text. ''(This can also be done with leading spaces, but is not recommended).''
 +
|<nowiki><pre>lorem
 +
ipsum</pre></nowiki>
 +
|<pre>lorem
 +
ipsum</pre>
 +
|-
 +
|Show wiki markup
 +
|Use when you need to display code that is used by the wiki.
 +
|<nowiki><nowiki><markup>lorem ipsum</markup></nowiki></nowiki>
 +
|<nowiki><markup>lorem ipsum</markup></nowiki>
|-
|-
|strikethrough
|strikethrough
-
|Use when you want to indicate that something no longer applies, but don't want to delete it yet
+
|Use when you want to indicate that something no longer applies, but don't want to delete it yet.
|<nowiki><strikethrough>lorem ipsum</strikethrough></nowiki>
|<nowiki><strikethrough>lorem ipsum</strikethrough></nowiki>
|<strike>lorem ipsum</strike>
|<strike>lorem ipsum</strike>
 +
|-
 +
|Citations
 +
|Use when you cite another source.
 +
|<nowiki><cite>lorem ipsum</cite></nowiki>
 +
|<cite>lorem ipsum</cite>
 +
|-
 +
|block quote
 +
|For a long citation (not for code) that you want indented.
 +
|<nowiki><blockquote>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Integer eget sapien eu libero porttitor eleifend. Mauris ornare nunc a ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos.</blockquote></nowiki>
 +
|<blockquote>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Integer eget sapien eu libero porttitor eleifend. Mauris ornare nunc a ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos.</blockquote>
|}
|}
Line 69: Line 125:
|<nowiki>[[DLXS_style_guide#Advanced_Markup|Advanced]]</nowiki>
|<nowiki>[[DLXS_style_guide#Advanced_Markup|Advanced]]</nowiki>
|[[DLXS_style_guide#Advanced_Markup|Advanced]]
|[[DLXS_style_guide#Advanced_Markup|Advanced]]
 +
|-
 +
|Link to an external (non-wiki) source
 +
|<nowiki>[http://en.wikipedia.org Wikipedia]</nowiki>
 +
|[http://en.wikipedia.org Wikipedia]
 +
|-
|}
|}
 +
== Lists ==
 +
{| cellpadding="15" cellspacing="0" border="1"
 +
! Type
 +
! Markup
 +
! Example
 +
|-
 +
|Bullet list
 +
|<pre><nowiki>
 +
* Item 1
 +
** Item 1.1
 +
** Item 1.2
 +
* Item 2
 +
** Item 2.1
 +
*** Item 2.1.1
 +
*** Item 2.1.2
 +
*** Item 2.1.3
 +
** Item 2.2
 +
* Item 3</nowiki></pre>
 +
|
 +
* Item 1
 +
** Item 1.1
 +
** Item 1.2
 +
* Item 2
 +
** Item 2.1
 +
*** Item 2.1.1
 +
*** Item 2.1.2
 +
*** Item 2.1.3
 +
** Item 2.2
 +
* Item 3
 +
|-
 +
|Numbered list
 +
|<pre><nowiki>
 +
# Item 1
 +
## Item 1.1
 +
## Item 1.2
 +
# Item 2
 +
## Item 2.1
 +
### Item 2.1.1
 +
### Item 2.1.2
 +
### Item 2.1.3
 +
## Item 2.2
 +
# Item 3</nowiki></pre>
 +
|
 +
# Item 1
 +
## Item 1.1
 +
## Item 1.2
 +
# Item 2
 +
### Item 2.1
 +
### Item 2.1.1
 +
### Item 2.1.2
 +
### Item 2.1.3
 +
## Item 2.2
 +
# Item 3
 +
|}
-
The preferable way of linking to a file is: (everything before the pipe won't show)
 
-
<pre>
 
-
<nowiki>
 
-
[[Sample Makefile.html|Makefile.html click here]]
 
-
</nowiki>
 
-
</pre>
 
 +
== Tables ==
 +
You can use wiki table formatting '''or''' html table formatting
-
and '''NOT''':
+
{| cellpadding="15" cellspacing="0" border="1"
-
<pre>
+
|-
-
<nowiki>
+
|
-
"For more information about the [[Makefile.html click here]]."
+
<pre><nowiki><table cellpadding="5" cellspacing="0" border="1">
-
</nowiki>
+
<tr>
-
</pre>
+
<th>heading 1</th>
-
This isn't the best way to create a new page because it names the page whatever is in the brackets, and then forevermore you have to remember that it's not called "Sample Makefile.html" or something more intuitive when you want to link to it.
+
<th>heading 2</th>
 +
</tr>
 +
<tr>
 +
<td>cell 1</td>
 +
<td>cell 2</td>
 +
</tr>
 +
</table></nowiki></pre>
 +
|
 +
<table cellpadding="5" cellspacing="0" border="1">
 +
<tr>
 +
<th>heading 1</th>
 +
<th>heading 2</th>
 +
</tr>
 +
<tr>
 +
<td>cell 1</td>
 +
<td>cell 2</td>
 +
</tr>
 +
</table>
 +
|-
 +
|<pre><nowiki>
 +
{| cellpadding="15" cellspacing="0" border="1"
 +
|-
 +
!heading 1
 +
!heading 2
 +
|-
 +
|cell 1
 +
|cell 2
 +
|}
-
== Comments ==
+
OR
 +
{| cellpadding="15" cellspacing="0" border="1"
 +
|-
 +
!heading 1 !! heading 2
 +
|-
 +
|cell 1 || cell 2
 +
|}</nowiki></pre>
 +
|
 +
<table cellpadding="5" cellspacing="0" border="1">
 +
<tr>
 +
<th>heading 1</th>
 +
<th>heading 2</th>
 +
</tr>
 +
<tr>
 +
<td>cell 1</td>
 +
<td>cell 2</td>
 +
</tr>
 +
</table>
 +
|}
-
= Advanced Markup =
 
 +
== Images ==
 +
 +
[[Special:Upload|DLXS wiki upload page]]
 +
 +
[[Special:Imagelist|DLXS wiki list of uploaded images]]
{| cellpadding="15" cellspacing="0" border="1"
{| cellpadding="15" cellspacing="0" border="1"
! Style
! Style
-
! When to use
 
! Markup
! Markup
! Example
! Example
|-
|-
-
|bug
+
|Basic image w/custom alt text
-
|[for use by DLXS staff only] use to alert users that there is a known bug in the software
+
|<nowiki>[[Image:DLXSlogo.gif|The DLXS logo]]</nowiki>
-
|<nowiki><div class="bug">'''Bug:''' We're working on it.</div></nowiki>
+
|[[Image:DLXSlogo.gif|The DLXS logo]]
-
|<div class="bug">'''Bug:''' We're working on it.</div>
+
|-
|-
-
|release
+
|Image w/custom alt text & floated to write
-
|[for use by DLXS staff only] Additions about a forthcoming release should just be added to any relevant pages as a new paragraph. Header tags should also be used and the paragraph should be given a title "Release X" so it can be easily searched and integrated when the release is ready.
+
|<nowiki>[[Image:DLXSlogo.gif|right|The DLXS logo]] Here is the DLXS logo floated to the right, if you put the image before the text, the text should wrap around it like this.</nowiki>
 +
|[[Image:DLXSlogo.gif|right|The DLXS logo]]Here is the DLXS logo floated to the right, if you put the image before the text, the text should wrap around it like this.
 +
|-
 +
|Resize image
 +
|<nowiki>[[Image:DLXSlogo.gif|100px|The DLXS logo]]</nowiki>
 +
|[[Image:DLXSlogo.gif|100 px|The DLXS logo]]
 +
|-
 +
|Link directly to an image without displaying it:
 +
|<nowiki>[[:media:DLXSlogo.gif|Image of the DLXS logo]]</nowiki>
 +
|[[:media:DLXSlogo.gif|Image of the DLXS logo]]
 +
|}
 +
 
 +
 
 +
 
 +
== Hidden Comments ==
 +
 
 +
You can comment in the wiki the same way you would comment in html. Use when you want to leave comments that can only be seen when editing the page.
 +
 
 +
<nowiki><!-- comment here --></nowiki>
 +
 
 +
 
 +
= DLXS Custom Styles =
 +
 
 +
 
 +
{| cellpadding="15" cellspacing="0" border="1"
 +
! Style
 +
! When to use
 +
! Markup
 +
! Example
 +
|-
 +
|future release
 +
|[for use by DLXS staff only] Additions about a forthcoming release should just be added to any relevant pages as a new paragraph. '''Be sure to include the word 'Release_X'''' (X being the release number) for easy searching and integration when the release is ready.
|<nowiki><div class="release">
|<nowiki><div class="release">
-
'''Release X'''
+
'''Release_X:'''
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Praesent velit.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Praesent velit.
</div></nowiki>
</div></nowiki>
|<div class="release">
|<div class="release">
-
'''Release X'''
+
'''Release_X:'''
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Praesent velit.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Praesent velit.
</div>
</div>
|-
|-
-
|tip
+
|DLXS staff only note
-
|Use to describe a tip for a particular procedure
+
|Use to describe a note, tip or warning for a particular procedure.
-
|<nowiki><div class="tip">'''Tip:''' I found that doing x first really helps -suz</div></nowiki>
+
'''Be sure to include the label 'DLXS_Tip', 'DLXS_Warning', or 'DLXS_Note' to make searching for these items easier.'''
-
|<div class="tip">'''Tip:''' I found that doing x first really helps -suz</div>
+
<span class="redtext">For use by U-M DLXS staff only</span>.
 +
|<nowiki><div class="tip">'''DLXS_Tip:''' Make sure you first blah blah blah. </div></nowiki>
 +
|<div class="tip">'''DLXS_Tip:''' Make sure you first blah blah blah.</div>
|-
|-
|note
|note
-
|Use if you just want to describe something and have it stand out a bit more
+
|Use to describe a note or tip for a particular procedure. Use of this style is highly encouraged - especially by DLXS partners. '''Note the use of tilda (<nowiki>~~~</nowiki>) to indicate author'''.
-
|<nowiki><div class="note">'''Note:''' Make sure you first blah blah blah.</div></nowiki>
+
|<nowiki><div class="note">'''Note:''' I found that by doing x first blah blah blah. ~~~</div></nowiki>
-
|<div class="note">'''Note:''' Make sure you first blah blah blah.</div>
+
|<div class="note">'''Note:''' I found that by doing x first blah blah blah. [[User:Suzchap|Suzchap]]</div>
 +
|-
 +
|workshop
 +
|Used by DLXS staff only to indicate that content is applies to the workshop only
 +
|<nowiki><div class="workshop">'''Workshop:''' Go to directory foobar blah blah blah.</div></nowiki>
 +
|<div class="workshop">'''Workshop:''' Go to directory foobar blah blah blah.</div>
|-
|-
|Red Text
|Red Text
Line 137: Line 333:
|Here's what I have to say about <span class="greentext">this</span> and that's all.
|Here's what I have to say about <span class="greentext">this</span> and that's all.
|}
|}
 +
 +
= Templates for page status =
 +
 +
There are currently 2 templates that can be applied to any page to signal a page's status.
 +
 +
To assign a template to a page, enter the markup below to the top of the page.
 +
 +
 +
<nowiki>{{WorkInProgress}}</nowiki> will display:
 +
 +
{{WorkInProgress}}
 +
 +
 +
<nowiki>{{NeedsReview}}</nowiki> will display:
 +
{{NeedsReview}}
 +
 +
 +
 +
<div class="tip">'''Tip:''' To find wiki articles that use these templates - use the following URL's:
 +
[[Special:Whatlinkshere/Template:NeedsReview]]
 +
 +
[[Special:Whatlinkshere/Template:WorkInProgress]]
 +
 +
 +
</div>

Current revision

Contents

[edit] Basic Wiki Formatting

[edit] Creating New Pages

To create a new page, simply begin by editing a current page and enter the markup to link to the page you want to create. [[Name of page]]. Save the current page and then click on the red link to go directly to the edit mode of the new page.


[edit] Page Titles

For consistency, major words in all page titles should be in capital letters.

Pages pertaining to specific classes should include that class in their page title. Ex. “Mounting the Collection Online” should be "Mounting the Text Class Collection Online."

[edit] Sections & Paragraphs

Sections: using four or more headers on a page will create a table of contents (TOC) to appear in front of the first header. 
= Section =

== Sub-section ==

=== Sub-sub-section ===

==== Sub-sub-sub-section ====
Paragraphs: leave a blank line between paragraphs 
Line one

Line two


[edit] Text Formatting

Style When to use Markup Example
Bold '''Bold text''' Bold text
Italic ''Italicized text'' Italicized text
Bold & Italic '''''Italicized & Bold text''''' Italicized & Bold text
Inline code Use when displaying in line code (code embedded in other text) and names of scripts This is a sentence with <code>a bit of code</code> in it. This is a sentence with a bit of code in it.
Blocks of code Use when you want to display large blocks of code and keep original formatting. <code> should always go outside <pre> <code><pre><ul> <li class="list">list item 1</li> <li class="list">list item 2</li> </ul></pre></code> 
<ul>
  <li class="list">list item 1</li>
  <li class="list">list item 2</li>
</ul>
Keep original formatting of text (not for code) Use when displaying non-code text that you want to set apart from rest of text. (This can also be done with leading spaces, but is not recommended). <pre>lorem ipsum</pre> 
lorem 
     ipsum
Show wiki markup Use when you need to display code that is used by the wiki. <nowiki><markup>lorem ipsum</markup></nowiki> <markup>lorem ipsum</markup>
strikethrough Use when you want to indicate that something no longer applies, but don't want to delete it yet. <strikethrough>lorem ipsum</strikethrough> lorem ipsum
Citations Use when you cite another source. <cite>lorem ipsum</cite> lorem ipsum
block quote For a long citation (not for code) that you want indented. <blockquote>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Integer eget sapien eu libero porttitor eleifend. Mauris ornare nunc a ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos.</blockquote>
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Integer eget sapien eu libero porttitor eleifend. Mauris ornare nunc a ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos hymenaeos.

[edit] Linking

Style Markup Example
Link to another wiki page Go to [[Installing_DLXS]] Installing_DLXS
Link to another wiki page but have the link say something different Go to [[Installing_DLXS|DLXS installation]] DLXS installation
Link to a section within another wiki page [[Installing_DLXS#Installation_Instructions]] Installing_DLXS#Installation_Instructions
Link to a section on the current page [[DLXS_style_guide#Advanced_Markup]] DLXS_style_guide#Advanced_Markup
Link to a section on the current page but have the link say something different [[DLXS_style_guide#Advanced_Markup|Advanced]] Advanced
Link to an external (non-wiki) source [http://en.wikipedia.org Wikipedia] Wikipedia


[edit] Lists

Type Markup Example
Bullet list 
* Item 1
** Item 1.1
** Item 1.2
* Item 2
** Item 2.1
*** Item 2.1.1
*** Item 2.1.2
*** Item 2.1.3
** Item 2.2
* Item 3
  • Item 1
    • Item 1.1
    • Item 1.2
  • Item 2
    • Item 2.1
      • Item 2.1.1
      • Item 2.1.2
      • Item 2.1.3
    • Item 2.2
  • Item 3
Numbered list 
# Item 1
## Item 1.1
## Item 1.2
# Item 2
## Item 2.1
### Item 2.1.1
### Item 2.1.2
### Item 2.1.3
## Item 2.2
# Item 3
  1. Item 1
    1. Item 1.1
    2. Item 1.2
  2. Item 2
      1. Item 2.1
      2. Item 2.1.1
      3. Item 2.1.2
      4. Item 2.1.3
    2. Item 2.2
  3. Item 3


[edit] Tables

You can use wiki table formatting or html table formatting 

<table cellpadding="5" cellspacing="0" border="1">
  <tr>
    <th>heading 1</th>
    <th>heading 2</th>
  </tr>
  <tr>
    <td>cell 1</td>
    <td>cell 2</td>
  </tr>
</table>
heading 1 heading 2
cell 1 cell 2 
{| cellpadding="15" cellspacing="0" border="1"
|-
!heading 1
!heading 2
|-
|cell 1
|cell 2
|}

OR

{| cellpadding="15" cellspacing="0" border="1"
|-
!heading 1 !! heading 2
|-
|cell 1 || cell 2
|}
heading 1 heading 2
cell 1 cell 2


[edit] Images

DLXS wiki upload page

DLXS wiki list of uploaded images

Style Markup Example
Basic image w/custom alt text [[Image:DLXSlogo.gif|The DLXS logo]] The DLXS logo
Image w/custom alt text & floated to write [[Image:DLXSlogo.gif|right|The DLXS logo]] Here is the DLXS logo floated to the right, if you put the image before the text, the text should wrap around it like this.
The DLXS logo
Here is the DLXS logo floated to the right, if you put the image before the text, the text should wrap around it like this.
Resize image [[Image:DLXSlogo.gif|100px|The DLXS logo]] The DLXS logo
Link directly to an image without displaying it: [[:media:DLXSlogo.gif|Image of the DLXS logo]] Image of the DLXS logo


[edit] Hidden Comments

You can comment in the wiki the same way you would comment in html. Use when you want to leave comments that can only be seen when editing the page.

<!-- comment here -->


[edit] DLXS Custom Styles

Style When to use Markup Example
future release [for use by DLXS staff only] Additions about a forthcoming release should just be added to any relevant pages as a new paragraph. Be sure to include the word 'Release_X' (X being the release number) for easy searching and integration when the release is ready. <div class="release"> '''Release_X:''' Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Praesent velit. </div>

Release_X: Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Praesent velit.

DLXS staff only note Use to describe a note, tip or warning for a particular procedure.

Be sure to include the label 'DLXS_Tip', 'DLXS_Warning', or 'DLXS_Note' to make searching for these items easier. For use by U-M DLXS staff only.

<div class="tip">'''DLXS_Tip:''' Make sure you first blah blah blah. </div>
DLXS_Tip: Make sure you first blah blah blah.
note Use to describe a note or tip for a particular procedure. Use of this style is highly encouraged - especially by DLXS partners. Note the use of tilda (~~~) to indicate author. <div class="note">'''Note:''' I found that by doing x first blah blah blah. ~~~</div>
Note: I found that by doing x first blah blah blah. Suzchap
workshop Used by DLXS staff only to indicate that content is applies to the workshop only <div class="workshop">'''Workshop:''' Go to directory foobar blah blah blah.</div>
Workshop: Go to directory foobar blah blah blah.
Red Text Make text red so it stands out (usually useful for key elements in a code snippet) Here's what I have to say about <span class="redtext">this</span> and that's all. Here's what I have to say about this and that's all.
Green Text Make text green so it stands out (usually useful for key elements in a code snippet) Here's what I have to say about <span class="greentext">this</span> and that's all. Here's what I have to say about this and that's all.

[edit] Templates for page status

There are currently 2 templates that can be applied to any page to signal a page's status.

To assign a template to a page, enter the markup below to the top of the page.


{{WorkInProgress}} will display:

progress icon
This page is a work in progress. It is actively being worked on.
So don't worry if it looks kinda weird.


{{NeedsReview}} will display:

warning icon
This page has been flagged by DLXS or DLXS Users as needing to be reviewed.
Until it is fully reviewed, it may contain inaccurate or difficult to follow information.


Tip: To find wiki articles that use these templates - use the following URL's:

Special:Whatlinkshere/Template:NeedsReview

Special:Whatlinkshere/Template:WorkInProgress


Retrieved from "http://webservices.itcs.umich.edu/mediawiki/dlxs13/index.php/DLXS_Style_Guide"
Personal tools