====== Wiki policies and guidelines ====== [ __[[vlsi:home|Home]]__ ] [ __[[vlsi:wiki:users|Registered users]]__ ] [ __[[wiki:syntax|Syntax]]__ ] [ __[[http://seeingstone.net/dokuwiki/doku.php/wiki/syntax|Syntax (more exhaustive)]]__ ] == Contents == * [[vlsi:wiki:policies#introduction|Introduction]] * [[vlsi:wiki:policies#login|Login]] * [[vlsi:wiki:policies#editing_pages|Editing pages]] * [[vlsi:wiki:policies#public_pages|Public pages]] * [[vlsi:wiki:policies#private_pages|Private pages]] * [[vlsi:wiki:policies#hierarchical_tree_structure|Hierarchical tree structure]] * [[vlsi:wiki:policies#confidentiality_of_tools_and_technology_information|Confidentiality of tools and technology information]] * [[vlsi:wiki:policies#wiki_policies|Wiki policies]] * [[vlsi:wiki:policies#heading_conventions|Heading conventions]] * [[vlsi:wiki:policies#blocks_of_folded_text|Blocks of folded text]] * [[vlsi:wiki:policies#links_to_sections|Links to sections]] * [[vlsi:wiki:policies#tables_of_contents_and_quick_links|Tables of contents and quick links]] * [[vlsi:wiki:policies#unix_commands_and_paths|UNIX commands and paths]] * [[vlsi:wiki:policies#code_snippets|Code snippets]] * [[vlsi:wiki:policies#attaching_files_and_images|Attaching files and images]] * [[vlsi:wiki:policies#available_plugins|Available plugins]] **Keywords:** ===== Introduction ===== This page contains a few basic information you should know before getting started in editing and contributing to VLSI Wiki pages. ===== Login ===== If you already have a __[[vlsi:workbook:computing:accounts#wiki_account|VLSI Wiki account]]__, to login left click on ''Entra'' at the top-right of a Wiki page and authenticate yourself with your INFN UNIX account credentials. Your Web browser could need extra cookies to be enabled. ===== Editing pages ===== Wiki pages are created and modified using the [[https://www.dokuwiki.org/dokuwiki|DokuWiki]] interface. It uses a very simple coding system that takes no time to learn (no HTML knowledge is required). Once authenticated, simply make your changes and save before exiting. The basic formatting syntax can be found __[[wiki:syntax|here]]__. For more information and details look at the [[https://www.dokuwiki.org/manual|DokuWiki official manual]]. The VLSI Wiki has been configured to work with both **public** and **private** pages, as described below. ===== Public pages ===== New **public pages** can be created as __[[wiki:syntax#links|internal links]]__ under the ''vlsi'' namespace using **double brackets** [[ and ]] : [[vlsi:pagename|New page]] [[vlsi:pagename|New page]] The [[vlsi:pagename|New page]] does not exist by default. To create it, open the link and just start writing some text and save. [[https://www.dokuwiki.org/pagename|Page names]] are automatically converted by DokuWiki to lowercase, thus ''vlsi:pagename'' and ''vlsi:Pagename'' will represent the same page. Just for a better visualization it is recommended to underline page links, __[[vlsi:pagename|New page]]__ __[[vlsi:pagename|New page]]__ Public pages can be also created following a __[[vlsi:wiki:policies#hierarchical_tree_structure|hierarchical tree structure]]__ . ===== Private pages ===== VLSI **private pages** can be read by registered users only. They are created as __[[wiki:syntax#links|internal links]]__ similar to public pages, but page names are nested under the ''vlsi:private'' namespace : [[vlsi:private:pagename|New private page]] [[vlsi:private:pagename|New private page]] **//Always use private pages for documenting and sharing confidential and restricted information !//** Private pages can be also created following a __[[vlsi:wiki:policies#hierarchical_tree_structure|hierarchical tree structure]]__ . ===== Hierarchical tree structure ===== Wiki pages can be better organized into a hierarchical tree structure using [[https://www.dokuwiki.org/namespaces|namespaces]]. Namespaces are similar to UNIX directories or Windows folders, whereas pagenames are similar to files. To create namespaces, simply create pages with separative **colons** in the full page path in form of [[vlsi:path:to:pagename|Page name]] The token after the last colon will represent the name of the page itself. All other previous tokens are namespaces and can be considered as directories and sub-directories. \\ Private pages can be nested under namespaces as well: [[vlsi:private:path:to:pagename|Page name]] \\ Examples: [[vlsi:workbook:computing:accounts]] [[vlsi:private:technologies:ibm]] ===== Confidentiality of tools and technology information ===== All the commercial EDA softwares licensed by INFN for the VLSI lab and the associated documentation contain **trade secrets** and **proprietary information** protected by **copyright laws**. Thus any or parts of the documentation accompanying the design platforms available on VLSI machines cannot be uploaded on public pages or published on the Web! \\ Furthermore, all **technology-related** information and documentation are very confidential and restricted. No information about technology processes can be disseminated to a third party or published on the Web. Each VLSI user is bound to specific **non-disclosure agreement (NDA)** contracts with manufacturers (foundries) or third party IC fabrication services depending on the particular technology involved in his research activity. //Never put confidential and restricted information on Wiki public pages !// ===== Wiki policies ===== Contributing to VLSI Wiki pages is not mandatory, aware that it cannot become a time consuming stuff for a professional researcher. People are welcome to suggest changes, updates and improvements. Always feel free to fix typos and grammatical errors. If you find missing/wrong information or something could be presented better, feel free to revise the topic. In general, keep explanations brief using a step-by-step format wherever possible and provide links to external information such as //papers//, //books//, //Web pages// etc. Proprietary and confidential information cannot be shared on Wiki public pages. So, what kind of information can be included? Things you write yourself should be ok unless VLSI coordinators (//[[mazza@NOSPAMto.infn.it]]//, //[[rivetti@NOSPAMto.infn.it]]//, remove NOSPAM in the address) have something against them. You can upload generic screenshots and describe step-by-step **technology-independent tutorials**. You can mention UNIX paths related to tool executables, setup files and documentation files, as well as environment variables, command line expressions, simulation directives etc. as you can find in other Web tutorials or in any EDA forum. Available technologies can be mentioned but //**no technology-related information and documentation can be put on public pages!**// Thus, you cannot mention or describe libraries, devices, model files, layout mask layers etc. of a particular fabrication technology. Furthermore **never upload PDF documentation**, neither about design tools nor technologies. Just provide UNIX paths to files instead. ===== Heading conventions ===== DokuWiki allows using up to five different __[[wiki:syntax#sectioning|levels of headlines]]__ to structure a page content. All VLSI Wiki pages must have a top **page title** using a level 1 headline : ====== Page title ====== \\ Then pages can be divided into **sections** using level 2 headlines, ===== Section ===== \\ New **paragraphs** inside sections are generated by leaving an empty line in the text. If you want to force a new line without a paragraph use two consecutive backslashes \\ instead. In general, avoid unnecessary nesting with further sub-sections. ===== Blocks of folded text ===== You can create blocks of **folded text** with the general syntax ++++ Click here | to show the folded text ++++ ++++ Click here | to show the folded text ++++ \\ Only when you click on the folder head the block expands and shows the full text content. ===== Links to sections ===== If you want to make a link to a page section use the syntax [[vlsi:pagename#section|link name]] or [[vlsi:private:pagename#section|link name]] \\ The same syntax applies to page names nested under namespaces, [[vlsi:path:to:pagename#section|link name]] [[vlsi:private:path:to:pagename#section|link name]] \\ Be aware that blanks in the section name must be substituted by underscores in the link path, [[vlsi:pagename#link_to_section|link name]] [[vlsi:path:to:pagename#link_to_section|link name]] ===== Tables of contents and quick links ===== If you use more than two headlines in a page a **table of contents** is automatically generated by DokuWiki in form of a right side pane. It is recommended to create custom indices and quick links by hand indeed. Put a ''~~NOTOC~~'' string at the end of a page to disable the automatically generated table of contents and create at the beginning of the page __[[wiki:syntax#lists|an ordered or unordered list]]__ of links to various page sections with the syntax == Contents == * [[vlsi:path:to:pagename#introduction|Introduction]] * [[vlsi:path:to:pagename#first_section|First section]] * [[vlsi:path:to:pagename#second_section|Second section]] * ... == Contents == * [[vlsi:path:to:pagename#introduction|Introduction]] * [[vlsi:path:to:pagename#first_paragraph|First paragraph]] * [[vlsi:path:to:pagename#second_paragraph|Second paragraph]] * ... ===== ===== Documentation pages should always contain a short **introduction** section to explain page contents. \\ Furtheromore, **quick links** below page titles in form of [ __[[vlsi:path:to:pagename1|First link]]__ ] [ __[[vlsi:path:to:pagename2|Second link]]__ ] [ __[[...]]__ ] \\ can be created with the syntax [ __[[vlsi:path:to:pagename1|First link]]__ ] [ __[[vlsi:path:to:pagename2|Second link]]__ ] [ __[[vlsi:path:to:pagename3|...]]__ ] ===== UNIX commands and paths ===== You can insert sequences of **UNIX commands** or **pieces of code** between and TAGS : mkdir ~/scratch \\ mkdir ~/scratch \\ Put **file names** and **single UNIX commands** between double single-quotes (apologize for the pun!) ' ' and ' ' : You can copy default ''.cdsinit'' and ''.cdsenv'' initialization files to your local area You can copy default ''.cdsinit'' and ''.cdsenv'' initialization files to your local area \\ The same syntax applies to **UNIX paths** : ''/path/to/something'' \\ ''/path/to/something'' ===== Code snippets ===== Dokuwiki supports __[[wiki:syntax#syntax_highlighting|syntax highlighting]]__ for many different programming languages. Just specify the language name in the first TAG. In particular, C/C++, VHDL, Verilog, Python and TCL are supported, just use //c, cpp, vhdl, verilog, python// and //tcl//. -- example of VHDL code entity AND2 is -- entity declaration port(A,B : in bit; Y : out bit); end AND2; architecture behavior of AND2 is -- architecture declaration begin Y <= A and B; end behavior; \\ -- example of VHDL code entity AND2 is -- entity declaration port(A,B : in bit; Y : out bit); end AND2; architecture behavior of AND2 is -- architecture declaration begin Y <= A and B; end behavior; ===== Attaching files and images ===== Images and other files can be uploaded and included into Wiki pages through a simple [[https://www.dokuwiki.org/mime|media manager]]. To open the media manager, left click on the proper button in the editor toolbar as shown below. {{:vlsi:wiki_media_manager.png?650}} \\ \\ The media manager window appears, then left click on the ''Choose'' button, browse your file system and select the file you want to attach. Once the upload has been completed you can insert the file in your pages in form of a link by using **double curly brackets** {{ and }}, {{vlsi:filename|link name}} {{vlsi:filename|link name}} \\ Resources can be uploaded and under [[https://www.dokuwiki.org/namespaces|namespaces]] and saved into a hierarchical structure: {{vlsi:path:to:filename|link name}} \\ DokuWiki allows you to upload //jpg, jpeg, gif, png// images, //mp3, ogg, wav// media files, //tgz, tar, gz, bz2, zip, rar, 7z// compressed archives and //pdf, ps, doc, ppt, xls// documents. For security issues **you cannot upload plain-text files** by default, because spammers are known to use them for spamming. Hence //txt, html, htm, xml, csv// cannot be directly uploaded through the media manager. If you want to include text files, shell scripts, configuration files etc. please **squeeze them with a compression utility** (''gzip'' and ''tar'' work fine) before uploading. ===== Available plugins ===== DokuWiki provides [[https://www.dokuwiki.org/plugins|plugins]] to extend basic formatting syntax options. \\ The complete list of **installed plugins** which come with the current INFN DokuWiki installation can be found __[[wiki:syntax#syntax_plugins|here]]__. ====== ====== \\ ---- Last update: [[pacher@NOSPAMto.infn.it|Luca Pacher]] - Sep 10, 2013 ~~NOTOC~~