Wiki policies and guidelines

Contents

This page contains a few basic information you should know before getting started in editing and contributing to VLSI Wiki pages.

If you already have a 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.

Wiki pages are created and modified using the 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 here. For more information and details look at the DokuWiki official manual.

The VLSI Wiki has been configured to work with both public and private pages, as described below.

New public pages can be created as internal links under the vlsi namespace using double brackets [[ and ]] :

[[vlsi:pagename|New page]]

New page

The New page does not exist by default. To create it, open the link and just start writing some text and save. 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]]__

New page

Public pages can be also created following a hierarchical tree structure .

VLSI private pages can be read by registered users only. They are created as internal links similar to public pages, but page names are nested under the vlsi:private namespace :

[[vlsi:private:pagename|New private page]]

New private page

Always use private pages for documenting and sharing confidential and restricted information !

Private pages can be also created following a hierarchical tree structure .

Wiki pages can be better organized into a hierarchical tree structure using 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]]

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 !

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.

DokuWiki allows using up to five different 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.

You can create blocks of folded text with the general syntax

 ++++ Click here |
 to show the folded text
 ++++

Click here


Only when you click on the folder head the block expands and shows the full text content.

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]]

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 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

Documentation pages should always contain a short introduction section to explain page contents.


Furtheromore, quick links below page titles in form of

[ First link ] [ Second link ] [ ... ]


can be created with the syntax

[ __[[vlsi:path:to:pagename1|First link]]__ ]
[ __[[vlsi:path:to:pagename2|Second link]]__ ]
[ __[[vlsi:path:to:pagename3|...]]__ ]

You can insert sequences of UNIX commands or pieces of code between <code> and </code> TAGS :

 <code>
    mkdir ~/scratch   
 </code>


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

Dokuwiki supports syntax highlighting for many different programming languages. Just specify the language name in the first <code> TAG. In particular, C/C++, VHDL, Verilog, Python and TCL are supported, just use c, cpp, vhdl, verilog, python and tcl.

 <code vhdl>
 -- 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;
 </code>


-- 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;

Images and other files can be uploaded and included into Wiki pages through a simple media manager. To open the media manager, left click on the proper button in the editor toolbar as shown below.



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}}

link name


Resources can be uploaded and under 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.

DokuWiki provides plugins to extend basic formatting syntax options.
The complete list of installed plugins which come with the current INFN DokuWiki installation can be found here.



Last update: Luca Pacher - Sep 10, 2013