Differenze
Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.
Entrambe le parti precedenti la revisione Revisione precedente Prossima revisione | Revisione precedente | ||
vlsi:policies [08/09/2013 20:21] pacher |
— (versione attuale) | ||
---|---|---|---|
Linea 1: | Linea 1: | ||
- | ====== Wiki policies and guidelines ====== | ||
- | |||
- | [ __[[vlsi:home|Home]]__ ] | ||
- | [ __[[vlsi:workbook|Design Workbook]]__ ] | ||
- | [ __[[wiki:syntax|Syntax]]__ ] | ||
- | |||
- | |||
- | |||
- | == Contents == | ||
- | |||
- | * [[vlsi:policies#introduction|Introduction]] | ||
- | * [[vlsi:policies#login|Login]] | ||
- | * [[vlsi:policies#editing_pages|Editing pages]] | ||
- | * [[vlsi:policies#public_pages|Public pages]] | ||
- | * [[vlsi:policies#private_pages|Private pages]] | ||
- | * [[vlsi:policies#confidentiality_of_tools_and_technology_information|Confidentiality of tools and technology information]] | ||
- | * [[vlsi:policies#wiki_policies|Wiki policies]] | ||
- | * [[vlsi:policies#heading_conventions|Heading conventions]] | ||
- | * [[vlsi:policies#links_to_sections|Links to sections]] | ||
- | * [[vlsi:policies#tables_of_contents_and_quick_links|Tables of contents and quick links]] | ||
- | * [[vlsi:policies#unix_commands_and_paths|UNIX commands and paths]] | ||
- | * [[vlsi:policies#code_snippets|Code snippets]] | ||
- | * [[vlsi:policies#attaching_files_and_images|Attaching files and images]] | ||
- | |||
- | **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: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 ===== | ||
- | |||
- | Once authenticated, make your changes and save before exiting. | ||
- | 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 <nowiki>HTML</nowiki> knowledge is required). | ||
- | 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 either **public** or **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** <nowiki>[[</nowiki> and <nowiki>]]</nowiki> : | ||
- | |||
- | <code> | ||
- | [[vlsi:pagename|New page]] | ||
- | </code> | ||
- | |||
- | [[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. Page names are not case-sensitive, thus | ||
- | ''vlsi:pagename'' and ''vlsi:Pagename'' represent the same Wiki page. | ||
- | |||
- | Just for a better visualization it is recommended to underline page links, | ||
- | |||
- | <code> | ||
- | __[[vlsi:pagename|New page]]__ | ||
- | </code> | ||
- | |||
- | |||
- | __[[vlsi:pagename|New page]]__ | ||
- | |||
- | ===== 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 : | ||
- | |||
- | <code> | ||
- | [[vlsi:private:pagename|New private page]] | ||
- | </code> | ||
- | |||
- | [[vlsi:private:pagename|New private page]] | ||
- | |||
- | |||
- | **//Always use private pages for documenting and sharing confidential and restricted information !//** | ||
- | |||
- | |||
- | ===== Wiki tree structure ===== | ||
- | |||
- | |||
- | <code> | ||
- | [[vlsi:workbook:computing:accounts]] | ||
- | </code> | ||
- | |||
- | ''vlsi/workbook/computing/accounts'' | ||
- | |||
- | <code> | ||
- | [[vlsi:private:technologies:xxxx]] | ||
- | </code> | ||
- | |||
- | [[https://www.dokuwiki.org/namespaces]] | ||
- | |||
- | ===== 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. | ||
- | |||
- | <box 100% round #ddf9f9 #ddf9f9 #ddf9f9 #ddf9f9> | ||
- | //Never put confidential and restricted information on Wiki public pages !// | ||
- | </box> | ||
- | |||
- | ===== 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 <nowiki>PDF</nowiki> 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 | ||
- | <nowiki>\\</nowiki> instead. In general, avoid unnecessary nesting with further sub-sections. | ||
- | |||
- | ===== 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]] | ||
- | |||
- | |||
- | \\ | ||
- | Be aware that blanks in the section name must be substituted by underscores in the link path, | ||
- | |||
- | [[vlsi:policies#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 | ||
- | |||
- | ''<nowiki>~~NOTOC~~</nowiki>'' | ||
- | |||
- | 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:pagename#introduction|Introduction]] | ||
- | * [[vlsi:pagename#first_section|First section]] | ||
- | * [[vlsi:pagename#second_section|Second section]] | ||
- | * ... | ||
- | |||
- | |||
- | == Contents == | ||
- | * [[vlsi:pagename#introduction|Introduction]] | ||
- | * [[vlsi:pagename#first_paragraph|First paragraph]] | ||
- | * [[vlsi: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 | ||
- | |||
- | [ __[[First link]]__ ] | ||
- | [ __[[Second link]]__ ] | ||
- | [ __[[...]]__ ] | ||
- | |||
- | |||
- | \\ | ||
- | can be created with the syntax | ||
- | |||
- | [ __[[vlsi:pagename1|First link]]__ ] | ||
- | [ __[[vlsi:pagename2|Second link]]__ ] | ||
- | [ __[[vlsi:pagename3|...]]__ ] | ||
- | |||
- | ===== UNIX commands and paths ===== | ||
- | |||
- | You can insert sequences of **UNIX commands** or **pieces of code** between | ||
- | <nowiki><code></nowiki> and <nowiki></code></nowiki> TAGS : | ||
- | |||
- | |||
- | <code> | ||
- | mkdir ~/scratch | ||
- | </code> | ||
- | |||
- | |||
- | \\ | ||
- | <code> | ||
- | mkdir ~/scratch | ||
- | </code> | ||
- | |||
- | |||
- | \\ | ||
- | Put **file names** and **single UNIX commands** between double single-quotes (apologize for the pun!) | ||
- | <nowiki>' '</nowiki> and <nowiki>' '</nowiki> : | ||
- | |||
- | |||
- | 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 <nowiki><code></nowiki> TAG. | ||
- | In particular, C/C++, VHDL, Verilog, Python and TCL are supported, just use //c, cpp, vhdl, verilog, | ||
- | python// and //tcl//. | ||
- | |||
- | |||
- | <code vhdl> | ||
- | -- first 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> | ||
- | |||
- | \\ | ||
- | <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> | ||
- | |||
- | ===== 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** <nowiki>{{</nowiki> and <nowiki>}}</nowiki>, | ||
- | |||
- | {{vlsi:filename|link name}} | ||
- | |||
- | |||
- | {{vlsi: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. | ||
- | |||
- | ====== ====== | ||
- | \\ | ||
- | ---- | ||
- | Last update: [[pacher@NOSPAMto.infn.it|Luca Pacher]] - Apr 7, 2012 | ||
- | |||
- | ~~NOTOC~~ |