WikiPages

From FreeCAD Documentation
Revision as of 16:06, 4 May 2024 by Simone.b (talk | contribs) (Created page with "|-- |SystemOutput |{{SystemOutput|Output text}} |Usato per indicare l'output di testo dal sistema.")

Questa pagina è un'estensione della pagina Help:Editing e fornisce linee guida comuni per scrivere e aggiornare la documentazione wiki di FreeCAD. Riassume diverse discussioni e sessioni di brainstorming

Prima di iniziare

  • Questa documentazione wiki è basata su MediaWiki, lo stesso software con cui è realizzata Wikipedia. Se si ha contribuito a Wikipedia, modificare le pagine wiki di FreeCAD dovrebbe essere facile.
  • Contrariamente a Wikipedia, la wiki di FreeCAD è protetta da scrittura per evitare spam. È necessario richiedere un account sul forum.
  • Se non si ha mai utilizzato il software wiki prima, leggere Help:Editing per acquisire familiarità con il markup utilizzato.
  • Per un utilizzo avanzato del software wiki, vedere MediaWiki Help:Contents. Non tutte le funzionalità di MediaWiki sono disponibili in questo wiki di FreeCAD, ma molte lo sono.
  • Si è intenzionati a mantenere la documentazione facile da leggere, quindi si dovrebbe evitare di utilizzare funzionalità complesse. Mantenerlo semplice.
  • Utilizzare una sandbox per testare il codice, ad esempio, FreeCADDocu:Sandbox o una pagina personale con il proprio nome Sandbox:Yourname. Le pagine Sandbox devono essere inserite nella categoria Sandbox. Questo viene fatto aggiungendo [[Category:Sandbox]] in fondo al codice wiki.
  • Si prega di fare attenzione alle traduzioni. Il wiki di FreeCAD utilizza il supporto della traduzione automatizzata per fornire pagine in molte lingue. Per ogni pagina possono esistere versioni in più lingue. In molte pagine ci saranno tag come <translate>...</translate> e molti tag singoli come <!--T:8-->. Questi ultimi contrassegnano le cosiddette unità di traduzione e vengono creati dal sistema di traduzione, non andrebbero mai creati manualmente. Collegano i titoli e i paragrafi alle loro versioni tradotte. Non vanno cambiati perché ciò distruggerebbe i collegamenti. È comunque possibile spostare paragrafi o modificare il testo purché i tag rimangano con essi. Se si rimuove un'intestazione o un paragrafo andrebbe rimosso anche il tag che gli appartiene. Tenere presente che le modifiche ai titoli e ai paragrafi esistenti influiscono sulle traduzioni esistenti. Le modifiche dovrebbero valerne la pena. Non preoccuparsi di aggiungere nuovo materiale perché il sistema aggiungerà automaticamente i nuovi tag dopo le modifiche. Per ulteriori informazioni vedere Localizzazione e la Mediawiki:Extension:Translate pagina originale.

Linee guida generali

Descrizioni concise

Quando si descrive FreeCAD si deve cercare di essere concisi e diretti ed evitare ripetizioni. Descrivere cosa fa FreeCAD, non cosa non fa FreeCAD. Evitare anche espressioni colloquiali come "una coppia". Utilizzare "alcuni" quando si ha a che fare con un numero indeterminato o specificare la quantità corretta.

Descrizione errata
Ambiente PartDesign: PartDesign è un ambiente di lavoro per la progettazione di parti che mira a fornire strumenti per la modellazione di parti solide complesse.
Descrizione corretta
Ambiente PartDesign: mira a fornire strumenti per la modellazione di parti solide complesse.

Informazioni centralizzate

Evitare di duplicare le stesse informazioni in luoghi diversi. Inserire le informazioni in una nuova pagina e collegarsi a questa pagina da altre pagine che richiedono queste informazioni.

Non utilizzare la transclusione delle pagine (Help:Editing#Templates and transclosure pagine), poiché ciò rende difficile la traduzione del wiki. Utilizzare solo i modelli descritti di seguito in #Templates.

Stile

I modelli vengono utilizzati per definire lo stile delle pagine della guida. Conferiscono alla documentazione un aspetto coerente. C'è un modello per i comandi di menu, File → Salva, un modello per definire lo stile dei tasti da premere, Shift, per mostrare un valore booleano, true, ecc. Per favore acquisire familiarità con la sezione #Templates prima di scrivere pagine di aiuto.

Flag temporanei

Se si sta lavorando su una pagina di grandi dimensioni è consigliabile contrassegnare la pagina come work in progress o come incompiuta. Ciò garantisce che gli amministratori wiki non contrassegnino la tua pagina come pronta per la traduzione mentre la si sta ancora modificando.

Per contrassegnare una pagina, aggiungere come prima linea {{Page in progress}} o {{UnfinishedDocu}}. Con {{UnfinishedDocu}} si invitano gli altri a collaborare per finire la pagina, mentre {{Page in progress}} indica che si svolgerà il lavoro da solo e che gli altri dovrebbero lasciarti un po' di tempo.

Una volta terminato il lavoro, non dimenticare di rimuovere i flag!

Esempi

Per acquisire rapidamente familiarità con la struttura e lo stile del wiki di FreeCAD, guardare la pagina del modello: modello di base.

Struttura

L'Hub degli utenti fornisce un Sommario. Viene utilizzato come riferimento principale per creare automaticamente la guida offline raggiungibile da FreeCAD, nonché la documentazione PDF offline.

Il Template:Docnav viene utilizzato per collegare in sequenza le pagine, seguendo la struttura del Sommario. Vedere #Templates per un elenco di tutti i modelli.

Nomi delle pagine

I nomi delle pagine dovrebbero essere brevi e dovrebbero usare le maiuscole: ogni parola dovrebbe iniziare con una lettera maiuscola, a meno che non si tratti di articoli, preposizioni, congiunzioni o altre particelle grammaticali (ad esempio 'di', 'su', 'in', 'a ', 'uno', 'e').

Nome della pagina errato
Construction of AeroCompany airplanes
Nome della pagina corretto
Construction of AeroCompany Airplanes

I nomi delle pagine dell'ambiente di lavoro del livello superiore devono avere questo formato: XYZ Workbench, dove XYZ è il nome del workbench, ad esempio PartDesign Workbench. E i nomi delle pagine che descrivono i comandi (o strumenti) appartenenti a un ambiente devono avere questo formato: Comando XYZ, ad esempio PartDesign Pad. Tenere presente che si dovrebbe utilizzare il nome del comando così come appare nel codice sorgente.

Intestazioni

I titoli dei paragrafi dovrebbero essere brevi e utilizzare maiuscole e minuscole: tutte le parole, tranne la prima e i nomi propri, dovrebbero essere in minuscolo. Non si dovrebbero utilizzare le intestazioni H1 (= Heading =) nel markup della wiki, in quanto nel titolo della pagina viene aggiunto automaticamente come intestazione principale H1.

Link

Si dovrebbe utilizzare il nome del collegamento originale per i collegamenti quando possibile. Questo rende più evidente la pagina di riferimento nella documentazione stampata oppure offline. Si prega di evitare parole prive di significato per il collegamento.

Collegamento errato
Per ulteriori informazioni sul disegno di oggetti 2D, fare clic qui.
Collegamento corretto
Per ulteriori informazioni sul disegno di oggetti 2D fare riferimento a Draft.

Il formato preferito per un collegamento è:

[[Name_of_Page/it|Name of Page]]

Tradotto

[[Name_of_Page/fr|Nom de la Page]]

Tenere presente che per la parte prima del carattere |, ovvero il link effettivo, è rilevante la distinzione tra maiuscole e minuscole. Se il nome della pagina è Name_of_page il collegamento non funzionerà se si digita Name_of_Page (P maiuscola). Prima del carattere | tutti gli spazi devono essere sostituiti da trattini bassi (_). Questo serve per aiutare i traduttori che utilizzano software di traduzione, senza i caratteri di sottolineatura il collegamento verrebbe tradotto dal software, il che è indesiderabile.

Per collegarsi a un determinato paragrafo aggiungere un segno # e le sue intestazioni al nome della pagina. Esempio:

[[WikiPages#Links|WikiPages]]

Tradotto

[[WikiPages/fr#Liens|WikiPages]]

All'interno della stessa pagina si può omettere il nome della pagina. Esempio:

[[#Links|Links]]

Per collegarsi alla parte superiore della pagina è possibile utilizzare:

</translate>{{Top}}<translate>

Questo template dovrebbe visualizzare automaticamente il testo corretto a seconda della lingua della pagina. Un collegamento alla parte superiore della pagina è particolarmente utile per le pagine lunghe poiché consente all'utente di tornare rapidamente al sommario. Lo si può mettere alla fine di ogni paragrafo. Assicurarsi che ci sia una riga vuota prima e dopo il template.

Collegamento a una immagine
Testo facoltativo che viene mostrato quando passi il mouse sull'immagine

Per utilizzare un'immagine come collegamento:

[[Image:Draft_Wire.svg|24px|Testo facoltativo che viene mostrato quando passi il mouse sull'immagine|link=Draft_Wire]]

Immagine del Collegamento + testo del collegamento
Draft Wire

Se si tralascia il testo facoltativo, il collegamento stesso verrà mostrato quando si passa sull'immagine, il che è preferibile, e si dovrebbe anche aggiungere un collegamento testuale dopo il collegamento dell'immagine:

[[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]

Pagine degli Ambienti di lavoro

Una pagina dell'ambiente di livello superiore dovrebbe iniziare con:

  • Una descrizione dello scopo per cui viene utilizzato l'ambiente.
  • Un'immagine per illustrarne la descrizione.

Vedere #Screen capture per le convenzioni su come inserire le immagini.

Pagine dei comandi

Le pagine dei comandi che descrivono gli strumenti dell'ambiente di lavoro non dovrebbero essere troppo lunghe, dovrebbero solo spiegare cosa può fare un comando e cosa no, e come usarlo. Si dovrebbe ridurre al minimo le immagini e gli esempi. I tutorial si possono espandere riguardo l'utilizzo dello strumento e fornire dettagli passo passo.

Per ulteriori dettagli, fare riferimento alla pagina dei Modelli per la descrizione dei comandi.

Tutorial

Un tutorial ben scritto dovrebbe insegnare come ottenere rapidamente determinati risultati pratici. Non dovrebbe essere troppo lungo, ma dovrebbe includere immagini e istruzioni passo passo sufficienti per guidare l'utente. Man mano che FreeCAD si evolve, i tutorial potrebbero diventare obsoleti, quindi è importante menzionare la versione di FreeCAD utilizzata o richiesta per un tutorial.

Per esempi visitare la pagina dei Tutorial.

Templates

Lo stile delle pagine wiki di FreeCAD si ottiene attraverso l'uso di modelli (Help:Editing#Templates_and_transcluding_pages). Garantiscono un aspetto standardizzato in tutte le pagine e consentono anche di rimodellare il wiki. È possibile visualizzare l'elenco completo dei modelli definiti accedendo a Special:PrefixIndex/Template:. Si prega tuttavia di utilizzare solo i modelli elencati nelle tabelle seguenti. Solo in casi molto particolari si possono utilizzare direttamente i tag HTML.

Fare clic sul collegamento del modello per visualizzare le istruzioni di utilizzo di un modello e per visualizzarne l'implementazione. I modelli sono una potente funzionalità del software MediaWiki. Si dovrebbe essere un utente wiki esperto per proporre aggiunte e modifiche ai modelli esistenti. Se implementati in modo errato, i template rendono difficile la traduzione delle pagine in altre lingue, quindi il loro utilizzo dovrebbe essere limitato alla formattazione del testo e la transclusione delle pagine dovrebbe essere evitata. Vedere MediaWiki Help:Templates per ulteriori informazioni.

Template semplici

Questi template accettano un parametro semplice di testo e lo formattano con uno stile particolare.

Template Aspetto Descrizione
Top

Inizio

Utilizzato per aggiungere un link che porta all'inizio della pagina.
Enfasi enfasi Utilizzato per enfatizzare una parte di testo.
KEY Alt Usato per indicare un tasto della tastiera che deve essere premuto.
ASCII Usato per indicare un tasto ascii in un'immagine (.svg) che deve essere premuto. E' necessario fornire il carattere desiderato oppure il numero del codice ascii del carattere.
Button Cancel Utilizzato per indicare un pulsante nell'interfaccia utente grafica che deve essere premuto.
RadioButton Option Utilizzato per indicare un pulsante di un'opzione nell'interfaccia utente grafica che deve essere Selezionato o No.
CheckBox Option Utilizzato per indicare una casella di controllo nell'interfaccia utente grafica che deve essere Selezionata o No.
SpinBox 1.50 Utilizzato per indicare una casella numerica nell'interfaccia utente grafica che può essere modificata.
ComboBox Menu 1 Utilizzato per indicare una casella combinata nell'interfaccia utente grafica che può essere modificata.
LineEdit Metal Nickel (Ni) Utilizzato per indicare un LineEdit nell'interfaccia utente grafica che può essere modificato.
FALSE, false false, false Utilizzato per indicare un valore booleano falso, ad esempio, come proprietà nell'editor delle proprietà. Questa è una scorciatoia. Poiché si tratta di un valore, preferire il Template Value false
TRUE, true true, true Utilizzato per indicare un valore booleano vero, ad esempio, come proprietà nell'editor delle proprietà. Questa è una scorciatoia. Poiché si tratta di un valore, preferire Template Value true
MenuCommand File → Save Usato per indicare la posizione di un comando all'interno di un particolare menu.
FileName File name Usato per indicare il nome di un file o di una cartella.
SystemInput Type this text Usato per indicare il testo di input digitato dall'utente.
SystemOutput Output text Usato per indicare l'output di testo dal sistema.
Incode import FreeCAD Use it to include in-line source code with a monospace font. It should fit in one line.
PropertyView VistaColor Use it to indicate a View property in the property editor. Examples of View properties include Line Color, Line Width, Point Color, Point Size, etc.
PropertyData DatiPosition Use it to indicate a Data property in the property editor. Data properties are different for different types of objects.
Properties Title / TitleProperty Base Use it to indicate the title of a property group in the property editor. The title will not be included in the automatic table of contents.
Obsolete obsolete in version 0.19 Use it to indicate that a feature became obsolete in the specified FreeCAD version.
Version introduced in version 0.18 Use it to indicate that a feature was introduces in the specified FreeCAD version.
VersionMinus version 0.16 and below Use it to indicate that a feature is available in the specified FreeCAD version and earlier versions.
VersionPlus version 0.17 and above Use it to indicate that a feature is available in the specified FreeCAD version and later versions.
ColoredText Colored Text Use this template to color the background, text, or background and text. (ColoredText page for more examples)
ColoredParagraph
Colored Paragraph
Use this template to color the background, text, or background and text of an entire paragraph. ColoredParagraph page for more examples)

Complex templates

These templates require more input parameters, or produce a block of text with a particular format.

Template Appearance Description
Prettytable This table Use it to format tables such as this one. Additional table properties can be added.
Caption

Some caption for an image

Use it to add an explanation below an image. It can be left aligned or center aligned.
Clear Use it to clear columns. Follow the definition of the template for a detailed explanation. It is often used to stop text from flowing next to unrelated images.
Code
import FreeCAD
Use it to include multi-line code examples with a monospace font. The default language is Python, but other languages can be specified.

Python code should adhere to the general recommendations established by PEP8: Style Guide for Python Code. In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable.

CodeDownload Use it to create a link on a macro page.
Codeextralink

Temporary code for external macro link. Do not use this code. This code is used exclusively by Addon Manager. Link for optional manual installation: Macro


# This code is copied instead of the original macro code
# to guide the user to the online download page.
# Use it if the code of the macro is larger than 64 KB and cannot be included in the wiki
# or if the RAW code URL is somewhere else in the wiki.

from PySide import QtGui, QtCore

diag = QtGui.QMessageBox(QtGui.QMessageBox.Information,
    "Information",
    "This macro must be downloaded from this link\n"
    "\n"
    "https://wiki.freecad.org/Main_Page" + "\n"
    "\n"
    "Quit this window to access the download page")

diag.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint)
diag.setWindowModality(QtCore.Qt.ApplicationModal)
diag.exec_()

import webbrowser 
webbrowser.open("https://wiki.freecad.org/Main_Page")
<class="rawcodeurl"><a href="https://wiki.freecad.org/Main_Page">raw code</a>
Use it if the code of a macro is too large to be hosted on the Wiki. The code can then be hosted somewhere else, and the raw link to it specified with this template. The Addon Manager will use this link.
Fake heading
Heading
Use it to create a heading that will not be automatically included in the table of contents.
GuiCommand See GuiCommand model Use it to create a box with useful information to document workbench commands (tools).
TutorialInfo See for example Basic modeling tutorial Use it to create a box with useful information to document tutorials.
Macro See for example Macro FlattenWire Use it to create a box with useful information to document macros.
Docnav
Online Help Startpage
Feature list
Use it to create a bar with arrows and appropriate links, which is useful for putting pages in a particular sequence.
VeryImportantMessage
Important Message
Use it to create a highlighted box with a very important message. Use sparingly, only to indicate major problems in the functionality of the software, discontinuation of tools, and similar.
Page in progress
This documentation is a work in progress. Please don't mark it as translatable since it will change in the next hours and days.
Use this for pages that are still in progress or that are currently being reworked. Don't forget to remove this when the page is ready.
UnfinishedDocu

This documentation is not finished. Please help and contribute documentation.

GuiCommand model explains how commands should be documented. Browse Category:UnfinishedDocu to see more incomplete pages like this one. See Category:Command Reference for all commands.

See WikiPages to learn about editing the wiki pages, and go to Help FreeCAD to learn about other ways in which you can contribute.

Use it to create a highlighted box indicating an unfinished documentation page.
Softredirect Use it instead of the normal redirect, when you are redirecting to a special page (such as Media: or Category:), in which cases the normal redirect is disabled.
Quote

Cry "Havoc" and let slip the dogs of war.

—William Shakespeare, Julius Caesar, act III, scene I
Use it to create a box of text with a literal quote and reference.
Userdocnavi, Powerdocnavi Use them to create navigation boxes for the user documentation, the power user documentation, and the developer documentation. This allows quickly jumping between different sections of the documentation. They also place the corresponding page in the proper category.

Graphics

Images and screenshots are necessary to produce a complete documentation of FreeCAD. They are particularly useful to illustrate examples and tutorials. Images should be shown in their original size, so they present sufficient detail and are readable if they include text. Bitmap images should not be resized.

Avoid animated pictures (GIF) in the general help pages. Animations and videos should be reserved for tutorials not intended to be used as offline PDF documentation.

Images can be uploaded through the Special:Upload page.

Name

Give meaningful names to your images. If you have an image that showcases the characteristics of a particular command, you should use the name of that command with _example at the end. For example for the command Draft Offset the image should be called Draft_Offset_example.png.

Screen capture

Recommended sizes for screen captures are:

  • Native 400x200 (or width=400 and height<=200), for command reference pages, to allow the picture to fit in the left part of the page, and for other standard snapshots.
  • Native 600x400 (or width=600 and height<=400), for command reference pages, when you really need a bigger picture, and still allow the picture to fit in the left part of the page, and for other standard snapshots.
  • Native 1024x768 (or width=1024 and height<=768), only for full screen images.
  • Smaller sizes are possible when showing details.
  • Avoid images with larger resolutions, as they won't be very portable to other kinds of displays or the printed PDF documentation.

You shouldn't depend on a custom configuration of your desktop or operating system when you create screenshots and you should use the visual defaults of the FreeCAD interface whenever possible.

To create a screenshots you can use the options provided by your operating system, or one of these macros: Macro Snip and Macro Screen Wiki.

Text

To ease documentation translations, try to avoid screenshots that contain texts. If you cannot avoid this, consider taking separate screenshots of the interface and the 3D view. The image of the 3D view can be reused in every translation, while a translator can take a screenshot of the localized interface if necessary.

Icons and graphics

Refer to the Artwork page for all artwork and icons that have been created for FreeCAD, and which can also be used in documentation pages. If you would like to contribute icons, please read the Artwork Guidelines.

Translations

As per general consensus, the reference page in the wiki is the English page, which should be created first. If you want to change or add content to a page, you should do it to the English page first, and only once the update is completed, port the modification to the translated page.

The FreeCAD wiki supports a translation extension that allows managing translations between pages easier; for details, see Localisation Translating the wiki.

Other useful resources are:

Some tips for translators

Translate GuiCommand

{{GuiCommand
|Name=FEM EquationFlux
|MenuLocation=Solve → Flux equation
|Workbenches=[[FEM_Workbench|FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial|FEM tutorial]]
}}

Translated:

{{GuiCommand/fr
|Name=FEM EquationFlux
|Name/fr=FEM Équation d'écoulement
|MenuLocation=Solveur → Équation de flux
|Workbenches=[[FEM_Workbench/fr|Atelier FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial/fr|FEM Tutoriel]]
}}

Translate navi

{{FEM_Tools_navi}}

Translated:

{{FEM_Tools_navi/fr}}

Translate link

[[Part_Module|Part Module]]

Translated:

[[Part_Module/fr|Atelier Part]]

Translate Docnav

{{Docnav
|[[About_FreeCAD|About FreeCAD]]
|[[Installing_on_Windows|Installing on Windows]]
}}

Translated:

{{Docnav/fr
|[[About_FreeCAD/fr|À propos de FreeCAD]]
|[[Installing_on_Windows/fr|Installation sous Windows]]
}}

Example with icons:

{{Docnav
|[[Std_Save|Save]]
|[[Std_SaveCopy|SaveCopy]]
|[[Std_File_Menu|Std File Menu]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}

Translated:

{{Docnav/fr
|[[Std_Save/fr|Enregistrer]]
|[[Std_SaveCopy/fr|Enregistrer une copie]]
|[[Std_File_Menu/fr|Menu fichier]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}

Create, rename and delete pages

Create pages

Before creating a new page you should first check if a similar page already exists. If that is the case it is usually better to edit that existing page instead. When in doubt please open a topic in the Wiki forum first.

To create a new page do one of the following:

  • Visit the URL with the desired page name, for example: https://wiki.freecadweb.org/My_New_Page, and click on 'create this page'.
  • Do a wiki search for the page name, and click on the red text in 'Create the page "My New Page" on this wiki!'.

Rename pages

Since FreeCAD is a project under permanent development, it is sometimes necessary to revise the content of the wiki. If the names of commands are changed in the source code, the wiki pages documenting them have to be renamed as well. This can only be done by wiki administrators. To inform them, open a topic in the Wiki forum and list the necessary renaming operation in this form:

old name         new name
Old_page_name_1  New_page_name_1
Old_page_name_2  New_page_name_2
...

Delete files and pages

In case you need to delete a file, go to its page (https://www.freecadweb.org/wiki/File:***.***) and edit it. No matter if the page is blank or not, add this as the first element: {{Delete}} and directly below it describe why the page should be deleted. Additionally, open a topic in the Wiki forum.

For pages the procedure is the same.

Discussion

The Development/Wiki subforum in the FreeCAD forum provides a dedicated space for discussing wiki topics, the wiki appearance and anything else related to the wiki. Direct your questions and suggestions there.

Terminology - naming policy

English

See Glossary.

Other languages