WikiPages/pt-br

Esta página é uma extensão da página Help:Editing e dá orientações comuns para escrever e atualizar a documentação do wiki FreeCAD. Resume várias discussões e sessões de troca de ideias.

Antes de começar

 * Esta documentação wiki é baseada no MediaWiki, o mesmo ‘software’ que alimenta a Wikipédia. Se você já contribuiu para a Wikipédia, a edição de páginas wiki FreeCAD deve ser fácil.
 * Ao contrário da Wikipedia, o wiki FreeCAD está protegido contra ‘spam’. É necessário solicitar uma conta no forum.
 * Se nunca utilizou ‘software’ wiki antes, por favor leia Help:Editing para se familiarizar com a marcação que é utilizada.
 * Para o uso avançado do ‘software’ wiki, ver MediaWiki Ajuda:Conteúdo. Nem todas as características do MediaWiki estão disponíveis neste wiki FreeCAD, mas muitas estão.
 * Gostamos de manter a documentação de fácil leitura, por isso evite utilizar características complexas. Mantenha-a simples.
 * Use uma sandbox para testar o seu código, por exemplo, FreeCADDocu:Sandbox ou uma página específica com o seu nome Sandbox:Yourname.
 * Por favor, esteja atento às traduções. O wiki FreeCAD utiliza suporte de tradução automática para fornecer páginas em diversas línguas. Para cada página podem existir várias versões linguísticas. Em muitas páginas vê-se etiquetas como   e muitas etiquetas individuais como  . Estas últimas são criadas pelo sistema de tradução. Elas ligam os títulos e parágrafos às suas versões traduzidas. Não devem ser alterados, já que isso destruiria essas ligações. No entanto, não há problema em mover parágrafos ou alterar a redação, desde que as etiquetas permaneçam com eles. Se remover um título ou um parágrafo, deve também remover a etiqueta correspondente. Tenha em conta que as alterações nos títulos e parágrafos existentes influenciam as traduções existentes. As suas modificações devem valer a pena. Não se preocupe quando adicionar novo material porque o sistema irá adicionar novas etiquetas automaticamente após as suas edições. Para mais informações ver  Localisation e a página original Help:Extensão:Translate/Exemplo de tradução de página.

Descrições concisas
Ao descrever o FreeCAD tente ser conciso e direto e evite a repetição. Descrever o que o FreeCAD "faz", e não o que o FreeCAD "não faz". Evite também expressões coloquiais. Utilizar "alguns" quando se lida com um número indeterminado, ou especificar a quantidade correta.


 * Descrição ruim
 * PartDesign Workbench a PartDesign é uma bancada de trabalho para a concepção de peças que visa fornecer ferramentas para a modelação de peças sólidas complexas.


 * Boa descrição
 * PartDesign Workbench visa fornecer ferramentas para modelação de peças sólidas complexas.

Informação centralizada
Evitar duplicar informações. Insira a informação numa nova página, e crie um link para esta, e utilize o quando precisar reutilizar informação.

Não utilizar a tranclusão de páginas (Help:Editing#Modelos e paginas Transcluidas), visto que isto torna o wiki difícil de traduzir. Utilize apenas os modelos descritos abaixo em #Modelos.

Estilo
Os modelos são usados para estilizar as páginas de ajuda. Eles dão à documentação uma aparência uniforme. Há um modelo para comandos de 'menu', Arquivo → Salvar, um modelo para mostrar as teclas a serem pressionadas,, para mostrar um valor booleano, , etc. Familiarize-se com a seção #Modelos antes de escrever páginas de ajuda.

Sinalizadores temporários
Se estiver a trabalho numa página grande é aconselhável marcar a página como em construção ou como inacabada. Isto assegura que os administradores do wiki não marquem a sua página como pronta para tradução enquanto ainda está a alterá-la.

Para sinalizar uma página, adicionar  ou   na primeira linha. Com   convidará outros a juntarem-se a ti para terminar a página, enquanto    indica que tu realizarás o trabalho e que outros devem esperar o autor concluir.

Uma vez terminado o trabalho, por favor não se esqueça de retirar os sinalizadores!

Exemplos
Para se familiarizar rapidamente com a estrutura e estilo do wiki FreeCAD veja a página modelo: Modelo GuiCommand.

Estrutura
A Central do Usuário fornece um Índice 'On-line' de Ajuda. Este é usado como referência principal para compilar automaticamente a ajuda 'offline' que se encontra no FreeCAD, bem como a documentação PDF 'offline'.

O Modelo:Docnav é utilizado para ligar páginas sequencialmente, seguindo a estrutura do Índice 'On-line' de Ajuda. Veja #Modelos para uma lista de todos os Modelos.

Nomes de página
Os nomes das páginas devem ser curtos, e eles devem utilizar o estilo capitular: todas as palavras, exceto a primeira e os nomes próprios, tem de estar em caixa baixa. Este é o estilo adotado pela Wikipédia para seus artigos.


 * Nome de página ruim:
 * Construção de Aviões da AeroCompany


 * Bom nome de página:
 * Construção de aviões da AeroCompany

Os nomes das páginas de bancada de trabalho de alto nível devem ter este formato: em inglês  em  ‎português do Brasil   onde XYZ é o nome da bancada de trabalho, por exemplo, PartDesign Workbench,  Bancada de trabalho PartDesign. E os nomes das páginas que descrevem os comandos (ou ferramentas) pertencentes a um bancada de trabalho devem ter este formato:  por exemplo, PartDesign Pad. Note que deve-se usar o nome do comando como ele aparece no código fonte.

Uma convenção anterior previa a utilização de estilo primeiras maiúsculas: cada palavra deveria começar com uma letra maiúscula, a menos que sejam artigos, preposições, conjunções, ou outras partículas gramaticais (por exemplo, 'de', 'para', 'em', 'no', 'um', 'uma', 'e'). Há muitas páginas existentes que utilizam este estilo, mas é desaconselhável o uso em novas páginas. Isto foi discutido no tópico do fórum (Lowercase links) Use a lower case title for a wiki page.

Títulos
Tal como os nomes das páginas, os títulos dos parágrafos devem ser curtos e utilizar estilo capitular. Não deve utilizar H1 no título na sua marcação wiki, visto que o título da página é automaticamente adicionado como título principal.

Links
Você deve usar o nome do link original para links sempre que possível. Isso esclarece a página referenciada na documentação impressa ou ‘offline’. Evite palavras sem sentido para o link.

Link ruim
 * Para obter mais informações sobre como desenhar objetos 2D, clique aqui.


 * Bom link
 * Para obter mais informações sobre o desenho de objetos 2D, consulte a Bancada de trabalho Draft.

O melhor formato para um link é:

Traduzido:

Note que o que vem antes de, é o link real, isto é importante. Se o nome da sua página for, o link falhará se você digitar   (P em maiúsculo). Antes do caractere  todos os espaços devem ser substituídos por traço baixo. Isto é para ajudar os tradutores que utilizam programas de tradução, sem os sublinhados o link seria traduzido pelo ‘software’, o que é indesejável.

Para criar um link para um determinado parágrafo, adicione uma cerquilha  e o títulos a referenciar. Exemplo:

Traduzido:

Dentro da mesma página, você pode omitir o nome da página. Exemplo:

Para criar um link para o topo da página você pode usar:

Este link funcionará até mesmo se não houver parágrafo 'Topo' na página. Ele é especialmente útil para páginas longas, pois permite que o usuário volte rapidamente à lista de conteúdo. Você pode colocá-lo no final de cada parágrafo. Certifique-se de que haja uma linha vazia antes e depois do link.

Páginas do Workbench
Uma página de bancada de trabalho de alto nível deve começar com:
 * Uma descrição de para que serve a bancada de trabalho.
 * Uma imagem para ilustrar a descrição.

Consulte #Captura de tela para obter convenções sobre a inclusão de imagens.

Páginas de comando
As páginas de comando que descrevem as ferramentas da bancada de trabalho não devem ser muito longas, elas devem apenas explicar o que um comando pode e o que não pode fazer, e como usá-lo. Você deve manter as imagens e os exemplos no mínimo possível. Tutoriais podem expandir os detalhes de como usar a ferramenta e fornecer detalhes passo a passo.

Consulte a página Modelo GuiCommand para obter mais detalhes.

Tutoriais
Um tutorial bem escrito deve ensinar como alcançar determinados resultados práticos rapidamente. Não deve ser muito longo, mas deve incluir instruções e imagens passo-a-passo suficientes para guiar o usuário. Conforme o FreeCAD evolui, os tutoriais podem tornar-se obsoletos, por isso é importante mencionar a versão FreeCAD usada nele, ou necessária para realizar o tutorial.

Para obter exemplos, visite a página Tutoriais.

Modelos
A estilização das páginas wiki do FreeCAD é conseguida através da utilização de modelos (Help:Editing#Templates_and_transcluding_pages). Garantem um aspecto e uma sensação padronizados em todas as páginas, e também tornam possível reestilizar o wiki. Para consultar a lista completa de modelos definidos, acesse Todas as páginas com prefixo (Template:). Mas, por favor, utilize apenas os modelos listados nas tabelas abaixo. Apenas em casos muito especiais deverá utilizar diretamente as marcações HTML.

Clique no link do modelo para ver as instruções de utilização de um modelo, e para ver a sua implementação. Os modelos são uma característica poderosa do ‘software’ MediaWiki. Deve ser um usuário wiki experiente se desejar propor adições e modificações aos modelos existentes. Se implementados de forma errada, os modelos dificultam a tradução de páginas para outras línguas, pelo que a sua utilização deve ser limitada à formatação de texto, a transclusão de páginas deve ser evitada. Veja MediaWiki Help:Predefinições para saber mais.

Modelos simples
Estes modelos aceitam um parâmetro de texto simples, e o formatam com um estilo particular.

Modelos complexos
Estes modelos requerem mais parâmetros de entrada, ou produzem um bloco de texto com um formato particular.

Artes gráficas
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.

Nome
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 at the end. For example for the command Draft Offset the image should be called.

Captura de tela
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.

Você não deve depender de uma configuração personalizada de sua área de trabalho ou sistema operacional quando criar capturas de tela e deve usar os padrões gráficos da plataforma do FreeCAD sempre que possível.

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.

Texto
Para facilitar a tradução da documentação, tente evitar capturas de tela que contenham textos. Se você não puder evitar isto, considere tirar fotos separadas da ‘interface’ e da Vista 3D. A imagem da visualização 3D pode ser reutilizada em cada tradução, enquanto um tradutor pode tirar uma captura de tela da ‘interface’ localizada, se necessário.

Ícones e imagens
Consulte a página Objetos gráficos para todas as ilustrações e ícones que foram criados para o FreeCAD, e que também podem ser utilizados em páginas de documentação. Se quiser contribuir com ícones, favor ler as Diretrizes para trabalhos gráficos.

Traduções
Por consenso, a página de referência no wiki é a página em inglês, que deve ser criada primeiro. Se quiser alterar ou adicionar conteúdo a uma página, deve fazê-lo primeiro à página inglesa, e só após concluída a atualização, deve ser feita a modificação na página traduzida.

O wiki FreeCAD utiliza uma extensão de tradução que permite gerir traduções entre páginas mais facilmente; para mais detalhes, ver Localização Traduzir a wiki do FreeCAD.

Outros recursos úteis são:
 * código de idioma ISO para identificar o código de duas letras para uma linguagem específica para a qual se pretende traduzir.
 * Google Tradutor para ajuda com traduções.
 * Deepl Tradutor para ajuda com traduções.

Traduzir GuiCommand
Traduzido:

Traduzir navi
Traduzido:

Traduzir link
Part Module

Traduzido:

Atelier Pièces /

Traduzir Docnav
Traduzido:

Exemplo com ícones:

Traduzido:

Renomear páginas
Como o FreeCAD é um projeto em permanente desenvolvimento, é por vezes necessário rever o conteúdo do wiki. Se os nomes dos comandos forem alterados no código-fonte, as páginas wiki que os documentam têm de ser renomeadas também. Isto só pode ser feito pelos administradores do wiki. Para informar os administradores, abrir um tópico no fórum Wiki e listar a alteração de nome necessária nesta forma:

old name        new name Old_page_name_1 New_page_name_1 Old_page_name_2 New_page_name_2 ...

Excluir arquivos e páginas
Caso precise apagar um arquivo, vá à sua página e edite-o. Não importa se a página está em branco ou não, adicione isto como primeiro elemento:  e imediatamente abaixo descreva por que razão a página deve ser apagada. Além disso, abrir um tópico no fórum Wiki.

Para páginas, o procedimento é o mesmo.

Discussão
O subforum Desenvolvimento/Wiki no fórum FreeCAD oferece um espaço dedicado à discussão de tópicos da wiki, a aparência da wiki e tudo o mais relacionado com a wiki. Coloque lá as suas perguntas e sugestões.

Inglês
Consulte Glossário.

Outros idiomas

 * Italiano
 * Francês
 * Alemão
 * Polonês