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. Although this page may not be specifically dedicated to how to edit the wiki, there is plenty of information included here that describes how to use various templates for certain situations. Until a page is developed which does focus on editing the wiki, the information here shall be considered a good start. A {{local|link=PC-BSD%C2%AE_Wiki:Template_QuickRef|template quick reference}} or an {{local|link=User:Tigersharke/editorFXcss|editor's stylesheet}} may also be helpful.

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. Although this page may not be specifically dedicated to how to edit the wiki, there is plenty of information included here that describes how to use various templates for certain situations. Until a page is developed which does focus on editing the wiki, the information here shall be considered a good start. A {{local|link=PC-BSD%C2%AE_Wiki:Template_QuickRef|template quick reference}} or an {{local|link=User:Tigersharke/editorFXcss|editor's stylesheet}} may also be helpful.

−

== Text ==

+

== Text == <!--T:2-->

−

+

+

<!--T:66-->

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:Wikipedia:Manual of Style|Wikipedia:Manual of Style]].

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:Wikipedia:Manual of Style|Wikipedia:Manual of Style]].

−

=== Typographic Conventions ===

+

=== Typographic Conventions === <!--T:3-->

−

+

+

<!--T:67-->

The PC-BSD Handbook uses the following 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.

: '''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.

: ''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.

+

=== Other Emphasis === <!--T:4-->

−

=== Other Emphasis ===

+

==== Highlighted text ==== <!--T:5-->

−

==== Highlighted text ====

+

<!--T:68-->

: 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 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.

: In the context of this sentence only {{highlight|text=this portion of text}} has the highlight effect.

+

==== Redlighted text ==== <!--T:6-->

−

==== Redlighted text ====

+

<!--T:69-->

: This should only have limited use for the sole purpose of adding emphasis to {{redlight|critical and dangerous}} information.

: This should only have limited use for the sole purpose of adding emphasis to {{redlight|critical and dangerous}} information.

: Use words and phrases with the same meaning; multiple types of sentence structure. This will increase interest and also by use of synonyms will improve the chance that the text will be understood, especially with regard to translations or non-native English readers.

: Use words and phrases with the same meaning; multiple types of sentence structure. This will increase interest and also by use of synonyms will improve the chance that the text will be understood, especially with regard to translations or non-native English readers.

+

==== Contractions ==== <!--T:10-->

−

==== Contractions ====

+

<!--T:72-->

−

{{nbsp|2}}In Place of:

+

In Place of:{{br}}

−

{{txtbox|override|box={{nbsp|2}}'''''aren't''''' use '''''are not''''',{{nbsp|8}}'''''can't''''' use '''''can not''''',{{nbsp|9}}'''''cannot''''' use '''''can not''''',<br/>{{nbsp|2}}'''''doesn't''''' use '''''does not''''',{{nbsp|6}}'''''don't''''' use '''do not''',{{nbsp|10}}'''''hasn't''''' use '''''has not'''''<br/>{{nbsp|2}}'''''haven't''''' use '''''have not''''',{{nbsp|6}}'''''weren't''''' use '''''were not''''',{{nbsp|6}}'''''won't''''' use '''''will not''''',<br/>{{nbsp|2}}'''''you'll''''' use '''''you will''''',{{nbsp|7}}'''''you'd''''' use '''''you would''''',{{nbsp|7}}'''''you're''''' use '''''you are''''',<br/>{{nbsp|2}}'''''you've''''' use '''''you have'''''.}}

+

{|

+

|{{nbsp|2}}'''''aren't''''' use '''''are not''''',||'''''can't''''' use '''''can not''''',||'''''cannot''''' use '''''can not''''',

+

|-

+

|{{nbsp|2}}'''''doesn't''''' use '''''does not''''',||'''''don't''''' use '''do not''',||'''''hasn't''''' use '''''has not'''''

+

|-

+

|{{nbsp|2}}'''''haven't''''' use '''''have not''''',{{nbsp|4}}||'''''weren't''''' use '''''were not''''',{{nbsp|4}}||'''''won't''''' use '''''will not''''',

+

|-

+

|{{nbsp|2}}'''''you'll''''' use '''''you will''''',||'''''you'd''''' use '''''you would''''',||'''''you're''''' use '''''you are''''',

+

|-

+

|{{nbsp|2}}'''''you've''''' use '''''you have'''''.||||

+

|}

−

==== Brand names ====

+

==== Brand names ==== <!--T:11-->

+

+

<!--T:73-->

Since some brand names may not always exist or are potentially unavailable/unknown, we must use a more descriptive word or phrase rather than a company or brand name for the item.

Since some brand names may not always exist or are potentially unavailable/unknown, we must use a more descriptive word or phrase rather than a company or brand name for the item.

: Use '''''web''' search'' instead of '''''Google''' search''.

: Use '''''web''' search'' instead of '''''Google''' search''.

: Use '''''cotton swab''''' rather than '''''Q-tip'''''.

: Use '''''cotton swab''''' rather than '''''Q-tip'''''.

−

==== Idioms ====

+

==== Idioms ==== <!--T:12-->

+

+

<!--T:74-->

Each language has its own idioms which are born from the context of that culture. It is much clearer and more universally understood if such phrases are avoided.

Each language has its own idioms which are born from the context of that culture. It is much clearer and more universally understood if such phrases are avoided.

: Use proper and precise wording.

: Use proper and precise wording.

Line 59:

Line 79:

: {{citelink|wikipedia|url=Idiom|txt=Idioms described on wikipedia}}.

: {{citelink|wikipedia|url=Idiom|txt=Idioms described on wikipedia}}.

+

==== Slang ==== <!--T:13-->

−

==== Slang ====

+

<!--T:75-->

: Use precise rather than colorful or regional terms, however some technical jargon is allowable especially if explained or defined within the context of the sentence or paragraph.

: Use precise rather than colorful or regional terms, however some technical jargon is allowable especially if explained or defined within the context of the sentence or paragraph.

:: '''''Open a browser to pcbsd.org''''' would be used instead of '''''surf to pcbsd'''''.

:: '''''Open a browser to pcbsd.org''''' would be used instead of '''''surf to pcbsd'''''.

Line 66:

Line 87:

: {{citelink|wikipedia|url=Jargon|txt=Jargon described on wikipedia}}.

: {{citelink|wikipedia|url=Jargon|txt=Jargon described on wikipedia}}.

+

==== Dates ==== <!--T:14-->

−

==== Dates ====

+

<!--T:76-->

: 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.

: 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.

:: '''<nowiki>{{</nowiki>#dateformat:'''''01 May 2012'''''}}''' should be used resulting in {{#dateformat:01 May 2012}} which conforms to each {{local|link=Special:Preferences#mw-prefsection-datetime|user's preferences}}.

:: '''<nowiki>{{</nowiki>#dateformat:'''''01 May 2012'''''}}''' should be used resulting in {{#dateformat:01 May 2012}} which conforms to each {{local|link=Special:Preferences#mw-prefsection-datetime|user's preferences}}.

+

==== Uncapped proper names ==== <!--T:15-->

−

==== Uncapped proper names ====

+

<!--T:77-->

: 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.

: 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.

+

==== Newness and changes ==== <!--T:16-->

−

==== Newness and changes ====

+

<!--T:78-->

: Especially within a list of updates to the current version, the word ''now'' ought to be omitted. By the very nature of pointing out that it is a list of revised features, it implies its relationship to the current documented version and that an adjustment has been made. Where possible the alternative of providing a comparison of the former method, application, or feature which contrasts with the current one is sufficient (and provides an improved explanation in context). Further explanation may be added as in the example below:

: Especially within a list of updates to the current version, the word ''now'' ought to be omitted. By the very nature of pointing out that it is a list of revised features, it implies its relationship to the current documented version and that an adjustment has been made. Where possible the alternative of providing a comparison of the former method, application, or feature which contrasts with the current one is sufficient (and provides an improved explanation in context). Further explanation may be added as in the example below:

:: The login manager uses PCDM which replaces the former GDM in order to reduce associated dependencies when GNOME is not also installed.

:: The login manager uses PCDM which replaces the former GDM in order to reduce associated dependencies when GNOME is not also installed.

−

=== Hypertext Links ===

+

=== Hypertext Links === <!--T:17-->

−

+

+

<!--T:79-->

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.

−

==== Name ====

+

+

==== Name ==== <!--T:18-->

+

+

<!--T:80-->

: 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 are used for clarity in the examples below.

: 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 are used for clarity in the examples below.

:: '''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.''}}}}

: 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.

: 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.

:: '''Example of a url that ends with a file name:''' <nowiki>http://</nowiki>www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/sound-setup.html

:: '''Example of a url that ends with a file name:''' <nowiki>http://</nowiki>www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/sound-setup.html

+

==== Internal ==== <!--T:20-->

−

==== Internal ====

+

<!--T:82-->

: The URL is within the PC-BSD wiki. The template [[template:local|''local'']] assists with localization of the internal links. The link URL will attempt to use a localized one of the form pagename/en where 'en' would be the language of the current page. The link name will attempt to use the localized name where the link is displayed. The separation of the anchor from the base URL allows it to be localized independently.

: The URL is within the PC-BSD wiki. The template [[template:local|''local'']] assists with localization of the internal links. The link URL will attempt to use a localized one of the form pagename/en where 'en' would be the language of the current page. The link name will attempt to use the localized name where the link is displayed. The separation of the anchor from the base URL allows it to be localized independently.

: 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 ''[[template:citelink|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.

: 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 ''[[template:citelink|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 '''<nowiki>{{Citelink|url=</nowiki>'''''complete URL'''''|txt='''''alternate text'''''}}'''

:: For the link use '''<nowiki>{{Citelink|url=</nowiki>'''''complete URL'''''|txt='''''alternate text'''''}}'''

: Also place a total of exactly one '''<nowiki><noinclude>{{refheading}}</noinclude></nowiki>''' at the bottom of the page, above the category links section.

: Also place a total of exactly one '''<nowiki><noinclude>{{refheading}}</noinclude></nowiki>''' at the bottom of the page, above the category links section.

+

===== Special External (standard) ===== <!--T:22-->

−

===== Special External (standard) =====

+

<!--T:84-->

: The URL is for a site not part of the PC-BSD wiki, but has a defined ''shortcut'' such as for wikipedia.

: The URL is for a site not part of the PC-BSD wiki, but has a defined ''shortcut'' such as for wikipedia.

: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.

+

−

+

<!--T:87-->

−

:''template:RM'' produces {{RM}} via '''<nowiki>{{RM}}</nowiki>''' which is simply an equivalent in place of typing the specific character.

+

: 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: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.

+

: ''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.

{{warning|icon32=Special care needs to be taken because the two are ''not'' equivalent. ''NavHome'', ''UseTOC'', and ''SwapTitle'' have ''title'' that may be assigned content that includes '''<nowiki>{{r}}</nowiki>.''' Internal links must include '''<nowiki>{{RM}}</nowiki>''' for the page name portion, but may include '''<nowiki>{{r}}</nowiki>''' for displayed text.}}

{{warning|icon32=Special care needs to be taken because the two are ''not'' equivalent. ''NavHome'', ''UseTOC'', and ''SwapTitle'' have ''title'' that may be assigned content that includes '''<nowiki>{{r}}</nowiki>.''' Internal links must include '''<nowiki>{{RM}}</nowiki>''' for the page name portion, but may include '''<nowiki>{{r}}</nowiki>''' for displayed text.}}

−

=== Named visual objects ===

+

=== Named visual objects === <!--T:27-->

−

+

+

<!--T:88-->

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.

+

<!--T:89-->

: These items could be further emphasized, but their names must be within quotes.

: 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.

: Example: Click on the “Submit” button along the lower edge of the “Compose response” window.

−

== Visual entities ==

+

== Translation considerations == <!--T:90-->

+

The methods and prescriptions described here may overlap and relate to many of the above topics in “text.”

+

=== Careful adjustment precautions === <!--T:91-->

+

Translation tags will cause the system to define a new translation element as well as the automated insertion of markers into the page markup which identify the element with a reference number. When elements are redefined, eliminated, or re-numbered manually, the system will make additional modifications to the page markup and may cause translations to become invalid or disappear entirely. It is very strongly suggested that only few knowledgeable editors or admins of the wiki attempt this in order to limit adverse results.

−

=== Commandline examples ===

+

=== “translate” tags === <!--T:92-->

+

It is important that elements defined by and contained between {{vtag|translate}} and {{vtag|/translate}} tags are comprised of the least amount of non-translated content as possible. The primary exceptions are template entities which may either automagically self-translate, be themselves non-translated units, or have content which is translated. These special entities must remain within the translated element due to variations of language which may affect word position, as an entity they must be allowed to be positioned differently as needed.

+

==== Examples ====

+

<!--T:93-->

+

:---content needed here---

+

:

+

== Visual entities == <!--T:28-->

+

+

=== Commandline examples === <!--T:29-->

+

+

<!--T:94-->

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).

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).

−

+

<!--T:95-->

; 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.

{{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.

Line 171:

Line 215:

}}

}}

−

=== Tables ===

+

=== Tables === <!--T:30-->

−

An addition of a class="spiffy_table" which further simplifies creation (as shown below), the init template includes it transparently. Including a caption places it into the tables group list.

+

+

<!--T:97-->

+

An addition of a class="spiffy_table" which further simplifies creation (as shown below), the init template includes it transparently. Including a caption places it into the tables group list.

+

<!--T:98-->

{{tbl-init|caption= 1a. Comparison of table syntax}}

{{tbl-init|caption= 1a. Comparison of table syntax}}

!Frequently used wiki markup (replace this)

!Frequently used wiki markup (replace this)

Line 182:

Line 228:

|This method may involve slightly more typing but produces a very sharp result such as ''this table itself'' and added the feature of a table index.

|This method may involve slightly more typing but produces a very sharp result such as ''this table itself'' and added the feature of a table index.

: 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. Please note a small adjustment to this rule in the ''noinclude block'' section below.

: 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. Please note a small adjustment to this rule in the ''noinclude block'' section below.

−

=== Special Text boxes ===

+

=== Special Text boxes === <!--T:31-->

+

+

<!--T:99-->

Some comments within the content of the page need or should be clearly separated from the rest of the text to both give better context and improved awareness.

Some comments within the content of the page need or should be clearly separated from the rest of the text to both give better context and improved awareness.

+

==== Notes ==== <!--T:32-->

−

==== Notes ====

+

<!--T:100-->

−

: Often we need to specifically call attention to a particular caveat, or other tidbit of information that is ''not mission critical.''

+

: Often we need to specifically call attention to a particular detail, or provide other information that is ''not mission critical.''

: {{note|This is an example that is simply text.'''<nowiki>{{</nowiki>note{{pipe}}'''''text'''''<nowiki>}}</nowiki>'''}}

: {{note|This is an example that is simply text.'''<nowiki>{{</nowiki>note{{pipe}}'''''text'''''<nowiki>}}</nowiki>'''}}

−

: {{note|icon64=Include an icon for larger notes by assigning the text to ''icon64'' when the template is used, such as '''<nowiki>{{</nowiki>note{{pipe}}icon64='''''text'''''<nowiki>}}</nowiki>'''. This icon is the classic ''tie a string around your finger to help remember'', the green triangle is used in hopes of implying that you can continue safely.<br/><br/>As you can see with this text box, the message content neatly remains to the right of the icon and is of a somewhat smaller size than the surrounding page. This right indent will continue with the icon centered vertically, even when there is sufficient text that the column of lines in the message are much larger than the height of the icon. The same effect with 32px, 48px, or 64px icons and text content works for the other two icon message boxes described below. To apply the other sizes of icon, simply assign the text to 'icon32' or 'icon48' as was done for 'icon64' here. It may make sense to use a smaller icon for smaller amounts of text, however, normally the box will adjust to match both the page space and content size. A further option may be used to cause the box to position itself to the right side of the page, if an additional field of class=rightfloat is included with the invocation such as <nowiki>{{note|class=rightfloat|text content}}.</nowiki> Various formatting within the box is also possible.}}

+

: {{note|icon64=Include an icon for larger notes by assigning the text to ''icon64'' when the template is used, such as '''<nowiki>{{</nowiki>note{{pipe}}icon64='''''text'''''<nowiki>}}</nowiki>'''. This icon is the classic ''tie a string around your finger to help remember'', the green triangle is used in hopes of implying that you can continue safely.{{br}}{{br}}As you can see with this text box, the message content neatly remains to the right of the icon and is of a somewhat smaller size than the surrounding page. This right indent will continue with the icon centered vertically, even when there is sufficient text that the column of lines in the message are much larger than the height of the icon. The same effect with 32px, 48px, or 64px icons and text content works for the other two icon message boxes described below. To apply the other sizes of icon, simply assign the text to 'icon32' or 'icon48' as was done for 'icon64' here. It may make sense to use a smaller icon for smaller amounts of text, however, normally the box will adjust to match both the page space and content size. A further option may be used to cause the box to position itself to the right side of the page, if an additional field of class=rightfloat is included with the invocation such as <nowiki>{{note|class=rightfloat|text content}}.</nowiki> Various formatting within the box is also possible.}}

−

==== Warning ====

+

==== Warning ==== <!--T:33-->

+

+

<!--T:101-->

: Some instructions have frustrating or annoying consequences and therefore should be emphasized.

: Some instructions have frustrating or annoying consequences and therefore should be emphasized.

: {{warning|icon64=A verbose and descriptive warning. The concept behind the icon is that something may have been missed, stop and check, investigate. '''<nowiki>{{</nowiki>warning{{pipe}}icon64='''''text'''''<nowiki>}}</nowiki>'''}}

: {{warning|icon64=A verbose and descriptive warning. The concept behind the icon is that something may have been missed, stop and check, investigate. '''<nowiki>{{</nowiki>warning{{pipe}}icon64='''''text'''''<nowiki>}}</nowiki>'''}}

+

==== Dangerous ==== <!--T:34-->

−

==== Dangerous ====

+

<!--T:102-->

: Some instructions are critically dangerous and may result in serious harm if a mistake is made.

: Some instructions are critically dangerous and may result in serious harm if a mistake is made.

: {{danger|icon64=The text content probably should default to a surfeit of '''bold''' or '''''bold and italic'''''. This icon hopes to clearly indicate that possible damage to the PC may be involved. '''<nowiki>{{</nowiki>danger{{pipe}}icon64='''''text'''''<nowiki>}}</nowiki>'''}}

: {{danger|icon64=The text content probably should default to a surfeit of '''bold''' or '''''bold and italic'''''. This icon hopes to clearly indicate that possible damage to the PC may be involved. '''<nowiki>{{</nowiki>danger{{pipe}}icon64='''''text'''''<nowiki>}}</nowiki>'''}}

−

== Topics structure ==

+

== Topics structure == <!--T:35-->

−

+

+

<!--T:103-->

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.

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.

# A bulleted list which begins uppercase. Whether or not it ends in punctuation depends upon the size of the list. For example:<br />

+

# A bulleted list which begins uppercase. Whether or not it ends in punctuation depends upon the size of the list. For example:{{br}}

−

#* 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.<br />

+

#* 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.{{br}}

−

#* 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.<br />

+

#* 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.{{br}}

−

# 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:<br />

+

# 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:{{br}}

−

#: '''Size on Disk:''' indicates the amount of space being used by the jail.<br />

+

#: '''Size on Disk:''' indicates the amount of space being used by the jail.{{br}}

#:: 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.

#:: 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.

−

+

<!--T:106-->

; 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>. {{highlight|text=This still needs verification whether a ''hard enter'' or <nowiki><br /></nowiki> are needed.}}

+

:: Suggestion used in revision above, is addition of {{ttag|br}}. {{highlight|text=This still needs verification whether a ''hard enter'' or {{ttag|br}} are needed.}}

−

+

:The {{ttag|br}} (br template) provides the proper wiki markup style {{vtag|br /}} which when incorrect (ie. {{vtag|br}} or {{vtag|br/}}), the translation system may flag and prevent saving of a translation element.

−

=== Collation ===

+

+

=== Collation === <!--T:39-->

+

<!--T:107-->

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.

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.

−

+

<!--T:40-->

; Logical

; Logical

: Putting things in order of precedence; from first task to last task, or first item naturally listed to last item.

: Putting things in order of precedence; from first task to last task, or first item naturally listed to last item.

−

:# Introduction<br>

+

:# Introduction{{br}}

−

:# Pre-Installation Tasks<br>

+

:# Pre-Installation Tasks{{br}}

−

:# Installing PC-BSD<br>

+

:# Installing PC-BSD{{br}}

:# Post Installation Configuration and Installation Troubleshooting

:# Post Installation Configuration and Installation Troubleshooting

−

+

<!--T:41-->

; Quality or significance

; Quality or significance

: Organizing according to the importance of the item or its membership in a specific group type.

: Organizing according to the importance of the item or its membership in a specific group type.

Line 279:

Line 332:

:: Window Maker

:: Window Maker

−

+

<!--T:42-->

; Alphabetical

; Alphabetical

: Organizing items by name according to the alphabet.

: Organizing items by name according to the alphabet.

Line 287:

Line 340:

:: XFCE4

:: XFCE4

−

+

<!--T:43-->

; Chronological

; Chronological

: Placing items in order according to date.

: Placing items in order according to date.

Line 293:

Line 346:

: Items are placed in reverse order, most recent first and oldest last.

: Items are placed in reverse order, most recent first and oldest last.

−

+

<!--T:44-->

; Ordinal

; Ordinal

: The items are listed according to number.

: The items are listed according to number.

Line 305:

Line 358:

:# second text

:# second text

−

== Images ==

+

== Images == <!--T:45-->

+

<!--T:108-->

{{note|align=right|width=40%|icon64=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.}}

{{note|align=right|width=40%|icon64=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.}}

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.

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.

−

{{caveat|icon64=Since the wiki markup does not prompt for an ''alt'' tag along with other deficiencies, there will need to be an 'image' template which will replace the current <nowiki>[[File:blah.png|thumb|'''caption''']]</nowiki> method.<br/>{{orangelight|This is a warning that another site-wide change will be coming.}}}}

+

{{caveat|icon64=Since the wiki markup does not prompt for an ''alt'' tag along with other deficiencies, there will need to be an 'image' template which will replace the current <nowiki>[[File:blah.png|thumb|'''caption''']]</nowiki> method.{{br}}{{orangelight|This is a warning that another site-wide change will be coming.}}}}

−

=== Format ===

+

+

=== Format === <!--T:46-->

−

==== Required ====

+

==== Required ==== <!--T:47-->

+

+

<!--T:109-->

* Portable Network Graphic (png).

* Portable Network Graphic (png).

* 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.

* Where possible, resize windows so that their entire content can be shown without scrollbars.

* Where possible, resize windows so that their entire content can be shown without scrollbars.

−

== Administrative ==

+

== Administrative == <!--T:53-->

−

=== Categories ===

+

=== Categories === <!--T:54-->

+

+

<!--T:116-->

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

''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

; Membership

Line 397:

Line 463:

: The category chosen may be determined by the description given on the individual category pages.

: The category chosen may be determined by the description given on the individual category pages.

−

+

<!--T:55-->

; Format

; Format

: 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.''

: 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.''

−

+

<!--T:56-->

; Description

; Description

: The categories themselves should have some sort of explanation to guide their use.

: The categories themselves should have some sort of explanation to guide their use.

−

=== Page structure ===

+

=== Page structure === <!--T:57-->

−

+

+

<!--T:58-->

; Header

; Header

−

: Each handbook page contains a [[template:NavHeader|3-icon navigation panel]] across the top, {{txtbox|box=

+

: Each handbook page contains a [[template:NavHeader|3-icon navigation panel]] across the top,

: Each page should contain a group of category links at the bottom, along with a Refheading and GroupListHeading as applicable (may be enclosed with comment markers if not yet needed). No further text or spaces following, though in some instances a comment is present with nothing following it. The categories included here should become more general as the list continues downward, an example series in order would be: GNOME2, Desktops, Handbook. Although 'GNOME2' would be auto-included by the NavHeader. The translate tag allows the page to be marked for translation, while the languages tag determines where links to translations of the current page will be displayed.

+

: Each page should contain a group of category links at the bottom, along with a Refheading and GroupListHeading as applicable (sometimes enclosed with comment markers if not yet needed). No further text or spaces following, though in some instances a comment is present with nothing following it. The categories included here should become more general as the list continues downward, an example series in order would be: GNOME2, Desktops, Handbook. Although "GNOME2" would be auto-included by the NavHeader. The translate tag allows the page to be marked for translation, while the languages tag determines where links to translations of the current page will be displayed.

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. Further investigation into the dead-tree/published version(s) needs to be done so the wiki version might hope to match or have a consistent header structure if visually different. (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.)

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. Further investigation into the dead-tree/published version(s) needs to be done so the wiki version might hope to match or have a consistent header structure if visually different. (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.)

−

+

<!--T:63-->

{|align="center" style=" border: #aaaaaa dashed 1px; width:97%;"

{|align="center" style=" border: #aaaaaa dashed 1px; width:97%;"

|

|

−

= Page title =

+

= Page title = <!--T:118-->

−

<nowiki>= Page title =</nowiki><br>

+

<!--T:119-->

+

<nowiki>= Page title =</nowiki>{{br}}

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.

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 == <!--T:120-->

−

<nowiki>== Level 2 ==</nowiki><br>

+

<!--T:121-->

+

<nowiki>== Level 2 ==</nowiki>{{br}}

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

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

−

=== Level 3 ===

+

=== Level 3 === <!--T:122-->

−

<nowiki>=== Level 3 ===</nowiki><br>

+

<!--T:123-->

+

<nowiki>=== Level 3 ===</nowiki>{{br}}

(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.

(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 ====

+

==== Level 4 ==== <!--T:124-->

−

<nowiki>==== Sub-heading ====</nowiki><br>

+

<!--T:125-->

+

<nowiki>==== Sub-heading ====</nowiki>{{br}}

This level exists but is generally unused currently.

This level exists but is generally unused currently.

−

===== Level 5 =====

+

===== Level 5 ===== <!--T:126-->

−

<nowiki>===== Level 5 =====</nowiki><br>

+

<!--T:127-->

+

<nowiki>===== Level 5 =====</nowiki>{{br}}

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

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

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. Although this page may not be specifically dedicated to how to edit the wiki, there is plenty of information included here that describes how to use various templates for certain situations. Until a page is developed which does focus on editing the wiki, the information here shall be considered a good start. A template quick reference or an editor's stylesheet may also be helpful.

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.

Use words and phrases with the same meaning; multiple types of sentence structure. This will increase interest and also by use of synonyms will improve the chance that the text will be understood, especially with regard to translations or non-native English readers.

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.

Especially within a list of updates to the current version, the word now ought to be omitted. By the very nature of pointing out that it is a list of revised features, it implies its relationship to the current documented version and that an adjustment has been made. Where possible the alternative of providing a comparison of the former method, application, or feature which contrasts with the current one is sufficient (and provides an improved explanation in context). Further explanation may be added as in the example below:

The login manager uses PCDM which replaces the former GDM in order to reduce associated dependencies when GNOME is not also installed.

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 are used for clarity in the examples below.

Replace this: You can find more information about hardware compatibility here.[4]

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

The URL is within the PC-BSD wiki. The template local assists with localization of the internal links. The link URL will attempt to use a localized one of the form pagename/en where 'en' would be the language of the current page. The link name will attempt to use the localized name where the link is displayed. The separation of the anchor from the base URL allows it to be localized independently.

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.

The URL would otherwise be obscenely long especially due to defining languages the external site has localized.

{{Citelink|shortcut|txtAb=alternate text}}

Example of abbreviation use: [https://creativecommons.org/licenses/by/3.0/deed.en Creative Commons] would be{{citelink|url=https://creativecommons.org/licenses/by/3.0/deed.{{testLangURL|es|es_ES|ca|de|eo|fr|id|it|hu|no|nl|pl|pt|pt_BR|fi|sv|is|el|ru|uk|zh|zh_TW|ko}}|txt=Creative Commons}}but due to txtAb is now {{citelink|ccby3|txtAb=Creative Commons}}

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.

Special care needs to be taken because the two are not equivalent. NavHome, UseTOC, and SwapTitle have title that may be assigned content that includes {{r}}. Internal links must include {{RM}} for the page name portion, but may include {{r}} for displayed text.

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.

Translation tags will cause the system to define a new translation element as well as the automated insertion of markers into the page markup which identify the element with a reference number. When elements are redefined, eliminated, or re-numbered manually, the system will make additional modifications to the page markup and may cause translations to become invalid or disappear entirely. It is very strongly suggested that only few knowledgeable editors or admins of the wiki attempt this in order to limit adverse results.

It is important that elements defined by and contained between <translate> and </translate> tags are comprised of the least amount of non-translated content as possible. The primary exceptions are template entities which may either automagically self-translate, be themselves non-translated units, or have content which is translated. These special entities must remain within the translated element due to variations of language which may affect word position, as an entity they must be allowed to be positioned differently as needed.

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.

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. Please note a small adjustment to this rule in the noinclude block section below.

Often we need to specifically call attention to a particular detail, or provide other information that is not mission critical.

NOTE: This is an example that is simply text.{{note|text}}

Include an icon for larger notes by assigning the text to icon64 when the template is used, such as {{note|icon64=text}}. This icon is the classic tie a string around your finger to help remember, the green triangle is used in hopes of implying that you can continue safely.

As you can see with this text box, the message content neatly remains to the right of the icon and is of a somewhat smaller size than the surrounding page. This right indent will continue with the icon centered vertically, even when there is sufficient text that the column of lines in the message are much larger than the height of the icon. The same effect with 32px, 48px, or 64px icons and text content works for the other two icon message boxes described below. To apply the other sizes of icon, simply assign the text to 'icon32' or 'icon48' as was done for 'icon64' here. It may make sense to use a smaller icon for smaller amounts of text, however, normally the box will adjust to match both the page space and content size. A further option may be used to cause the box to position itself to the right side of the page, if an additional field of class=rightfloat is included with the invocation such as {{note|class=rightfloat|text content}}. Various formatting within the box is also possible.

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.

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.

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.

The {{br}} (br template) provides the proper wiki markup style <br /> which when incorrect (ie. <br> or <br/>), the translation system may flag and prevent saving of a translation element.

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.

Introduction

Pre-Installation Tasks

Installing PC-BSD

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.

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.

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.

Since the wiki markup does not prompt for an alt tag along with other deficiencies, there will need to be an 'image' template which will replace the current [[File:blah.png|thumb|'''caption''']] method. This is a warning that another site-wide change will be coming.

Must limit to a maximum size of 800x600, this allows the entire image to remain visible even on a 1024x768 screen size.

Use background transparency where things such as irregularly shaped icons or rounded window corners are used.

Avoid window themes that include translucency or transparency of window content, title, or decorations. These can lead to less clear or unreadable titles, decorations, or content.

Identify each graphic with a Figure number consisting of the section number of the page followed by a letter, alphabetically with 'a' for the first graphic and 'b' for the second and so forth. Directly after the letter, place a colon and a brief description, preferably more concise than its mention within other text on the page.

Begin with an unmodified/default desktop configuration- including only the installed software to be discussed.

Emphatically recommended to useVirtual Box with a desktop of 4:3 ratio, Host name: Demo System, Username: PC-BSD_User, which would allow for consistency, universality, and genericness.

Use a white desktop background to easily capture individual windows or icons.

Expand the Virtualbox window to be larger than the enclosed desktop (desktop will be surrounded with a white frame).

The excess white background of cropped images is easily selectable by contiguous shape or color. Next, either invert the selection to cut/copy then paste into a new canvas, or delete the selection so it will be replaced with the alpha transparency.

When cropping selections, use the zoom tool to enlarge the work area to prevent loss of details or enable addition of transparency for rounded corners.

Where possible, resize windows so that their entire content can be shown without scrollbars.

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.

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 (sometimes enclosed with comment markers if not yet needed). No further text or spaces following, though in some instances a comment is present with nothing following it. The categories included here should become more general as the list continues downward, an example series in order would be: GNOME2, Desktops, Handbook. Although "GNOME2" would be auto-included by the NavHeader. The translate tag allows the page to be marked for translation, while the languages tag determines where links to translations of the current page will be displayed.

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. Further investigation into the dead-tree/published version(s) needs to be done so the wiki version might hope to match or have a consistent header structure if visually different. (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 =
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.