Difference between revisions of "PC-BSD® Wiki:Style Guidelines"

From PC-BSD Wiki
Jump to: navigation, search
(Screenshots)
(38 intermediate revisions by one user not shown)
Line 2: Line 2:
 
== Objective ==
 
== Objective ==
  
The purpose of defining how pages on the wiki should be created, is to help maintain consistency by having a set standard or model to follow, and to enable easier translations of the site into other languages.
+
The purpose of defining how pages on the wiki should be created, is to help maintain consistency by having a set standard or model to follow, to enable easier translations of the site into other languages, and allow publishing with less modification.
  
 
== Text ==
 
== Text ==
Line 15: Line 15:
 
: ''italic text:'' used to represent device names or file name paths.
 
: ''italic text:'' used to represent device names or file name paths.
 
: ''' ''bold italic text:'' ''' used to emphasize an important point.
 
: ''' ''bold italic text:'' ''' used to emphasize an important point.
 +
 +
==== Emphasis ====
 +
 +
; Notes
 +
: Often we need to specifically call attention to a particular caveat. In order to clearly delineate these, place them within a notes box via the template: '''<nowiki>{{</nowiki>note{{pipe}}''width='''48.5%'''''{{pipe}}'''''text'''''<nowiki>}}</nowiki>'''
 +
: {{note|This is an example that spans the width of the page.}}
 +
 +
; Warning text
 +
: Some instructions have serious consequences which are further emphasized by limited use of redlighting, such as the word ''WARNING'' and is accomplished with the redlight template: '''<nowiki>{{</nowiki>redlight{{pipe}}text='''''text'''''<nowiki>}}</nowiki>'''
 +
: In the context of this sentence only {{redlight|text=WARNING}} has the redlight effect, notice that it is padded by one space on either side.
 +
 +
; Highlighted text
 +
: In certain circumstances, especially to show revisions such as on the [[errata]] page or on [[#Hypertext Links|this page]] to more clearly show what to replace, there is the highlight template: '''<nowiki>{{</nowiki>highlight{{pipe}}text='''''text'''''<nowiki>}}</nowiki>'''
 +
: In the context of this sentence only {{highlight|text=this portion of text}} has the highlight effect.
  
 
=== Language usage and word choice ===
 
=== Language usage and word choice ===
Line 21: Line 35:
 
: Use words and phrases with the same meaning; multiple types of sentence structure.
 
: Use words and phrases with the same meaning; multiple types of sentence structure.
  
; Contractions
+
; Contractions: In place of: {{txtbox|override|margin-top=-5px|margin-bottom=0px|box={{nbsp|2}}'''''aren't''''' use '''''are not''''',       '''''can't''''' use '''''can not''''',       '''''cannot''''' use '''''can not''''',
: In place of
+
{{nbsp|2}}'''''doesn't''''' use '''''does not''''',    '''''don't''''' use '''do not''',         '''''hasn't''''' use '''''has not'''''
:: '''''aren't''''' use '''''are not''''',
+
{{nbsp|2}}'''''haven't''''' use '''''have not''''',    '''''weren't''''' use '''''were not''''',     '''''won't''''' use '''''will not''''',
:: '''''can't''''' use '''''can not''''',
+
{{nbsp|2}}'''''you'll''''' use '''''you will''''',     '''''you'd''''' use '''''you would''''',     '''''you're''''' use '''''you are''''',
:: '''''cannot''''' use '''''can not''''',
+
{{nbsp|2}}'''''you've''''' use '''''you have'''''.}}
:: '''''doesn't''''' use '''''does not'''''
+
:: '''''don't''''' use '''do not''',
+
:: '''''hasn't''''' use '''''has not'''''
+
:: '''''haven't''''' use '''''have not'''''
+
:: '''''weren't''''' use '''''were not''''',
+
:: '''''won't''''' use '''will not''',
+
:: '''''you'll''''' use '''''you will''''',
+
:: '''''you'd''''' use '''''you would''''',
+
:: '''''you're''''' use '''''you are'''''
+
:: '''''you've''''' use '''''you have'''''.
+
  
 
; Brand names
 
; Brand names
Line 62: Line 66:
  
 
Within the text, it is helpful to add a link to topics, pages, and sites to further explain and allow for additional research.  
 
Within the text, it is helpful to add a link to topics, pages, and sites to further explain and allow for additional research.  
; Link name
+
; Name
 
: Use a descriptive word or phrase. It can be the general location (page/site) of the link, as long as the link itself is to the specific section (when ever possible). Try not to be too general/generic. Highlight and italic used for clarity in the examples.
 
: Use a descriptive word or phrase. It can be the general location (page/site) of the link, as long as the link itself is to the specific section (when ever possible). Try not to be too general/generic. Highlight and italic used for clarity in the examples.
 
:: '''Replace this:''' You can find more information about hardware compatibility {{highlight|{{citelink|url=http://forums.freebsd.org/forumdisplay.php?f=32|txt=''here.''}}}}
 
:: '''Replace this:''' You can find more information about hardware compatibility {{highlight|{{citelink|url=http://forums.freebsd.org/forumdisplay.php?f=32|txt=''here.''}}}}
Line 96: Line 100:
 
; Traversal of menus or windows
 
; Traversal of menus or windows
 
: use an arrow (➜)
 
: use an arrow (➜)
:: '''Replace this:''' PC-BSD control panel -> System manager -> System packages tab
+
:: '''Replace this:''' PC-BSD control panel -> System manager -> System packages
:: '''With this:''' ''[[Control Panel]]'' ➜ [[System Manager#Install/Uninstall Desktops and System_Components | ''System Manager'' ➜ ''System Packages'']]
+
:: '''With this:''' ''[[Control Panel]]'' ➜ [[System Manager | ''System Manager'']] [[System Manager#Install/Uninstall Desktops and System_Components |''System Packages'']]
 
: This is a unicode [[wikipedia:UTF-8|UTF-8]]  character but may appear gibberish in other charsets such as [[wikipedia:ISO 8859-1|IS0 8859-1]].
 
: This is a unicode [[wikipedia:UTF-8|UTF-8]]  character but may appear gibberish in other charsets such as [[wikipedia:ISO 8859-1|IS0 8859-1]].
  
=== Describing buttons and other named visual objects ===
+
; Trademarks
 +
:PC-BSD®, AppCafe®, and Warden® are registered trademarks and the ® symbol must appear next to these terms ''' ''except'' ''' when the term is used as a command or in command output.
 +
 
 +
:''template:RM'' produces {{RM}} via '''<nowiki>{{RM}}</nowiki>''' which is simply an equivalent in place of typing the specific character.
 +
:''template:r'' produces {{r}} via '''<nowiki>{{r}}</nowiki>''' which is a symbol that is 50% of the size it would be in that context and in superscript position.
 +
'''Note:''' Special care needs to be taken because the two are not equivalent. ''NavHome'', ''NavHeader'', and ''SwapTitle'' have ''custompagename'' that may be assigned content that includes '''<nowiki>{{r}}</nowiki>''' but where that is used, ''custompagecategory'' must be defined an equivalent content that includes '''<nowiki>{{RM}}</nowiki>'''. Internal links must include '''<nowiki>{{RM}}</nowiki>''' for the page name portion, but may include '''<nowiki>{{r}}</nowiki>''' for the displayed text.
 +
 
 +
=== Named visual objects ===
  
 
Often the documentation within the handbook will describe a series of steps that includes clicking upon a button. In other places, the handbook may indicate the name of a window or folder or other object on the screen.
 
Often the documentation within the handbook will describe a series of steps that includes clicking upon a button. In other places, the handbook may indicate the name of a window or folder or other object on the screen.
Line 109: Line 120:
 
=== Commandline examples ===
 
=== Commandline examples ===
  
Frequently in the handbook we provide a series of commands or shell output. For these situations, use [[template:txtbox]].
+
Frequently in the handbook we provide a series of commands or shell output. For these situations, use [[template:txtbox]]. Such content should be formatted for a width of 80 characters (spaces included).
  
 
; Replace this: (The wiki method: leftmost character per line is a space.)
 
; Replace this: (The wiki method: leftmost character per line is a space.)
 
  Cause a box to enclose the text by starting the sentence with a space, however this has a small problem with keeping the text inside the box. For whatever reason, the text extends out of the dashed lines of this box, to the right.
 
  Cause a box to enclose the text by starting the sentence with a space, however this has a small problem with keeping the text inside the box. For whatever reason, the text extends out of the dashed lines of this box, to the right.
  
 
+
; With this: '''<nowiki>{{</nowiki>txtbox{{pipe}}box='''''content'''''<nowiki>}}</nowiki>'''
; With this: '''<nowiki>{{</nowiki>txtbox{{pipe}}box='''''content'''''<nowiki>}}</nowiki>'''.
+
 
{{txtbox|pre-line|width=50%|box=A much improved variation of that above method also encloses the text within a similar box. Even though the text is a short paragraph of four sentences in length, it does not have the same flaw as before. The text is neatly contained within the dashed lines of the box, and also does not require the initial space character at the start of the first sentence. If that character were included, it would display with two nested boxes. The exact wrap style can be determined when invoked; this box uses 'pre-line' style formatting.
 
{{txtbox|pre-line|width=50%|box=A much improved variation of that above method also encloses the text within a similar box. Even though the text is a short paragraph of four sentences in length, it does not have the same flaw as before. The text is neatly contained within the dashed lines of the box, and also does not require the initial space character at the start of the first sentence. If that character were included, it would display with two nested boxes. The exact wrap style can be determined when invoked; this box uses 'pre-line' style formatting.
|txt=Text to the right of the box is also possible. This is the [[template:txtbox|''txtbox'' template]] and works much the same as the next template, except for its appearance. Further details are on the template page.
+
|txt=Text to the right of the box is also possible. This is the [[template:txtbox|''txtbox'' template]] which facilitates a better result without adding a lot of extra typing. Further details including the list of format identifiers are on the template page.
 
}}
 
}}
  
 
=== Tables ===
 
=== Tables ===
Presently various templates are needed to more easily result in a table with the appearance below. However, in the near future there will be an addition of a class="spiffy_table" which will further simplify creation (as shown below), the init template is already modified to include it transparently.
+
Presently various templates are needed to more easily result in a table with the appearance below. However, in the near future there will be an addition of a class="spiffy_table" which will further simplify creation (as shown below), the init template is already modified to include it transparently. Including a caption places it into the tables group list.
  
 
{{tbl-init|caption= of comparison}}
 
{{tbl-init|caption= of comparison}}
 
{{tbl-title|width=32%|Current method}}
 
{{tbl-title|width=32%|Current method}}
{{tbl-title|width=32%|CSS style method}}
+
{{tbl-title|width=32%|CSS style method (minimal)}}
 
!Blank
 
!Blank
!Future
+
!Future (best)
 
|-
 
|-
 
{{tbl-cell|row=1|content=This is rather verbose and is more of a brute force method to get the job done. Every line needs a row number which is helpful for readability but also correlates to coloration: odd=white, even=grey.}}
 
{{tbl-cell|row=1|content=This is rather verbose and is more of a brute force method to get the job done. Every line needs a row number which is helpful for readability but also correlates to coloration: odd=white, even=grey.}}
{{tbl-cell|row=1|There will likely be somewhat of a combination of the two, since some capabilities may be a bit cumbersome otherwise, such as specifying column widths. However, clearly this method involves less typing to produce a good result.}}
+
{{tbl-cell|row=1|There will likely be somewhat of a combination of the two, since some capabilities may be a bit cumbersome otherwise, such as specifying column widths. However, clearly this method involves the least typing to produce a good result.}}
 
|
 
|
 
|When the CSS styles are in place, the right two columns will have matching coloration/style due to '''class=spiffy_table''' in tbl-init which is already present. Including tbl-title allows for defining width.
 
|When the CSS styles are in place, the right two columns will have matching coloration/style due to '''class=spiffy_table''' in tbl-init which is already present. Including tbl-title allows for defining width.
Line 140: Line 150:
 
|}
 
|}
 
: Also place a total of exactly one '''<nowiki><noinclude>{{GroupListHeading|tables}}</noinclude></nowiki>''' at the bottom of the page, below any existing <nowiki><noinclude>{{refheading}}</noinclude></nowiki> and above the category links section.
 
: Also place a total of exactly one '''<nowiki><noinclude>{{GroupListHeading|tables}}</noinclude></nowiki>''' at the bottom of the page, below any existing <nowiki><noinclude>{{refheading}}</noinclude></nowiki> and above the category links section.
 
=== Trademarks ===
 
 
PC-BSD®, AppCafe®, and Warden® are registered trademarks and the ® symbol must appear next to these terms ''' ''except'' ''' when the term is used as a command or in command output.
 
;Implementation
 
:''template:RM'' produces {{RM}} via '''<nowiki>{{RM}}</nowiki>''' which is simply an equivalent in place of typing the specific character.
 
:''template:r'' produces {{r}} via '''<nowiki>{{r}}</nowiki>''' which is a symbol that is 50% of the size it would be in that context and in superscript position.
 
'''Note:''' Special care needs to be taken because the two are not equivalent. ''NavHome'', ''NavHeader'', and ''SwapTitle'' have ''custompagename'' that may be assigned content that includes '''<nowiki>{{r}}</nowiki>''' but where that is used, ''custompagecategory'' must be defined an equivalent content that includes '''<nowiki>{{RM}}</nowiki>'''. Internal links must include '''<nowiki>{{RM}}</nowiki>''' for the page name portion, but may include '''<nowiki>{{r}}</nowiki>''' for the displayed text.
 
  
 
== Topics structure ==
 
== Topics structure ==
Line 183: Line 185:
 
; Left from prior guideline
 
; Left from prior guideline
 
: To ensure that the PDF and EPUB versions format correctly, use a [[wikipedia:Hard return|hard enter]] between the items in a bulleted list.
 
: To ensure that the PDF and EPUB versions format correctly, use a [[wikipedia:Hard return|hard enter]] between the items in a bulleted list.
:: Suggestion used in revision above, is addition of <nowiki><br></nowiki>. This still needs verification whether a ''hard enter'' or <nowiki><br></nowiki> are needed.
+
:: Suggestion used in revision above, is addition of <nowiki><br></nowiki>. {{highlight|text=This still needs verification whether a ''hard enter'' or <nowiki><br></nowiki> are needed.}}
  
 
=== Collation ===
 
=== Collation ===
Line 239: Line 241:
 
== Images ==
 
== Images ==
  
It is important that the images included in the wiki, especially the handbook portion, be consistent and of a quality that would be acceptable in a professional publication. ('''Note:''' Further refinement of images in general should be done, likely including a template for images that may shorten or clarify their inclusion. There are features that exist for images that also modify the page layout, which we do not take advantage of as yet.)
+
It is important that the images included in the wiki, especially the handbook portion, be consistent and of a quality that would be acceptable in a professional publication. ('''Note:''' Further refinement of images should be done, including a template for images that may shorten or clarify their inclusion. There are features that exist for images that also modify the page layout which are currently too wikipage specific to describe here in general terms.)
  
 
=== Format ===
 
=== Format ===
Line 255: Line 257:
 
==== Single windows ====
 
==== Single windows ====
 
* Include the whole window frame and its title bar.
 
* Include the whole window frame and its title bar.
==== Multiple windows shown as for a single task ====
+
==== Multiple windows ====
 +
These may be within the same image or screenshot if the purpose is to show one task.
 
* Crop to a box that contains both windows with entire window borders intact.
 
* Crop to a box that contains both windows with entire window borders intact.
** Windows may overlap only if necessary details as provided by wiki text are not hidden.
+
* Windows may overlap only if necessary details as provided by wiki text are not hidden.
 
* Must include in the image: options, button labels, window titles, and any other detail that allows the step-by-step to be easily followed without surprises.
 
* Must include in the image: options, button labels, window titles, and any other detail that allows the step-by-step to be easily followed without surprises.
  
Line 263: Line 266:
  
 
* Must limit to a '''maximum size of 800x600''', this allows the entire image to remain visible even on a 1024x768 screen size.
 
* Must limit to a '''maximum size of 800x600''', this allows the entire image to remain visible even on a 1024x768 screen size.
* Include an image on a page with the following syntax:
+
* If the content is text and has no images, such as console output, then transcribe the text into a txtbox (''Do NOT'' use an image).
: Example: '''<nowiki>[[</nowiki>File:'''''File:GNOME2-2.png'''''{{pipe}}thumb{{pipe}}400px{{pipe}}''<nowiki>'''</nowiki>'''Figure 6.1a: GNOME2 Desktop on a PC-BSD® System'''<nowiki>'''</nowiki>''<nowiki>]]</nowiki>'''
+
* Include a single image on a page with the following syntax:
 +
: Example:
 +
{{txtbox|margin-left=24px|box='''<nowiki>[[</nowiki>File:'''File:''GNOME2-2.png'''''{{pipe}}thumb{{pipe}}393px{{pipe}}''<nowiki>'''</nowiki>'''Figure 6.1a: GNOME2 Desktop on a PC-BSD® System'''<nowiki>'''</nowiki>''<nowiki>]]</nowiki>'''}}
 +
* Place two images side by side on a page with this syntax:
 +
: Example:
 +
{{txtbox|wrap|margin-left=24px|box='''<nowiki><div</nowiki> style="overflow: hidden"><nowiki>[[File:</nowiki>'''''Login2.jpeg'''''{{pipe}}left{{pipe}}thumb{{pipe}}393px{{pipe}}<nowiki>'''</nowiki>'''''Figure 4.8c: Login Menu with User Selected'''''<nowiki>''']][[</nowiki>'''''File:start1.png'''''{{pipe}}right{{pipe}}thumb{{pipe}}393px{{pipe}}'''<nowiki>'''</nowiki>''Figure 4.8d: PC-BSD® Getting Started Screen'''''<nowiki>''']]</div></nowiki>'''}}
  
 
==== Scalable Dimensions ====
 
==== Scalable Dimensions ====
Line 321: Line 329:
  
 
; Format
 
; Format
: Place the category link at the bottom of the page, usually contained between the <nowiki><noinclude> and </noinclude></nowiki> markers. The first category listed should be the largest group the page belongs to, followed by increasingly specific categories. Handbook pages may be members of multiple categories such as the example below, for the GNOME2 page. Category names should be capitalized the same as the pages involved, or each individual word has its first letter capitalized. ''Some templates can auto-categorize pages into their page title category.''
+
: Place the category link at the bottom of the page, contained within the between the <nowiki><noinclude></nowiki> block. The first category listed should be the largest group the page belongs to, followed by increasingly specific categories. Category names should be capitalized the same as the pages involved, or each individual word has its first letter capitalized. ''Some templates can auto-categorize pages into their page title category.''
 
+
:: <nowiki><noinclude></nowiki><br>
+
:: <nowiki>[[category:Handbook]]</nowiki><br>
+
:: <nowiki>[[category:Desktops]]</nowiki><br>
+
:: <nowiki>[[category:GNOME2]]</nowiki><br>
+
:: <nowiki></noinclude></nowiki>
+
  
 
; Description
 
; Description
Line 343: Line 345:
 
: Used in locations of the wiki markup that purposely and specifically do not follow the guideline, or places where reminders or explanations are needed or useful.
 
: Used in locations of the wiki markup that purposely and specifically do not follow the guideline, or places where reminders or explanations are needed or useful.
 
:: '''<nowiki><</nowiki>!--''' ''comment text'' '''--<nowiki>></nowiki>'''
 
:: '''<nowiki><</nowiki>!--''' ''comment text'' '''--<nowiki>></nowiki>'''
 +
 +
; The <nowiki><noinclude></nowiki> block
 +
: Each page should contain a group of category links at the bottom, along with a Refheading and GroupListHeading as applicable. No further text or spaces following, though in some instances a comment is present with nothing following it.
 +
{{txtbox|box=
 +
'''<nowiki><noinclude></nowiki>'''
 +
'''<nowiki>{{Refheading}}</nowiki>'''
 +
'''<nowiki>{{GroupListHeading|group=tables}}</nowiki>'''
 +
'''<nowiki>[[</nowiki>category:'''''category 1'''''<nowiki>]]</nowiki>'''
 +
'''<nowiki>[[</nowiki>category:'''''category 2'''''<nowiki>]]</nowiki>'''
 +
'''<nowiki></noinclude></nowiki>'''}}
  
 
=== Headings ===
 
=== Headings ===

Revision as of 02:55, 2 March 2013

PC-BSD® Wiki:Style GuidelinesProtection (edit): Edited by: Tigersharke

Contents

Objective

The purpose of defining how pages on the wiki should be created, is to help maintain consistency by having a set standard or model to follow, to enable easier translations of the site into other languages, and allow publishing with less modification.

Text

The guideline for actual text content may be under continual refinement with frequent additions until nearly complete. In areas that are incomplete or not yet defined, a reasonable default can be taken from the Wikipedia:Manual of Style.

Typographic Conventions

The PC-BSD Handbook uses the following typographic conventions:

bold text: represents a command written at the command line. In usage examples, the font is changed with any command output displayed in unbolded text.
italic text: used to represent device names or file name paths.
bold italic text: used to emphasize an important point.

Emphasis

Notes
Often we need to specifically call attention to a particular caveat. In order to clearly delineate these, place them within a notes box via the template: {{note|width=48.5%|text}}
Template:Word-note This is an example that spans the width of the page.
Warning text
Some instructions have serious consequences which are further emphasized by limited use of redlighting, such as the word WARNING and is accomplished with the redlight template: {{redlight|text=text}}
In the context of this sentence only  WARNING  has the redlight effect, notice that it is padded by one space on either side.
Highlighted text
In certain circumstances, especially to show revisions such as on the errata page or on this page to more clearly show what to replace, there is the highlight template: {{highlight|text=text}}
In the context of this sentence only this portion of text has the highlight effect.

Language usage and word choice

Variety
Use words and phrases with the same meaning; multiple types of sentence structure.
Contractions
In place of:
  aren't use are not, can't use can not, cannot use can not,

  doesn't use does not, don't use do not, hasn't use has not   haven't use have not, weren't use were not, won't use will not,   you'll use you will, you'd use you would, you're use you are,

  you've use you have.
Brand names
Use web search instead of Google search.
Idioms
Use proper and precise wording.
Watch closely should be used instead of keep an eye on.
Crashes or fails in place of gets a blue screen of death.
Idioms described on wikipedia.
Slang
Use precise rather than colorful or regional terms, however some technical jargon is allowable especially if explained or defined.
Open a browser to pcbsd.org would be used instead of surf to pcbsd.
Slang described on wikipedia.
Jargon described on wikipedia.
Dates
Given that some date formats can be problematic: (07-03-2012) Does the author mean July 3rd 2012, or March 7th 2012. The wiki offers a per-user preference for date format. This also formalizes instances of dates which may also aid translations.
{{#dateformat:01 May 2012}} should be used resulting in 01 May 2012 which conforms to each user's preferences.
Uncapped proper names
Some software is officially named in lowercase, yet sentences should usually begin with a capital letter. The solution is to avoid using those special proper names as the word that begins a sentence.

Hypertext Links

Within the text, it is helpful to add a link to topics, pages, and sites to further explain and allow for additional research.

Name
Use a descriptive word or phrase. It can be the general location (page/site) of the link, as long as the link itself is to the specific section (when ever possible). Try not to be too general/generic. Highlight and italic used for clarity in the examples.
Replace this: You can find more information about hardware compatibility here.[1]
With this: You can find more information about hardware compatibility on the [1][1].
Replace this: This forum post[1] explains how to properly plug the outlet tube of an inlet drain line.
With this: This [2][1] explains how to properly plug the outlet tube of an inlet drain line.
URL
Use an ending slash with any url that leads to a directory or non-file (such as any site name). It is prudent to verify that an adjusted link is valid since some sites do not use extensions for file names. This convention will aid with consistency and help to eliminate technically different but effectively identical URLs.
This is a valid url: http://forums.freebsd.org
Url with proper syntax on this wiki: http://forums.freebsd.org/
Example of a url that ends with a file name: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/sound-setup.html
Internal
The URL is within the PC-BSD wiki.
Use [[page name]] or [[page name|alternate text]]
External
The URL is for a location outside of wiki.pcbsd.org. Most places where an external link may be used, there is alternate text shown, which means for a printed handbook, there must be a footnote to provide the actual URL. Those rare places that do not provide alternate text but show the actual URL, do not need the citelink. If the link text is to be bold or italic or both then the modifier characters must be directly around the alternate text and not around the entire citelink phrase below.
For the link use {{Citelink|url=complete URL|txt=alternate text}}
Also place a total of exactly one <noinclude>{{refheading}}</noinclude> at the bottom of the page, above the category links section.
Special External
The URL is for a site not part of the PC-BSD wiki, but has a defined interwiki shortcut such as for wikipedia.
Valid markup is [[wikipedia:page name]] or [[wikipedia:page name|alternate text]] except in the context of the handbook itself.
For the link use {{Citelink|shortcut|url=page URL|txt=alternate text}}
  • Current shortcuts we have defined locally can be found at (or carefully added to) OurInterwiki.
Also place a total of exactly one <noinclude>{{refheading}}</noinclude> at the bottom of the page, above the category links section.

Special Characters

Traversal of menus or windows
use an arrow (➜)
Replace this: PC-BSD control panel -> System manager -> System packages
With this: Control Panel System ManagerSystem Packages
This is a unicode UTF-8 character but may appear gibberish in other charsets such as IS0 8859-1.
Trademarks
PC-BSD®, AppCafe®, and Warden® are registered trademarks and the ® symbol must appear next to these terms except when the term is used as a command or in command output.
template:RM produces ® via {{RM}} which is simply an equivalent in place of typing the specific character.
template:r produces ® via {{r}} which is a symbol that is 50% of the size it would be in that context and in superscript position.

Note: Special care needs to be taken because the two are not equivalent. NavHome, NavHeader, and SwapTitle have custompagename that may be assigned content that includes {{r}} but where that is used, custompagecategory must be defined an equivalent content that includes {{RM}}. Internal links must include {{RM}} for the page name portion, but may include {{r}} for the displayed text.

Named visual objects

Often the documentation within the handbook will describe a series of steps that includes clicking upon a button. In other places, the handbook may indicate the name of a window or folder or other object on the screen.

These items could be further emphasized, but their names must be within quotes.
Example: Click on the "Submit" button along the lower edge of the "Compose response" window.

Commandline examples

Frequently in the handbook we provide a series of commands or shell output. For these situations, use template:txtbox. Such content should be formatted for a width of 80 characters (spaces included).

Replace this
(The wiki method: leftmost character per line is a space.)
Cause a box to enclose the text by starting the sentence with a space, however this has a small problem with keeping the text inside the box. For whatever reason, the text extends out of the dashed lines of this box, to the right.
With this
{{txtbox|box=content}}
A much improved variation of that above method also encloses the text within a similar box. Even though the text is a short paragraph of four sentences in length, it does not have the same flaw as before. The text is neatly contained within the dashed lines of the box, and also does not require the initial space character at the start of the first sentence. If that character were included, it would display with two nested boxes. The exact wrap style can be determined when invoked; this box uses 'pre-line' style formatting.
Text to the right of the box is also possible. This is the txtbox template which facilitates a better result without adding a lot of extra typing. Further details including the list of format identifiers are on the template page.

Tables

Presently various templates are needed to more easily result in a table with the appearance below. However, in the near future there will be an addition of a class="spiffy_table" which will further simplify creation (as shown below), the init template is already modified to include it transparently. Including a caption places it into the tables group list.

Table of comparison [tables 1]
Current method CSS style method (minimal) Blank Future (best)
This is rather verbose and is more of a brute force method to get the job done. Every line needs a row number which is helpful for readability but also correlates to coloration: odd=white, even=grey.


There will likely be somewhat of a combination of the two, since some capabilities may be a bit cumbersome otherwise, such as specifying column widths. However, clearly this method involves the least typing to produce a good result. When the CSS styles are in place, the right two columns will have matching coloration/style due to class=spiffy_table in tbl-init which is already present. Including tbl-title allows for defining width.
{{tbl-init|align=center|caption=1a. The caption}}
{{tbl-title|column title}}
|-

{{tbl-cell|row=1|The content}}
|-
{{tbl-cell|row=
2|The content}}
|}


{{tbl-init|align=center|caption=1a. The caption}}
!column title
|-
|
The content
|-
|
The content
|}
{{tbl-init|align=center|caption=1a. The caption}}
{{tbl-title|width=32%|column title}}
|-
|
The content
|-
|
The content
|}
Also place a total of exactly one <noinclude>{{GroupListHeading|tables}}</noinclude> at the bottom of the page, below any existing <noinclude>{{refheading}}</noinclude> and above the category links section.

Topics structure

This will directly relate to headings, but since headings on individual pages are used in a somewhat non-uniform way (due to the appearance of each level of heading), this will apply to a naming convention used with the Table of Contents.

Examples in context

8. Control Panel <-- Macro Topic (Also wiki page and "level 1")

8.1 EasyPBI <-- Topic (Also wiki page and "level 1")

(Below are hidden on the wiki TOC but get shown in the published handbook html - All sub-page level)

8.1.1 Creating a PBI Module <-- Micro Topic
8.1.1.1 Build the Module <-- Nano Topic
8.1.1.2 Test and Fine-Tune the Module
8.1.1.2.1 pbi.conf <-- Pico Topic
8.1.1.2.2 Resources
8.1.1.2.3 Desktop/Menu Entries
8.1.1.2.4 External-Links

(Below is not known to have been used anywhere but if they were to exist this is how they would be used/named)

8.1.1.2.4.1 Example of external link <-- Femto Topic ("level 5")
8.1.1.2.4.1.1 This is the example <-- Atto Topic ("level 6")

Lists

Bullets

There are two types of bullets in use:

  1. A bulleted list which begins uppercase. Whether or not it ends in punctuation depends upon the size of the list. For example:
    • the What's New in 9.1 list uses sentences to describe the features so ends in a period. Use this type of list when the list includes a description large enough to warrant at least one sentence.
    • the Minimum Hardware Requirements list uses few words per item. Since the individual items do not warrant a sentence, this type of list does not end in a period.
  2. A bulleted list which begins with bolded text (typically the name of a menu item). The bolded section is capitalized to match the name of the menu item and followed by a colon (:). The sentence following the colon begins lowercase and should be worded so that the bolded item is the beginning of the sentence. An example is:
    Size on Disk: indicates the amount of space being used by the jail.
    In this example, the menu item appears as "Size on Disk" (mix of upper/lowercase), "indicates" is lowercase and is worded so that it reads as one sentence (including the name of the menu item). Because it is a sentence, it ends with a period.
Left from prior guideline
To ensure that the PDF and EPUB versions format correctly, use a hard enter between the items in a bulleted list.
Suggestion used in revision above, is addition of <br>. This still needs verification whether a hard enter or <br> are needed.

Collation

The information should first be placed in logical order, followed by quality or significance, then sorted in alphabetical order, next by chronological order, and finally by ordination. It may be noted that the entire collation section follows logical order, due to the order described in the first sentence. Examples below are taken from the PC-BSD Users Handbook#Table of Contents. The Errata page shows how chronological and ordinal organization may be used together. Using wiki markup in place of text (such as for numbering schemes) might allow for automatic charset substitution in relation to translations.

Logical
Putting things in order of precedence; from first task to last task, or first item naturally listed to last item.
  1. Introduction
  2. Pre-Installation Tasks
  3. Installing PC-BSD
  4. Post Installation Configuration and Installation Troubleshooting
Quality or significance
Organizing according to the importance of the item or its membership in a specific group type.
This is most visible with groups, such as Supported and unsupported desktops. In the Alphabetical example, the first four would seem out of order if the entire set of desktops were included, as below.
GNOME2
KDE4
LXDE
XFCE4
Awesome
EvilWM
Fluxbox
FVWM
i3
IceWM
Openbox
Spectrwm
WindowLab
Window Maker
Alphabetical
Organizing items by name according to the alphabet.
GNOME2
KDE4
LXDE
XFCE4
Chronological
Placing items in order according to date.
This is distinction primarily relates to historical and archival purposes.
Items are placed in reverse order, most recent first and oldest last.
Ordinal
The items are listed according to number.
Examples are Handbook page and chapter numbers, step-by-step instruction where numbered incremental actions are listed.
Elements are organized from smallest to largest value, or first to last step (similar to logical).
Wiki markup
# first text
# second text
Result
  1. first text
  2. second text

Images

It is important that the images included in the wiki, especially the handbook portion, be consistent and of a quality that would be acceptable in a professional publication. (Note: Further refinement of images should be done, including a template for images that may shorten or clarify their inclusion. There are features that exist for images that also modify the page layout which are currently too wikipage specific to describe here in general terms.)

Format

Required

Single windows

Multiple windows

These may be within the same image or screenshot if the purpose is to show one task.

Screenshots

Example:
[[File:File:GNOME2-2.png|thumb|393px|'''Figure 6.1a: GNOME2 Desktop on a PC-BSD® System''']]
Example:
<div style="overflow: hidden">[[File:Login2.jpeg|left|thumb|393px|'''Figure 4.8c: Login Menu with User Selected''']][[File:start1.png|right|thumb|393px|'''Figure 4.8d: PC-BSD® Getting Started Screen''']]</div>

Scalable Dimensions

Table of Acceptable 4:3 screens [tables 2]
Resolution Multiplier
800x600


1.00
1024x768


1.28
1152x864


1.44
1200x900


1.50
1280x960


1.60
1400x1050


1.75
1440x1080


1.80
1600x1200


2.00
1920x1440


2.40

Capture tips

Administrative

Categories

All pages that use templates: SwapTitle, NavHome, and NavHeader, are automatically added to a category of their pagename (or custompagename where one is defined).

Membership
Each wiki page (ie, GNOME2) and image page (ie, File:Stub-icon.png) should be a member of at least one category.
The category chosen may be determined by the description given on the individual category pages.
Format
Place the category link at the bottom of the page, contained within the between the <noinclude> block. The first category listed should be the largest group the page belongs to, followed by increasingly specific categories. Category names should be capitalized the same as the pages involved, or each individual word has its first letter capitalized. Some templates can auto-categorize pages into their page title category.
Description
The categories themselves should have some sort of explanation to guide their use.

Page structure

Header
Each handbook page contains a 3-icon navigation panel across the top, while other pages linked from the main page contain a simplified version.
Stubs
With relation to new pages that have minimal content, a stub warning is included to enhance visibility and aid with community involvement.
Comments
Used in locations of the wiki markup that purposely and specifically do not follow the guideline, or places where reminders or explanations are needed or useful.
<!-- comment text -->
The <noinclude> block
Each page should contain a group of category links at the bottom, along with a Refheading and GroupListHeading as applicable. No further text or spaces following, though in some instances a comment is present with nothing following it.
<noinclude>

{{Refheading}} {{GroupListHeading|group=tables}} [[category:category 1]] [[category:category 2]]

</noinclude>

Headings

Generally, the headings on a page help to outline and organize the content. It should also be noted that having identical headings or sub-headings within the entire wiki can cause trouble with future editing or navigation, and should be avoided. Include an action word or phrase or otherwise differentiate between the two locations, even if they are discussing the same content, the purpose in each case is not likely identical. (If a certain heading style is preferred though it does not match the guide below, then perhaps adjustments to the wiki site css need to be made.)

Page title

= Page title =
This level should not be used within a page. If there is need for this level within the content of the page, then it shall be the location of a break into a new page of that title. Here is where an introductory paragraph explaining the topic or feature given by the page name.

Level 2

== Level 2 ==
Often this level is skipped in favor of the next - likely indicating css changes should be made.

Level 3

=== Level 3 ===
(Since the level above gets skipped) Here is where the first major step of a process is mentioned, or the main characteristic of the feature is described.

Level 4

==== Sub-heading ====
This level exists but is generally unused currently.

Level 5

===== Level 5 =====
Usually the definition markup (;) is used in place of this header, such as the following:

Term
The above term is defined here.
Level 6

====== Level 6 ======
This level exists but is generally unused currently.

Resources

References


  1. 1.0 1.1 1.2 1.3 http://forums.freebsd.org/forumdisplay.php?f=32

List of Tables


  1. Table of comparison
  2. Table of Acceptable 4:3 screens
Retrieved from ‘http://wiki.pcbsd.org/index.php?title=PC-BSD®_Wiki:Style_Guidelines&oldid=19061
Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox