Return to graphic_chart.mdwn CVS log

Up to [NetBSD Developer Wiki] / wikisrc / wiki

Annotation of wikisrc/wiki/graphic_chart.mdwn, revision 1.3

1.1       wiki        1: [[!toc ]]
                      2: 
                      3: # Introduction
                      4: 
                      5: 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.
                      6: 
                      7: ***
                      8: 
                      9: # On textual conventions
                     10: 
                     11: 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]]. 
                     12: 
                     13: 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 .
                     14: 
                     15: ## Quoting
                     16: 
                     17: When quoting text from an outside source, use double quotes "...", and explicitly indicate its reference.
                     18: 
                     19: When you want to quote specific character(s), use single quotes. For example: all sentences end with a '.'.
                     20: 
                     21: ## Files and directories
                     22: 
                     23: Files and directories (and in a wider sense, *paths*) should be *emphasized*, e.g. *fstab* and *rc.conf* are found under */etc/*.
                     24: 
                     25: ## Commands, options names and flags
                     26: 
                     27: 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.
                     28: 
                     29: ## Functions, or specific part of code
                     30: 
                     31: 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.
                     32: 
                     33: For example, the *src/bin/print.c:printlong* function is responsible for printing the long output from [[!template id=man name=ls section=1]].
                     34: 
                     35: # On the usage of links
                     36: 
                     37: You can find multiple types of links within the wiki:
                     38: 
                     39: 1. links to other pages of this [[wiki|sitemap]]:
                     40:     2. [[index]]
                     41:     2. [[wiki/graphic_chart]] (this page)
                     42: 1. explicit URLs:
                     43:     2. with a label: 
                     44:     2. or without: 
                     45: 1. last but not least, various services regarding NetBSD:
                     46:     2. problem reports: [[!template id=pr number=1]]
1.3     ! leot       47:     2. man pages: [[!template id=man name=intro section=1]], [[!template id=man name=hier section=7]]
        !            48:     2. pkgsrc packages: [[!template id=pkg category=www name=apache]], [[!template id=pkg category=security name=netpgp]]
1.1       wiki       49: 
                     50: Always prefer using [[templates]] rather than hard-coding paths for external URLs. This helps both maintainability and readability.
                     51: 
                     52: # Specific layouts
                     53: 
                     54: The wiki support different commands, [[shortcuts]] and [[templates]] that can help controlling the layout.
                     55: 
                     56: ## Code
                     57: 
                     58: TBC 
                     59: 
                     60: ## Terminal/console-like output
                     61: 
                     62: If you want to write series of commands, eventually with their output, you can use the [[programlisting_template|templates/programlisting]].
                     63: 
                     64: [[!template id=programlisting text="""
                     65: $ uname
                     66: NetBSD
                     67: $ cat /etc/fstab
                     68: # See /usr/share/examples/fstab/ for more examples.
                     69: /dev/wd0a      /         ffs      rw,log       1 1
                     70: /dev/wd0b      none      swap     sw           0 0
                     71: kernfs         /kern     kernfs   rw
                     72: ptyfs          /dev/pts  ptyfs    rw
                     73: procfs         /proc     procfs   rw
                     74: /dev/cd0a      /cdrom    cd9660   ro,noauto
                     75: """]]
                     76: 
                     77: ## File content
                     78: 
                     79: If you want to display the content of a file, and make a proper distinction with terminal output, use the [[filecontent_template|templates/filecontent]].
                     80: 
                     81: [[!template id=filecontent name="/etc/fstab" text="""
                     82: # See /usr/share/examples/fstab/ for more examples.
                     83: /dev/wd0a      /         ffs      rw,log       1 1
                     84: /dev/wd0b      none      swap     sw           0 0
                     85: kernfs         /kern     kernfs   rw
                     86: ptyfs          /dev/pts  ptyfs    rw
                     87: procfs         /proc     procfs   rw
                     88: /dev/cd0a      /cdrom    cd9660   ro,noauto
                     89: """]]
                     90: 
                     91: ## Warnings and notes
                     92: 
                     93: ### Warnings
                     94: 
                     95: 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.
                     96: 
                     97: ### Notes
                     98: 
                     99: TBC Provide a "note" template, similar to the "warning" one (yellow-greyish maybe).
                    100: 
                    101: ***
                    102: 
                    103: # References
                    104: 
                    105: Last, some references:
                    106: 
                    107: * TBD
                    108: * TBD