[[!toc ]]
# Introduction
The purpose of the following document is to propose a graphic chart regarding the NetBSD htdocs site, including this wiki, and give some examples so they can be reused quickly anywhere else.
***
# On textual conventions
Remember that this is a [[!wikipedia wiki]]; its base syntax, [[!wikipedia Markdown]], is more limited than the one you have when writing down man pages using packages like [[!template id=man name=mdoc section=7]], where data types (variables, pathnames, flags, functions, return values, ...) have each their associated types, or document markup language like [[!wikipedia LaTeX]].
This does not mean that we should not care about conventions, though. For convenience, prefer using the ones that are chosen by the HTML output of the .
## Quoting
When quoting text from an outside source, use double quotes "...", and explicitly indicate its reference.
When you want to quote specific character(s), use single quotes. For example: all sentences end with a '.'.
## Files and directories
Files and directories (and in a wider sense, *paths*) should be *emphasized*, e.g. *fstab* and *rc.conf* are found under */etc/*.
## Commands, options names and flags
When a command, or an executable, are referenced, they should be **strongly emphasized**; same goes for their optional flags and arguments, e.g. **ls** can be used to list the content of a directory, and, together with its **-a** flag, will output entries that start with a dot.
## Functions, or specific part of code
Functions reference should be *simply emphasized*. It is preferable to give the associated file explicitly, to avoid confusions; in that case, use a colon `:' to separate file name from function name. Same goes when you want to pinpoint to specific zone in source files, like lines.
For example, the *src/bin/print.c:printlong* function is responsible for printing the long output from [[!template id=man name=ls section=1]].
# On the usage of links
You can find multiple types of links within the wiki:
1. links to other pages of this [[wiki|sitemap]]:
2. [[index]]
2. [[wiki/graphic_chart]] (this page)
1. explicit URLs:
2. with a label:
2. or without:
1. last but not least, various services regarding NetBSD:
2. problem reports: [[!template id=pr number=1]]
2. : [[!template id=man name=intro section=1]], [[!template id=man name=hier section=7]]
2. 's packages: [[!template id=pkg category=www name=apache]], [[!template id=pkg category=security name=netpgp]]
Always prefer using [[templates]] rather than hard-coding paths for external URLs. This helps both maintainability and readability.
# Specific layouts
The wiki support different commands, [[shortcuts]] and [[templates]] that can help controlling the layout.
## Code
TBC
## Terminal/console-like output
If you want to write series of commands, eventually with their output, you can use the [[programlisting_template|templates/programlisting]].
[[!template id=programlisting text="""
$ uname
NetBSD
$ cat /etc/fstab
# See /usr/share/examples/fstab/ for more examples.
/dev/wd0a / ffs rw,log 1 1
/dev/wd0b none swap sw 0 0
kernfs /kern kernfs rw
ptyfs /dev/pts ptyfs rw
procfs /proc procfs rw
/dev/cd0a /cdrom cd9660 ro,noauto
"""]]
## File content
If you want to display the content of a file, and make a proper distinction with terminal output, use the [[filecontent_template|templates/filecontent]].
[[!template id=filecontent name="/etc/fstab" text="""
# See /usr/share/examples/fstab/ for more examples.
/dev/wd0a / ffs rw,log 1 1
/dev/wd0b none swap sw 0 0
kernfs /kern kernfs rw
ptyfs /dev/pts ptyfs rw
procfs /proc procfs rw
/dev/cd0a /cdrom cd9660 ro,noauto
"""]]
## Warnings and notes
### Warnings
TBC Provide a "warning" template, with a nice-looking icon and appropriate framing (light red fieldset, for example). Investigate Tango icons. Needs some CSS tweaking.
### Notes
TBC Provide a "note" template, similar to the "warning" one (yellow-greyish maybe).
***
# References
Last, some references:
* TBD
* TBD