File:  [NetBSD Developer Wiki] / wikisrc / wiki / graphic_chart.mdwn
Revision 1.3: download - view: text, annotated - select for diffs
Sat Oct 24 16:41:08 2015 UTC (2 years, 5 months ago) by leot
Branches: MAIN
CVS tags: HEAD
Add some missing words while here.

[[!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. man pages: [[!template id=man name=intro section=1]], [[!template id=man name=hier section=7]]
    2. pkgsrc 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


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


CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb