DLXS Style Guide
From DLXS Documentation
(DRAFT! a work in progress)
Contents |
Basics
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."
Text Formatting
| Style | When to use | Markup | Example |
|---|---|---|---|
| Citation | Use when you need to display code that is used by the wiki | <cite>lorem ipsum</cite> | lorem ipsum |
| pre | Use when displaying large chunks of code that you want to set apart from rest of text | <pre>lorem ipsum</pre> | lorem ipsum |
| 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.
|
| nowiki | Use when you need to display code that is used by the wiki | <nowiki><code>lorem ipsum</code></nowiki> | <code>lorem ipsum</code> |
| strikethrough | Use when you want to indicate that something no longer applies, but don't want to delete it yet | <strikethrough>lorem ipsum</strikethrough> |
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 |
The preferable way of linking to a file is: (everything before the pipe won't show)
[[Sample Makefile.html|Makefile.html click here]]
and NOT:
"For more information about the [[Makefile.html click here]]."
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.
Comments
Advanced Markup
| Style | When to use | Markup | Example |
|---|---|---|---|
| bug | [for use by DLXS staff only] use to alert users that there is a known bug in the software | <div class="bug">'''Bug:''' We're working on it.</div> | Bug: We're working on it.
|
| release | [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. | <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. |
| tip | Use to describe a tip for a particular procedure | <div class="tip">'''Tip:''' I found that doing x first really helps -suz</div> | Tip: I found that doing x first really helps -suz
|
| note | Use if you just want to describe something and have it stand out a bit more | <div class="note">'''Note:''' Make sure you first blah blah blah.</div> | Note: Make sure you first 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. |
