Return to graphic_chart.mdwn CVS log

Up to [NetBSD Developer Wiki] / wikisrc / wiki

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

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]]
        !            47:     2. : [[!template id=man name="intro" section="1"]], [[!template id=man name="hier" section="7"]]
        !            48:     2. 's packages: [[!template id=pkg category="www" name="apache"]], [[!template id=pkg category="security" name="netpgp"]]
        !            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