Difference between revisions of "Help:Style (Italiano)"

From ArchWiki
Jump to: navigation, search
("Known issues" sections: translate)
("See also" sections: translate)
Line 197: Line 197:
 
*Se esiste un bug report per il problema, è fortemente preferibile includere un link ad esso; nel caso non esista, bisognerebbe provvedere a riportarlo, in maniera da aumentare le probabilità che il bug venga corretto.
 
*Se esiste un bug report per il problema, è fortemente preferibile includere un link ad esso; nel caso non esista, bisognerebbe provvedere a riportarlo, in maniera da aumentare le probabilità che il bug venga corretto.
  
==="See also" sections===
+
===Sezioni "Altre risorse"===
*A list of links to references and sources of additional information.
+
*Una lista di link a pagine di riferimento e fonti per informazioni addizionali.
*This should be a list where each entry is started with {{Ic|*}}.
+
*Dovrebbe essere una lista in cui ogni voce comincia con {{Ic|*}}.
*The standard title is ''See also'', other similar titles like ''External links'', ''More resources'' etc. should be avoided.
+
*Il titolo standard è ''Altre rirorse'', è meglio evitare altri titoli simili come ''Link esterni'', ''Vedere anche'' ecc.
  
 
===Non-pertinent content===
 
===Non-pertinent content===

Revision as of 14:21, 22 November 2011

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.


Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어


External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

Tango-preferences-desktop-locale.pngThis article or section needs to be translated.Tango-preferences-desktop-locale.png

Notes: please use the first argument of the template to provide more detailed indications. (Discuss in Help talk:Style (Italiano)#)
Template:Article summary start

Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary end

Uno dei migliori modi per far sì che un'opera di documentazione sia chiara e facilmente comprensibile dai suoi utenti è l'adesione del suo contenuto ad una serie di regole di stile convenzionali. ArchWiki non fa eccezione a quest'idea: non solo il testo di un articolo dev'essere coerente, il più esaustivo possibile e scritto in linguaggio formale, ma deve anche apparire ordinato ed organizzato, visivamente coerente con gli altri articoli. Tutti i collaboratori di ArchWiki sono incoraggiati a seguire queste linee guida nel modificare gli articoli.

Articoli

Titolo

  • Se l'argomento dell'articolo è comunemente conosciuto sia con il nome completo che con un acronimo, si preferisca usare il nome completo nel titolo dell'articolo.
    Evitare di includere nel titolo sia il nome completo che l'acronimo (ad esempio tra parentesi): se si pensa che entrambi siano usati comunemente, si crei un redirect per l'acronimo che reindirizzi alla pagina titolata con il nome completo.
  • Si veda anche Article Naming Guidelines.

Struttura

  • I vari elementi di un articolo devono essere inclusi nel seguente ordine:
  1. Categorie
  2. Template i18n
  3. Interlink (opzionali)
  4. Template di stato dell'articolo (opzionali)
  5. Sommario (opzionale)
  6. Prefazione o introduzione
  7. Tabella dei contenuti (automatica)
  8. Sezioni specifiche dell'articolo

Categorie

  • Ogni articolo dev'essere categorizzato in almeno una categoria tra quelle esistenti.
  • Un articolo può appartenere a più di una categoria, ammesso che nessuna di esse sia contenuta, direttamente o indirettamente, in una delle altre categorie presenti.
  • Le categorie devono essere specificate all'inizio del codice di ogni articolo.
    Nota: Questo metodo differisce da altri progetti MediaWiki come Wikipedia, i quali includono le categorie in fondo agli articoli.
  • Non devono esserci righe vuote tra le categorie e la barra i18n, dato che introdurrebbero dello spazio bianco all'inizio dell'articolo.
  • Vedere anche Recategorizing Pages.

Template i18n

Interlink

  • Se l'articolo ha corrispondenza con un altro di una delle wiki esterne di Arch Linux in altre lingue, si possono includere i relativi interlink subito sotto il template i18n.
    Notare che effettivamente appariranno nell'apposita colonna alla sinistra della pagina.
  • Quando si aggiungono o modificano interlink, bisogna fare attenzione a ripetere tale azione per tutte le traduzioni dell'articolo accessibili nella barra i18n.
  • Vedere anche Aiuto:Interlink.

Template di stato dell'articolo

Sommario

Prefazione o introduzione

  • Descrive l'argomento dell'articolo.
    Piuttosto che parafrasare o scrivere la propria (magari troppo soggettiva) descrizione di un particolare software, si può usare la descrizione dell'autore originale, che di solito può essere trovata sulla pagina home o about del sito ufficiale del progetto, se esistente. Un esempio è MediaTomb.
  • Inclusa subito sotto il Sommario.
  • Non creare esplicitamente una sezione ==Introduzione== o ==Prefazione==: lasciare invece che appaia sopra il primo titolo di sezione. Quando c'è un numero sufficiente di sezioni nell'articolo, tra la prefazione e la prima sezione viene mostrata automaticamente la tabella dei contenuti.
  • Vedere anche Writing Article Introductions.

Titoli di sezione

  • I livelli dei titoli di sezione devono cominciare dal secondo (==), infatti il primo livello è riservato per i titoli degli articoli.
  • Evitare di saltare livelli quando si creano sottosezioni, perciò una sottosezione di un livello 2 avrà un titolo di livello 3 e così via.
  • I titoli di sezione usano le maiuscole come le normali frasi: Una nuova sezione e non Una Nuova Sezione.
  • Evitare di usare link nei titoli, dato che creano una discontinuità di stile ed inoltre non sono facilmente individuabili. In genere il testo del link si può trovare anche nel contenuto della sezione, altrimenti è possibile usare semplici frasi del tipo Si veda anche My New Page.
    Per lo stesso motivo, si eviti anche di usare qualunque altro tipo di markup o markdown, inclusi i template di formattazione del codice.
  • Vedere anche Effective Use of Headers.

Linee vuote

  • Evitare di inserire più linee vuote consecutive per aumentare lo spazio bianco tra paragrafi o sezioni.
  • Si veda Help:Editing#Line breaks per maggiori informazioni.

Template di formattazione del codice

  • Usare {{ic|codice}} per rappresentare, nelle righe del testo, corte linee di codice, nomi di file, nomi di comandi, nomi di variabili e simili, ad esempio:
    pippo codice pluto.
  • Usare {{bc|codice}} per rappresentare in un blocco separato singole o multiple linee di codice (input o output della linea di comando e contenuto dei file), ad esempio:
# iwconfig
lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0
#!/bin/sh

# Demo
echo "Hello World"
  • Per corte linee di codice è anche ammesso iniziarle con uno spazio invece di usare {{bc|code}} (vedere Help:Editing (Italiano)), ma si noti che il blocco di codice risultante non avrà la barra di scorrimento orizzontale nel caso in cui il codice vada oltre il limite dello schermo: tenere a mente che alcuni lettori potrebbero usare schermi più stretti del proprio, o semplicemente visualizzare il browser in una finestra non massimizzata, perciò potrebbero vedere il codice raggiungere il bordo dello schermo anche se all'autore dell'articolo non accade.
  • Usare {{hc|input|output}} quando si ha bisogno di rappresentare sia l'input che l'output della linea di comando, ad esempio:
# iwconfig
lo no wireless extensions.
eth0 no wireless extensions.
wlan0    unassociated  ESSID:""
         Mode:Managed  Channel=0  Access Point: Not-Associated
         Bit Rate:0 kb/s   Tx-Power=20 dBm   Sensitivity=8/0
         Retry limit:7   RTS thr:off   Fragment thr:off
         Power Management:off
         Link Quality:0  Signal level:0  Noise level:0
         Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
         Tx excessive retries:0  Invalid misc:0   Missed beacon:0
  • Quando si ha bisogno di rappresentare il contenuto di un file e si teme che possa essere difficile per i lettori capire a quale file si riferisca tale codice, è anche possibile usare {{hc|nomefile|contenuto}} per mostrare il nome del file nell'intestazione, ad esempio:
~/hello_world.sh
#!/bin/sh

# Demo
echo "Hello World"

Testo da linea di comando

  • Usare $ come prompt per comandi da utente normale; usare # come prompt per comandi da root.
    Nota: Dato che # è usato anche per indicare i commenti nei file di testo, bisognerebbe sempre cercare di evitare equivoci, magari scrivendo esplicitamente di eseguire il comando o editare un file di testo.
  • La frase introduttiva per un comando dovrebbe in genere terminare con i :.
  • Preferire l'uso di # command invece di scrivere $ sudo command a meno che non sia strettamente necessario.
  • Non presupporre che l'utente usi sudo o un'altra applicazione per ottenere i permessi di root (ad esempio gksu, kdesu).
  • # sudo command è sempre un errore.
  • Non aggiungere commenti nella stessa cornice di un comando (ad esempio # pacman -S foo #Installa il pacchetto foo)
  • Evitare di scrivere linee di codice eccessivamente lunghe: usare dei metodi per spezzare le linee quando possibile.

Richieste di modifica di file

  • Non presupporre l'uso di specifici editor di testo (nano, vim, emacs, ...) nel richiedere modifiche a file di testo, a parte quando necessario.
  • Non usare comandi impliciti per richiedere modifiche a file di testo, a meno che sia strettamente necessario. Ad esempio al posto di $ echo -e "clear\nreset" >> ~/.bash_logout sarebbe meglio scrivere:
Aggiungere le seguenti linee a ~/.bash_logout:
clear
reset

Tasti della tastiera

Istruzioni per la gestione dei pacchetti

Pacchetti ufficiali

  • La maniera corretta per richiedere l'installazione di un pacchetto ufficiale prevede l'uso di una frase simile alla seguente:
    Installare package, disponibile nei Repository Ufficiali.
    il cui testo sorgente è [[pacman (Italiano)|Installare]] {{Pkg|package}}, disponibile nei [[Official Repositories (Italiano)|Repository Ufficiali]].
    Le istruzioni per l'installazione di una lista di pacchetti potrebbero apparire come:
    Installare package1, package2 e package3, disponibili nei Repository Ufficiali.
    Ulteriori esempi di formulazioni potrebbero essere:
    MyApplication può essere installato con il pacchetto my-appplication, disponibile nei Repository Ufficiali.
    È possibile installare MyApplication con il pacchetto my-appplication, disponibile nei Repository Ufficiali.
    È ovviamente consentito adattare la formulazione alle specifiche necessità di ciascun articolo.
  • Se il pacchetto è ospitato in [core], [extra] o [community], fare riferimento al nome del repository è da evitare, dato che non è infrequente che un pacchetto sia spostato in un repository differente, e questo renderebbe più difficile la manutenzione dell'articolo. Se però il pacchetto è ospitato in un repository ufficiale che non è abilitato di default (ad esempio [multilib]), è preferibile menzionarlo.
  • Fare un esempio del comando di pacman necessario per eseguire l'installazione è un metodo deprecato, sia per semplicità (ogni utente di Arch dovrebbe conoscere l'articolo su pacman a memoria) sia per evitare errori come pacman -Sy package o eventuali discussioni senza fine come la scelta tra pacman -S package e pacman -Syu package.
    A maggior ragione non si deve suggerire l'uso di frontend o wrapper per pacman per installare pacchetti ufficiali.

Pacchetti dell'AUR

  • La maniera corretta per richiedere l'installazione di un pacchetto dell'AUR prevede l'uso di una frase simile alla seguente:
    Installare packageAUR, disponibile nell'Arch User Repository.
    il cui testo sorgente è Installare {{AUR|package}}, disponibile nell'[[Arch User Repository (Italiano)|Arch User Repository]].
    È ovviamente consentito adattare la formulazione alle specifiche necessità di ciascun articolo, sebbene sia sempre necessario specificare che il pacchetto non è ufficiale.
  • Non fare esempi di come installare pacchetti dell'AUR, né con il metodo ufficiale né menzionando l'uso di un AUR helper: ogni utente che installa pacchetti non ufficiali deve aver letto l'articolo Arch User Repository (Italiano) ed essere cosciente di tutte le possibili conseguenze sul proprio sistema.

Operazioni con i moduli del kernel

  • Fornire esempi su come aggiungere moduli all'array MODULES in /etc/rc.conf è una pratica deprecata: la formulazione standard prevede una semplice lista dei moduli da aggiungere, eventualmente facendo notare dipendenze o conflitti con altri moduli, ed un link a Kernel modules (Italiano).
  • Fornire esempi su come caricare, rimuovere, mettere in blacklist o eseguire una qualunque altra operazione di base con i moduli è una pratica deprecata: la formulazione standard prevede una descrizione delle azioni che devono essere eseguite e un link a Kernel modules (Italiano).

Operazioni con i demoni

  • Fornire esempi su come aggiungere demoni all'array DAEMONS in /etc/rc.conf è una pratica deprecata: la formulazione standard prevede una semplice lista dei demoni da aggiungere, eventualmente facendo notare dipendenze o conflitti con altri demoni, ed un link a Daemon (Italiano).
  • Fornire esempi su come avviare (start), riavviare (restart) o stoppare (stop) demoni è una pratica deprecata: la formulazione standard prevede una descrizione delle azioni che devono essere eseguite e un link a Daemon (Italiano).
    Ciononostante, se l'azione richiesta non è una di esse, fornire un esempio è accettabile, e si dovrebbe far uso del comando rc.d invece di usare l'intero percorso /etc/rc.d/demone.

Template Nota, Attenzione, Suggerimento

  • Template:Nota dovrebbe essere usato per informazioni che in qualche modo divergono da ciò che il lettore si aspetterebbe più naturalmente di trovare in una parte di un articolo. Questa definizione include anche note che danno informazioni più dettagliate su un particolare e che altrimenti sarebbero considerate un po' estranee all'articolo. Un altro esempio si ha quando è necessario esporre un annuncio temporaneo come per esempio il cambio di nome di un pacchetto.
    Una Nota può anche essere usata per sottolineare importanti informazioni che potrebbero essere facilmente trascurate da lettori non molto competenti sull'argomento.
  • Template:Attenzione dovrebbe essere usato per descrivere procedure che potrebbero avere conseguenze negative come essere particolarmente difficili ad essere annullate o addirittura danneggiare il sistema. I template Attenzione dovrebbero generalmente indicare sia le varie possibili conseguenze negative, sia le condizioni a causa delle quali esse potrebbero verificarsi o al contrario essere evitate.
  • Template:Suggerimento dovrebbe indicare un metodo o una procedura che potrebbe essere utile e portare beneficio per alcuni lettori, benché assolutamente non necessaria per completare l'operazione in esame, e pertanto tranquillamente trascurabile.
  • Quando due o più template Nota, Attenzione o Suggerimento devono apparire uno dopo l'altro in un certo punto di un articolo, è preferibile raggruppare i loro contenuti in una lista dentro un unico template, evitando di mettere i template uno sopra l'altro, a meno che essi non siano per niente correlati uno con l'altro. Ad esempio:
Suggerimento:
  • Esempio di suggerimento #1.
  • Esempio di suggerimento #2.

Shell

  • Non presupporre che l'utente stia usando una shell in particolare (ad esempio bash), tranne quando effettivamente necessario: cercare di essere il più possibile neutrale riguardo alle shell nello scrivere o editare gli articoli.

Metafora dell'ipertesto

  • Cercare di creare link reciproci tra il proprio articolo e quanti più altri possibile, utilizzando le varie parole-chiave nel testo.
  • Per i termini tecnici come chiamata di sistema che non sono trattati in nessun articolo dell'ArchWiki, creare un link alla relativa pagina di Wikipedia.
  • Nel creare link ad altri articoli della wiki, non usare gli URL completi, ma sfruttare la speciale sintassi per i link interni: [[Articolo della wiki]]. Questo metodo permetterà inoltre al software wiki di tenere traccia dei link interni, facilitando così la manutenzione.
    Leggere Help:Editing (Italiano)#Collegamenti per informazioni più dettagliate e usi più avanzati della sintassi dei link interni.
  • Eccetto in rari casi, non si dovrebbe lasciare un articolo senza che questo fornisca link a qualche altro, né si dovrebbero creare pagine orfane, cioè articoli che non sono linkati da nessun'altra pagina.
  • Prima di scrivere una procedura specifica in un articolo, o descrivere qualcosa in particolare, controllare sempre che non esista già una pagina che tratta quella parte in dettaglio: in quel caso, creare un collegamento a quell'articolo invece di duplicare il suo contenuto.
  • Se la documentazione ufficiale per l'argomento del proprio articolo è ben scritta e aggiornata, preferire scrivere solamente adattamenti specifici per Arch, e linkare alla documentazione ufficiale per le informazioni generiche.

Sezioni "Trucchi e consigli"

  • Suggerimenti avanzati o esempi dell'utilizzo del software.
  • Il titolo standard è Trucchi e consigli.
  • I vari trucchi e consigli devono essere organizzati in sottosezioni.

Sezioni "Risoluzione di problemi"

  • Domande frequenti riguardo al software, o soluzioni a problemi comuni (confrontare con #Sezioni "Problemi noti").
  • Il titolo standard è Risoluzione di problemi; usare l'Inglese Troubleshooting non è considerato conforme a queste linee-guida.
  • È anche possibile riportare soluzioni temporanee per bug conosciuti, ma in tal caso è fortemente preferibile fornire un link al bug report, e nel caso questo non esista ancora si consiglia di crearlo, in maniera da aumentare le possibilità che il bug venga corretto in maniera appropriata.
    Linkare a un bug report porta grandi benefici sia ai lettori che a coloro che mantengono l'articolo:
    • Per i lettori, la Wiki non è un vicolo cieco: viene invece data loro la possibilità di trovare maggiori informazioni, più vicine alla fonte, che magari potrebbero non aver trovato con i propri metodi di ricerca.
    • Per i redattori della Wiki, viene resa più facile la manutenzione riducendo gli sforzi necessari per controllare se il bug riportato è stato risolto nel frattempo; questo può anche dare modo ad un lettore di aggiornare autonomamente l'articolo nel caso trovi informazioni più recenti nel bug report.

Sezioni "Problemi noti"

  • Elencano bug conosciuti o problemi di utilizzo per cui ancora non esiste una soluzione (confrontare con #Sezioni "Risoluzione di problemi").
  • Il titolo standard è Problemi noti.
  • Se esiste un bug report per il problema, è fortemente preferibile includere un link ad esso; nel caso non esista, bisognerebbe provvedere a riportarlo, in maniera da aumentare le probabilità che il bug venga corretto.

Sezioni "Altre risorse"

  • Una lista di link a pagine di riferimento e fonti per informazioni addizionali.
  • Dovrebbe essere una lista in cui ogni voce comincia con *.
  • Il titolo standard è Altre rirorse, è meglio evitare altri titoli simili come Link esterni, Vedere anche ecc.

Non-pertinent content

  • Please do not sign articles, nor credit article authors: the ArchWiki is a work of the community, and the history of each article is enough for crediting its contributors.
    Reporting the sources used to write an article, though, is good practice: you can use the "See also" section for this purpose.
  • Uploading files is disabled for normal users, and including the existing images in articles is not allowed. As an alternative you can include links to external images or galleries, and if you need to draw simple diagrams you may use an ASCII editor like Asciiflow.

Language register

  • Articles should be written using a formal language register.
  • Avoid contractions: "don't," "isn't," "you've," etc. should be "do not," "is not," "you have," for example.
  • Avoid unnecessary shortening of words: for example instead of "repo," "distro," and "config," prefer "repository," "distribution," and "configuration."
  • Do not include personal comments on articles; use discussion pages for this purpose. In general, do not write in first person.

Discussion pages

  • Add new discussions at the bottom of discussion pages and with a proper heading. You can also make use of the + tag at the top of each discussion page.
  • Indent your answers using colons at the beginning of new lines.
  • Always append a signature to your edits.
  • Discussion pages should not be categorized.
  • You should take care to strike the header of exhausted discussions using <s> tags.
    Exhausted discussions will be deleted a while after striking.

Category pages

  • Every category must be categorized under at least one parent category, except for root categories.
    Root categories are language categories, like Category:English and some other special categories: Category:DeveloperWiki, Category:Sandbox and Category:Template.
  • A category can be categorized under more than one category, provided one is not ancestor of the others.
  • Avoid circular relationships: two categories cannot be reciprocal ancestors.
  • Categories must be included at the top of the category page.
  • Categories should not redirect.

Redirect pages

  • Redirect pages should contain only the redirect code, nothing more.

Template pages

User pages

  • User pages cannot be categorized (this rule can be infringed in very rare, admin-approved cases).

Generic rules

Edit summary

  • The changes made daily to the articles are bravely checked by dedicated and voluntary patrollers, whom you must help by making sure that all your edits are accompanied by some explanation words in the "Summary" field of the editor page.
    • If the edit is minor, e.g. grammar or orthography corrections or the simple rewording of a sentence, a simple description of your edit is perfectly enough.
    • If you are performing a major change, e.g. adding, moving, modifying or removing content, besides summarizing your edit, you should make sure to explain the reason why you edited the article, even linking to a discussion on the wiki or the forums, if one exists at all.
    • An explanation is not mandatory in talk pages, where the why should be already evident.
      When deleting exhausted discussions, however, some explanation words are required (e.g. "closed discussion," "fixed," etc.) and including also the title of the discussion could help retrieving it in the history in case it needs to be reopened.
Tip: Take a look at the edit summaries in the Recent Changes to get an idea of what you should write in your summary, but be warned that unfortunately not all users respect these guidelines.
  • When performing major changes to articles, you should better try to split your work in multiple edits, based on the logical steps needed to complete the change.

HTML tags

  • Usage of HTML tags is generally discouraged: always prefer using wiki markdown or templates when possible, see Help:Editing and related.
  • When tempted to use <pre>code</pre>, always resort to {{bc|code}}. When tempted to use <tt>text</tt> or <code>text</code>, always resort to {{ic|text}}.
  • Especially avoid HTML comments (<!-- comment -->): it is likely that a note added in a HTML comment can be explicitly shown in the article's discussion page.
    You can add an appropriate Article status template in place of the comment.
  • Use <br> only when necessary: to start a new paragraph or break a line, put a blank line below it.
    Common exceptions to this rule are when it is necessary to break a line in a list item and you cannot use a sub-item, or inside a template and you cannot use a list.