Help:Style Guidelines
m (→Text highlighting guidelines) |
|||
| (4 intermediate revisions by one user not shown) | |||
| Line 11: | Line 11: | ||
This is how the article you're reading right now is formatted. | This is how the article you're reading right now is formatted. | ||
| − | ==Text guidelines== | + | ==Text highlighting guidelines== |
When showing an interactive console session, please use a leading space in front of every line (to put the session in a little "box" in the article when it renders) and use the triple-singlequote (<nowiki>'''</nowiki>) wikitag to bold user-entered text. For example: | When showing an interactive console session, please use a leading space in front of every line (to put the session in a little "box" in the article when it renders) and use the triple-singlequote (<nowiki>'''</nowiki>) wikitag to bold user-entered text. For example: | ||
| Line 19: | Line 19: | ||
ph34r# | ph34r# | ||
| − | + | The leading space can also be used for code from console output, and file contents. | |
| + | <nowiki>#!/bin/sh</nowiki> | ||
| + | exec xorg</nowiki> | ||
| + | <nowiki>#This text is commented out</nowiki> | ||
| − | * ''<nowiki>{{ | + | Here are templates for adding clarity to text. Templates need <nowiki><nowiki></nowiki> tags to properly display special characters. |
| + | * For commandline text within paragraphs use {{yhl|''<nowiki>{{cmd|kldstat -v}}</nowiki>''}} to produce {{cmd|kldstat -v}}. | ||
| − | * | + | * For code console output or file contents use {{yhl|<nowiki>{{code|:Command not found.}}</nowiki>}} for {{code|:Command not found.}}. |
| − | + | * Displaying files and directories use the same code, but end directory descriptions in "/". {{yhl|''<nowiki>{{file|/usr/local/etc/}}</nowiki>''}} produces {{file|/usr/local/etc/}} for directories. {{yhl|''<nowiki>{{file|/etc/rc.conf}}</nowiki>''}} produces {{file|/etc/rc.conf}} for files. | |
| − | ''<nowiki>{{port|ftp/curl|BSD}}</nowiki>'' produces {{port|ftp/curl|BSD}} for ports in ports-tree, and optionally it's licence. It links to the port's page on freshports.org if it exists. | + | * {{yhl|''<nowiki>{{port|ftp/curl|BSD}}</nowiki>''}} produces {{port|ftp/curl|BSD}} for ports in ports-tree, and optionally it's licence. It links to the port's page on freshports.org, if it exists. |
| − | ''<nowiki>{{man|kldstat|8}}</nowiki>'' produces {{man|kldstat|8}}. ''<nowiki>{{man|kldstat}}</nowiki>'' produces {{man|kldstat}} | + | * {{yhl|''<nowiki>{{man|kldstat|8}}</nowiki>''}} produces {{man|kldstat|8}}. {{yhl|''<nowiki>{{man|kldstat}}</nowiki>''}} produces {{man|kldstat}}. |
| − | For yellow highlighting of types of text not mentioned here, use ''<nowiki>{{yhl|look at this!}}</nowiki>'' for {{yhl|''look at this!''}}. | + | * For yellow highlighting of types of text not mentioned here, use {{yhl|''<nowiki>{{yhl|look at this!}}</nowiki>''}} for {{yhl|''look at this!''}}. |
Latest revision as of 17:12, 1 November 2015
[edit] The KISS principle
FreeBSD administration is a huge and overarching topic. But the goal of this wiki is to make it accessible, and accessibility means taking it in short and sweet bites - so wherever possible, try to keep your articles short; no more than one or two screen-pages. If that seems impossible, consider breaking your article down into sub-articles - for example, if you're writing an article about securing a server in an internet context, don't go into how to set up an IPFW firewall inside that article, instead link to an IPFW how-to when you get to that point.
[edit] Use Section markup tools for complex topics
In some cases - for example, an article on how to set up a Samba server from scratch - it's impossible to keep the overall article length down to a mere screen or two of text. There's just too much to cover, and it really doesn't lend itself well to multiple articles. When you have this type of content to cover, and multiple articles don't make sense, use Section markup! Not only will they automatically make your section titles nice and bold, any article with more than three Sections will also automatically get a hyperlinked table of contents at the head of the article itself. To use Sections, simply type a single line beginning and ending with ==, like this:
==This is an example of a Section line.==
This is how the article you're reading right now is formatted.
[edit] Text highlighting guidelines
When showing an interactive console session, please use a leading space in front of every line (to put the session in a little "box" in the article when it renders) and use the triple-singlequote (''') wikitag to bold user-entered text. For example:
ph34r# this is what a console session should look like on the BSDwiki. this: Command not found. ph34r#
The leading space can also be used for code from console output, and file contents.
#!/bin/sh exec xorg</nowiki> #This text is commented out
Here are templates for adding clarity to text. Templates need <nowiki> tags to properly display special characters.
- For commandline text within paragraphs use {{cmd|kldstat -v}} to produce kldstat -v.
- For code console output or file contents use {{code|:Command not found.}} for :Command not found..
- Displaying files and directories use the same code, but end directory descriptions in "/". {{file|/usr/local/etc/}} produces /usr/local/etc/ for directories. {{file|/etc/rc.conf}} produces /etc/rc.conf for files.
- {{port|ftp/curl|BSD}} produces ftp/curl BSD for ports in ports-tree, and optionally it's licence. It links to the port's page on freshports.org, if it exists.
- {{man|kldstat|8}} produces kldstat(8). {{man|kldstat}} produces kldstat().
- For yellow highlighting of types of text not mentioned here, use {{yhl|look at this!}} for look at this!.
