Wiki source for WikiStyleGuide
{{include tonguesWikiStyleGuide}}
[[HomePage]] > [[WikiIndex Wiki Index]]
======Wiki Style Guide======
=====The basics=====
The basic skeleton of any wiki page is composed of 4 elements; in order of appearance:
- Breadcrumbs
- Title
- (The content)
- Category footer
Both breadcrumbs and category footers are systems to ease navigation and location of pages; having both of them is a wiki page is desirable, having at least one of them is necessary so that other users can later find the page.
==**Breadcrumbs**==
~[[Breadcrumb]]s are used at the top of the articles. They point to index pages and help give the wiki structure. If a page has no other pages linking to it and no category, then a user might not find it. Think about which index the page belongs to. For example, media player software would go on the Multimedia software index, code:
~[[HomePage]] > [[SoftwareIndex Software Index]] > [[SoftwareMultimedia Multimedia]]
~%%[[HomePage]] > [[SoftwareIndex Software Index]] > [[SoftwareMultimedia Multimedia]]%%
(The double square brackets are used to link to internal pages within the wiki. See: [[http://puppylinux.org/wikka/WikiStyleGuide#hn_Links Links]])
//How do I determine the breadcrumbs for my page?//
One possible system is finding another wiki page that belongs to a similar family via the search bar on top of the page, and then copy-pasting its existing breadcrumbs when we create our new page.
==**Titles**==
Every wiki page must have a title, which will surely be the same name you gave to the page when you created it. To designate a text as title, you must format it as header. You can do so in 2 ways: a) selecting the text and pressing the H1-H5 buttons in the text editor. b) Surrounding the text with equal signs (=), from 6 to 2, depending on the size you want. The page title's header should have the biggest size of all the headers in the page, for obvious reasons.
~##""======Really big header======""##
~
======Really big header======
~(or: select the text and press H1 in the editor)
~
~##""=====Rather big header=====""##
~=====Rather big header=====
~(or: select the text and press H2 in the editor)
~
~##""====Medium header====""##
~====Medium header====
~(or: select the text and press H3 in the editor)
~
~##""===Not-so-big header===""##
~===Not-so-big header===
~(or: select the text and press H4 in the editor)
~
~##""==Smallish header==""##
~==Smallish header==
~(or: select the text and press H5 in the editor)
~You can also use bold (two asterisks on each side, or select the text and press B in the editor), to designate article sub-section
~##""**Sub-Section**""##
~**Sub-Section**
~
~
~Headers can be directly linked to by writing a link to the page, followed by the #hn_ termination and then the name of the title we want to be directed to. For example: [[http://puppylinux.org/wikka/WikiStyleGuide#hn_Breadcrumbs]] (NOTE: this seems to work only with one word titles -the wiki does not process spaces-. If someone knows how to do internal linking to titles with more than one word, please complete).
==**Category Footers**==
~Articles should include a Category footer, for example
~%%
(line return here)
(line return here)
----
==Categories==
CategoryExample%%
This fragment of code must be inserted at the bottom of the page, for unity of style. To see a list of all the current existing categories, press the link "Categories", on the top left corner of any wiki page, also here if you don't want to scroll up: [[CategoryCategory Categories]]
//How do I create or modify categories?//
Visit the wiki's [[WikiCategory categories]] page for more in-depth information.
With only these elements (breadcrumbs, title, and category footer), you are already qualified to [[CreateNewPage Create a new page]] or [[EditExistingPage Edit an existing one]]. You can also read on to learn about what other options this wiki offers for different contents.
=====More advanced stuff=====
==Links==
The easiest way to get you started with links is using the chain icon you'll find in the wiki's text editor; if you press it, it will paste the following link template:
%%[[http://www.example.com Page Title]]%%
It is pretty self-evident on how a link must be inserted. If you are linking to a page within the wiki, there is the additional advantage that you don't need to find and type its complete URL, but only the name of the page inCase format (initial capitals and no spaces). For example:
%%[[http://puppylinux.org/wikka/WikiIndex Go to the Index page]]%%
[[http://puppylinux.org/wikka/WikiIndex Go to the Index page]]
works just the same as
%%[[WikiIndex Go to the Index page]]%%
[[WikiIndex Go to the Index page]]
For more ways to create links, refer to the [[FormattingRules Format]] page.
It is considered a good practice to link internal to the Wiki where possible. This reduces jumping back and forth between websites. At the end of a pages relevant internal links are often listed under **Also on the Wiki** and relevant external links **Related Websites**.
==Images==
~
~To insert an image, you have to point to an external link where the image resides, as this wiki does not provide in itself options for image storage.
~When you insert the image, provide it with a title text and alt text (the text that appears when you hover with the mouse over the image-try it in the example below). This enables people who use screen readers to better understand articles.
~{{image url="http://www.murga-linux.com/puppy/viewtopic.php?mode=attach&id=57682" title="filetype icon" alt="filetype icon"}}
~%%{{image url="http://www.murga-linux.com/puppy/viewtopic.php?mode=attach&id=57682" title="filetype icon" alt="filetype icon"}}%%
~Text and graphics are preferred for articles; many people either do not have access to broadband or can’t afford it. Also, video is of no use to people using [[http://www.thefreecountry.com/utilities/free-screen-readers.shtml Screen Readers]].
~Vertically tall graphics should be placed on the right, so text may flow up and left of them. Vertically short graphics may simply be placed normally and thus will appear on the left (the default option).
~Alternatively, the graphic can be sized using height and width attributes.
==Forum Links==
~Notice that the information on the second field of a link can be omitted. But, if it isn't obvious from the url where a link goes, please provide this information. An example is forum links, as they only show a number and not the thread's or post's title. Example:
~[[http://www.murga-linux.com/puppy/viewtopic.php?t=80232 Help needed writing the Wiki thread]]
~%%[[http://www.murga-linux.com/puppy/viewtopic.php?t=80232 Help needed writing the Wiki thread]]%%
~When you link to Puppy related software offered for download (pet files etc), please provide a direct link or link to where it can be downloaded. It is helpful to indicate the program version in the link, and also adding some information about who the packager is. Software icons go above the title. For example:
~
~{{image url="http://qtractor.sourceforge.net/image/qtractor.png" link="http://qtractor.sourceforge.net/qtractor-index.html" title="qtractor icon" alt="qtractor icon"}}
~====Qtractor====
~%%{{image url="http://qtractor.sourceforge.net/image/qtractor.png" link="http://qtractor.sourceforge.net/qtractor-index.html" title="qtractor icon" alt="qtractor icon"}}
====Qtractor====%%
==Paragraph Indents==
~Paragraphs should come immediately under the title and be indented using a tab (use tab key or a ##~## character). An exception to the using of indents is categories, and also tables due to a bug currently existing in Wikka (see above).
==Tables==
~They can be used to present data or to create columns.
~Here is an example of table code:
~|=|Header 1|=|Header 2||
||Cell 1||Cell 2||
~%%|=|Header 1|=|Header 2||
||Cell 1||Cell 2||%%
~**Note: **indents cannot be used in tables due to a current error in Wikka that causes breaks in the formatting.
==Red text==
~Should be used for warnings and alerts. Do not use it in titles.
~{{color text="Warning:" c="red"}}
~%%{{color text="Warning:" c="red"}}%%
==Underline==
~Use underline to call attention to text within the article (not in titles).
~__significant__
~%%__significant__%%
==Bullet Points==
~Use a list to place bullets on special points within articles.
~%% - This is a bulleted point%%
~- This is a bulleted point
~
==""CamelCase"" and internal links==
~[[Docs:CamelCase CamelCase]] is the traditional notation used in wikis to denote internal links (i.e., links from one page of the wiki to another). It consists in words assembled with their initial letter in capital and no spaces in between (""ForExampleLikeThis"").
~
~From version 1.3., Wikka does not require such notation. However, if you create a link that is not ""CamelCase"" style, you need to put it inside double square brackets, for example:
~[[alsa]]
~%%[[alsa]]%%
~To use ""CamelCase"" notation without linking it to any page, use the double quotes
~
~""LinkNotWanted""
~%%""LinkNotWanted""%%
~If a page doesn't exist but would be useful in the future - do create the link; this will let other people know that the page is desired.
~
~For more information see the section [[http://puppylinux.org/wikka/WikiStyleGuide#hn_Links Links]] up in this page.
==Colors==
~Example, {{color text="coming:" c="teal"}} {{color text="soon" c="fuchsia"}}
~%%{{color text="color" c="teal"}} {{color text="color text" c="fuchsia"}}%%
==Redirecting==
~If there are two or more different pages names that could apply then 'redirect' may be useful. For example, if there is a page for Orange, you can create a Oranges empty page, that will redirect to that other page by inserting inside it this code,
~%%{{redirect target="Oranges"}}%%
==Also on the Wiki==
~LanguageBars - the bar at the top of many pages allowing access different translations
~FormattingRules
----
==Categories==
CategoryWiki
[[HomePage]] > [[WikiIndex Wiki Index]]
======Wiki Style Guide======
=====The basics=====
The basic skeleton of any wiki page is composed of 4 elements; in order of appearance:
- Breadcrumbs
- Title
- (The content)
- Category footer
Both breadcrumbs and category footers are systems to ease navigation and location of pages; having both of them is a wiki page is desirable, having at least one of them is necessary so that other users can later find the page.
==**Breadcrumbs**==
~[[Breadcrumb]]s are used at the top of the articles. They point to index pages and help give the wiki structure. If a page has no other pages linking to it and no category, then a user might not find it. Think about which index the page belongs to. For example, media player software would go on the Multimedia software index, code:
~[[HomePage]] > [[SoftwareIndex Software Index]] > [[SoftwareMultimedia Multimedia]]
~%%[[HomePage]] > [[SoftwareIndex Software Index]] > [[SoftwareMultimedia Multimedia]]%%
(The double square brackets are used to link to internal pages within the wiki. See: [[http://puppylinux.org/wikka/WikiStyleGuide#hn_Links Links]])
//How do I determine the breadcrumbs for my page?//
One possible system is finding another wiki page that belongs to a similar family via the search bar on top of the page, and then copy-pasting its existing breadcrumbs when we create our new page.
==**Titles**==
Every wiki page must have a title, which will surely be the same name you gave to the page when you created it. To designate a text as title, you must format it as header. You can do so in 2 ways: a) selecting the text and pressing the H1-H5 buttons in the text editor. b) Surrounding the text with equal signs (=), from 6 to 2, depending on the size you want. The page title's header should have the biggest size of all the headers in the page, for obvious reasons.
~##""======Really big header======""##
~
======Really big header======
~(or: select the text and press H1 in the editor)
~
~##""=====Rather big header=====""##
~=====Rather big header=====
~(or: select the text and press H2 in the editor)
~
~##""====Medium header====""##
~====Medium header====
~(or: select the text and press H3 in the editor)
~
~##""===Not-so-big header===""##
~===Not-so-big header===
~(or: select the text and press H4 in the editor)
~
~##""==Smallish header==""##
~==Smallish header==
~(or: select the text and press H5 in the editor)
~You can also use bold (two asterisks on each side, or select the text and press B in the editor), to designate article sub-section
~##""**Sub-Section**""##
~**Sub-Section**
~
~
~Headers can be directly linked to by writing a link to the page, followed by the #hn_ termination and then the name of the title we want to be directed to. For example: [[http://puppylinux.org/wikka/WikiStyleGuide#hn_Breadcrumbs]] (NOTE: this seems to work only with one word titles -the wiki does not process spaces-. If someone knows how to do internal linking to titles with more than one word, please complete).
==**Category Footers**==
~Articles should include a Category footer, for example
~%%
(line return here)
(line return here)
----
==Categories==
CategoryExample%%
This fragment of code must be inserted at the bottom of the page, for unity of style. To see a list of all the current existing categories, press the link "Categories", on the top left corner of any wiki page, also here if you don't want to scroll up: [[CategoryCategory Categories]]
//How do I create or modify categories?//
Visit the wiki's [[WikiCategory categories]] page for more in-depth information.
With only these elements (breadcrumbs, title, and category footer), you are already qualified to [[CreateNewPage Create a new page]] or [[EditExistingPage Edit an existing one]]. You can also read on to learn about what other options this wiki offers for different contents.
=====More advanced stuff=====
==Links==
The easiest way to get you started with links is using the chain icon you'll find in the wiki's text editor; if you press it, it will paste the following link template:
%%[[http://www.example.com Page Title]]%%
It is pretty self-evident on how a link must be inserted. If you are linking to a page within the wiki, there is the additional advantage that you don't need to find and type its complete URL, but only the name of the page inCase format (initial capitals and no spaces). For example:
%%[[http://puppylinux.org/wikka/WikiIndex Go to the Index page]]%%
[[http://puppylinux.org/wikka/WikiIndex Go to the Index page]]
works just the same as
%%[[WikiIndex Go to the Index page]]%%
[[WikiIndex Go to the Index page]]
For more ways to create links, refer to the [[FormattingRules Format]] page.
It is considered a good practice to link internal to the Wiki where possible. This reduces jumping back and forth between websites. At the end of a pages relevant internal links are often listed under **Also on the Wiki** and relevant external links **Related Websites**.
==Images==
~
~To insert an image, you have to point to an external link where the image resides, as this wiki does not provide in itself options for image storage.
~When you insert the image, provide it with a title text and alt text (the text that appears when you hover with the mouse over the image-try it in the example below). This enables people who use screen readers to better understand articles.
~{{image url="http://www.murga-linux.com/puppy/viewtopic.php?mode=attach&id=57682" title="filetype icon" alt="filetype icon"}}
~%%{{image url="http://www.murga-linux.com/puppy/viewtopic.php?mode=attach&id=57682" title="filetype icon" alt="filetype icon"}}%%
~Text and graphics are preferred for articles; many people either do not have access to broadband or can’t afford it. Also, video is of no use to people using [[http://www.thefreecountry.com/utilities/free-screen-readers.shtml Screen Readers]].
~Vertically tall graphics should be placed on the right, so text may flow up and left of them. Vertically short graphics may simply be placed normally and thus will appear on the left (the default option).
~Alternatively, the graphic can be sized using height and width attributes.
==Forum Links==
~Notice that the information on the second field of a link can be omitted. But, if it isn't obvious from the url where a link goes, please provide this information. An example is forum links, as they only show a number and not the thread's or post's title. Example:
~[[http://www.murga-linux.com/puppy/viewtopic.php?t=80232 Help needed writing the Wiki thread]]
~%%[[http://www.murga-linux.com/puppy/viewtopic.php?t=80232 Help needed writing the Wiki thread]]%%
~When you link to Puppy related software offered for download (pet files etc), please provide a direct link or link to where it can be downloaded. It is helpful to indicate the program version in the link, and also adding some information about who the packager is. Software icons go above the title. For example:
~
~{{image url="http://qtractor.sourceforge.net/image/qtractor.png" link="http://qtractor.sourceforge.net/qtractor-index.html" title="qtractor icon" alt="qtractor icon"}}
~====Qtractor====
~%%{{image url="http://qtractor.sourceforge.net/image/qtractor.png" link="http://qtractor.sourceforge.net/qtractor-index.html" title="qtractor icon" alt="qtractor icon"}}
====Qtractor====%%
==Paragraph Indents==
~Paragraphs should come immediately under the title and be indented using a tab (use tab key or a ##~## character). An exception to the using of indents is categories, and also tables due to a bug currently existing in Wikka (see above).
==Tables==
~They can be used to present data or to create columns.
~Here is an example of table code:
~|=|Header 1|=|Header 2||
||Cell 1||Cell 2||
~%%|=|Header 1|=|Header 2||
||Cell 1||Cell 2||%%
~**Note: **indents cannot be used in tables due to a current error in Wikka that causes breaks in the formatting.
==Red text==
~Should be used for warnings and alerts. Do not use it in titles.
~{{color text="Warning:" c="red"}}
~%%{{color text="Warning:" c="red"}}%%
==Underline==
~Use underline to call attention to text within the article (not in titles).
~__significant__
~%%__significant__%%
==Bullet Points==
~Use a list to place bullets on special points within articles.
~%% - This is a bulleted point%%
~- This is a bulleted point
~
==""CamelCase"" and internal links==
~[[Docs:CamelCase CamelCase]] is the traditional notation used in wikis to denote internal links (i.e., links from one page of the wiki to another). It consists in words assembled with their initial letter in capital and no spaces in between (""ForExampleLikeThis"").
~
~From version 1.3., Wikka does not require such notation. However, if you create a link that is not ""CamelCase"" style, you need to put it inside double square brackets, for example:
~[[alsa]]
~%%[[alsa]]%%
~To use ""CamelCase"" notation without linking it to any page, use the double quotes
~
~""LinkNotWanted""
~%%""LinkNotWanted""%%
~If a page doesn't exist but would be useful in the future - do create the link; this will let other people know that the page is desired.
~
~For more information see the section [[http://puppylinux.org/wikka/WikiStyleGuide#hn_Links Links]] up in this page.
==Colors==
~Example, {{color text="coming:" c="teal"}} {{color text="soon" c="fuchsia"}}
~%%{{color text="color" c="teal"}} {{color text="color text" c="fuchsia"}}%%
==Redirecting==
~If there are two or more different pages names that could apply then 'redirect' may be useful. For example, if there is a page for Orange, you can create a Oranges empty page, that will redirect to that other page by inserting inside it this code,
~%%{{redirect target="Oranges"}}%%
==Also on the Wiki==
~LanguageBars - the bar at the top of many pages allowing access different translations
~FormattingRules
----
==Categories==
CategoryWiki
