Escrevendo documentação do projeto em HTML
O HyperText possui mais recursos do que texto simples para aprimorar sua documentação.
A documentação é uma parte importante de qualquer projeto técnico. Uma boa documentação informa ao usuário final como executar o programa, como usá-lo ou como compilá-lo. Para muitos projetos, a documentação em texto simples é o padrão. Afinal, todo sistema pode exibir arquivos de texto simples.
No entanto, o texto simples é limitante. Os arquivos de texto simples não possuem elementos de formatação, como texto em itálico, negrito e títulos. Para adicionar esses elementos, podemos aproveitar o HTML. HyperText Markup Language (HTML) é a linguagem de marcação usada em todos os navegadores da web. E com um pouco mais de esforço, você pode usar HTML para escrever documentação do projeto que possa ser lida por todos.
HTML usa uma série de tags entre colchetes angulares para controlar como as diferentes partes de um documento devem ser exibidas. Essas tags definem elementos em um documento HTML, como títulos de documentos, parágrafos, texto em itálico, texto em negrito e outros tipos de texto. Quase todas as tags vêm em pares: uma tag abertura, como
para iniciar um parágrafo, e uma tag fechamento para finalizar o elemento, como
para terminar um parágrafo. Ao usar essas tags, lembre-se desta regra:
se você abrir uma tag, será necessário fechá-la. Não fechar uma tag corretamente pode resultar no mau funcionamento do navegador.
Algumas tags definem um bloco dentro do documento HTML, enquanto outras são inline. Para obter mais informações sobre elementos de bloco e embutidos, leia meu outro artigo sobre uma introdução suave ao HTML.
Iniciar um documento vazio
Comece criando um documento HTML vazio padrão. Todo documento HTML deve fornecer uma declaração de tipo de documento. Use a tag única na primeira linha do arquivo HTML para definir um documento HTML. O padrão HTML também exige que as páginas envolvam o texto do documento em dois elementos de bloco: para definir o documento HTML e <body> para definir o corpo do texto. Embora o HTML não exija recuo cada novo bloco de código, eu o adiciono de qualquer maneira para que você possa ver que <body> está na verdade "dentro" do bloco :
<!DOCTYPE html>
<html>
<body>
</body>
</html>
Documentos HTML também precisam de um bloco <head> antes do <body> que fornece informações extras chamadas metadados sobre a página. Os únicos metadados necessários são o título do documento, definido pelo elemento
. Um documento vazio pode ter esta aparência:</p><pre><code><!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
</body>
</html></code></pre><h2 style="text-align: justify;">Adicione o texto</h2><p>Vamos exercitar algum conhecimento de HTML adaptando um arquivo "Leiame" de texto simples existente para HTML. Para este exemplo, estou usando parte da documentação sobre como jogar um jogo de tabuleiro de código aberto, chamado Simple Senet:</p><pre><code>HOW TO PLAY SIMPLE SENET
The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.
If the "throw" is zero, then you lose your turn.
When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit Space (or Enter) to
move it. You can select using several different methods:
- Up/down/left/right to navigate to a specific square.
- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.
- Tab to select your next piece on the board.
To quit the game at any time, press Q (uppercase Q) or hit Esc, and
the game will prompt if you want to forfeit the game.
You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!</code></pre><p>Comece adicionando este texto Leiame ao seu arquivo HTML vazio. O conteúdo principal de uma página HTML é o <body>, então é aí que você coloca o texto:</p><pre><code><!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
HOW TO PLAY SIMPLE SENET
The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.
If the "throw" is zero, then you lose your turn.
When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit Space (or Enter) to
move it. You can select using several different methods:
- Up/down/left/right to navigate to a specific square.
- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.
- Tab to select your next piece on the board.
To quit the game at any time, press Q (uppercase Q) or hit Esc, and
the game will prompt if you want to forfeit the game.
You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!
</body>
</html></code></pre><p>Sem mais alterações, este documento HTML parece completamente errado quando você o visualiza em um navegador da web. Isso ocorre porque o HTML, como a maioria dos sistemas de marcação, coleta <em>palavras</em> do arquivo de entrada e preenche <em>parágrafos</em> na saída. Como você ainda não adicionou outra marcação, um navegador da Web exibe o texto em um único parágrafo:</p><p><a href="common-images/writing-project-documentation-html/html-senet-1.webp"><img src="common-images/writing-project-documentation-html/html-senet-1.webp"></a></p><p>(Jim Hall, CC BY-SA 4.0)</p><h2 style="text-align: justify;">Parágrafos do corpo</h2><p>O primeiro passo para atualizar este arquivo Leiame para HTML é marcar cada parágrafo para que o navegador possa exibi-lo corretamente. A tag para definir um parágrafo é <p>. Embora nem tudo neste arquivo seja na verdade um parágrafo, comece agrupando tudo nas tags <p> e </p>:</p><pre><code><!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<p>HOW TO PLAY SIMPLE SENET</p>
<p>The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.</p>
<p>If the "throw" is zero, then you lose your turn.</p>
<p>When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit Space (or Enter) to
move it. You can select using several different methods:</p>
<p>- Up/down/left/right to navigate to a specific square.</p>
<p>- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</p>
<p>- Tab to select your next piece on the board.</p>
<p>To quit the game at any time, press Q (uppercase Q) or hit Esc, and
the game will prompt if you want to forfeit the game.</p>
<p>You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!</p>
</body>
</html></code></pre><script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-6366716774018597"
crossorigin="anonymous"></script>
<!-- linux-console.net - в статье - после 15 параграфа -->
<ins class="adsbygoogle"
style="display:block"
data-ad-client="ca-pub-6366716774018597"
data-ad-slot="1482127509"
data-ad-format="auto"
data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script><p>Isso faz com que o Leiame pareça mais um documento que você deseja ler. Ao visualizar o novo documento em um navegador da web, cada parágrafo começa em uma nova linha, com algum espaço extra acima e abaixo. O parágrafo é o exemplo mais comum de elemento de bloco.</p><p><a href="common-images/writing-project-documentation-html/html-senet-2.webp"><img src="common-images/writing-project-documentation-html/html-senet-2.webp"></a></p><p>(Jim Hall, CC BY-SA 4.0)</p><h2 style="text-align: justify;">Títulos e subtítulos</h2><p>A primeira linha do seu conteúdo é o título do seu documento, então você deve transformá-lo em um título. HTML fornece seis níveis de títulos, de <h1> a <h6>. Na maioria dos documentos, você pode usar <h1> para definir o título do documento e <h2> para subseções principais. Faça essa alteração em seu documento Leiame de amostra. Use o nome do programa ("Simple Senet") como título da seção principal e "Como jogar" como subseção do documento.</p><p>Observe que neste exemplo, também atualizei o <title> nos metadados do documento para usar o mesmo título do cabeçalho <h1>. Na verdade, isso não muda a forma como os navegadores exibem o documento, mas é uma boa prática usar:</p><pre><code><!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
...
</body>
</html></code></pre><p>Ao adicionar estes títulos de seção, você tornou o documento mais fácil de ler:</p><p><a href="common-images/writing-project-documentation-html/html-senet-3.webp"><img src="common-images/writing-project-documentation-html/html-senet-3.webp"></a></p><p>(Jim Hall, CC BY-SA 4.0)</p><h2 style="text-align: justify;">Listas ordenadas e não ordenadas</h2><p>Seu documento inclui uma lista de diferentes maneiras de navegar no jogo de tabuleiro. Como este documento começou como um arquivo de texto simples, cada item da lista começa com um hífen. Mas você pode usar HTML para definir esses três parágrafos como itens de lista.</p><p>HTML suporta dois tipos de listas: listas <em>ordenadas</em> e <em>não ordenadas</em>. Uma lista ordenada <ol> é uma série numerada que você pode usar para definir uma sequência de etapas. Uma lista não ordenada <ul> define uma lista de itens que podem ou não estar relacionados, mas geralmente não são feitos em ordem. Ambas as listas usam itens de lista <li> para entradas na lista.</p><script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-6366716774018597"
crossorigin="anonymous"></script>
<ins class="adsbygoogle"
style="display:block; text-align:center;"
data-ad-layout="in-article"
data-ad-format="fluid"
data-ad-client="ca-pub-6366716774018597"
data-ad-slot="9360617528"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script><p>Atualize o documento Leiame para usar uma lista ordenada em vez de parágrafos. Apresenta as três opções de navegação em uma lista numerada:</p><pre><code> <ol>
<li>Up/down/left/right to navigate to a specific square.</li>
<li>Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</li>
<li>Tab to select your next piece on the board.</li>
</ol></code></pre><p>Isso apresenta as três opções em uma lista numerada:</p><p><a href="common-images/writing-project-documentation-html/html-senet-4.webp"><img src="common-images/writing-project-documentation-html/html-senet-4.webp"></a></p><p>(Jim Hall, CC BY-SA 4.0)</p><p>No entanto, esses três itens não são realmente uma sequência de etapas, mas diferentes opções para mover a seleção no jogo Simple Senet. Então, em vez de uma lista ordenada, queremos usar uma lista não ordenada. Isso requer a atualização de <ol> para <ul> no documento:</p><pre><code> <ul>
<li>Up/down/left/right to navigate to a specific square.</li>
<li>Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</li>
<li>Tab to select your next piece on the board.</li>
</ul></code></pre><p>A lista não ordenada usa marcadores para cada item da lista, porque as entradas não fazem parte de uma sequência:</p><p><a href="common-images/writing-project-documentation-html/html-senet-5.webp"><img src="common-images/writing-project-documentation-html/html-senet-5.webp"></a></p><p>(Jim Hall, CC BY-SA 4.0)</p><h2 style="text-align: justify;">Negrito e itálico</h2><p>Você pode destacar certas informações no documento aplicando os estilos <strong>negrito</strong> e <em>itálico</em>. Esses são estilos de texto muito comuns em redação técnica. Você pode usar negrito para destacar informações importantes ou itálico para enfatizar frases-chave e novos termos.</p><p>A tag em negrito foi originalmente definida como <b>, mas as versões mais recentes do padrão HTML preferem a tag para indicar grande importância, como etapas principais em um conjunto de instruções. Ambas as tags são válidas, mas são semanticamente ligeiramente diferentes. <b> agora significa "chamar a atenção para".</p><p>Da mesma forma, o padrão HTML original usava <i> para texto em itálico. Versões posteriores de HTML preferem para dar ênfase a partes do texto. Em vez disso, <i> agora identifica textos idiomáticos ou termos técnicos.</p><p>Neste exemplo, use negrito para identificar os pressionamentos de tecla de uma única letra e itálico para indicar teclas especiais em um teclado como <em>Enter</em> e <em>Espaço</em>. Para simplificar, use as tags <b> e <i> aqui (mas você pode usar as tags e <em> para obter o mesmo efeito :)</p><pre><code><!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
<p>The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.</p>
<p>If the "throw" is zero, then you lose your turn.</p>
<p>When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit <i>Space</i> (or <i>Enter</i>) to
move it. You can select using several different methods:</p>
<ul>
<li><i>Up</i>/<i>down</i>/<i>left</i>/<i>right</i> to navigate to a specific square.</li>
<li>Plus (<b>+</b>) or minus (<b>-</b>) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</li>
<li><em>Tab</em> to select your next piece on the board.</li>
</ul>
<p>To quit the game at any time, press <b>Q</b> (uppercase Q) or hit <i>Esc</i>, and
the game will prompt if you want to forfeit the game.</p>
<p>You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!</p>
</body>
</html></code></pre><p>Esses estilos extras ajudam itens especiais a se destacarem no texto:</p><p><a href="common-images/writing-project-documentation-html/html-senet-6.webp"><img src="common-images/writing-project-documentation-html/html-senet-6.webp"></a></p><p>(Jim Hall, CC BY-SA 4.0)</p><p>O objetivo de escrever documentação é que os usuários entendam como usar o software, portanto, todo projeto de código aberto deve se esforçar para escrever a documentação de uma forma que seja fácil de ler. Com algumas tags HTML básicas, você pode escrever documentação que apresente as informações de forma mais clara aos seus usuários.</p><p>Para obter mais informações sobre como usar HTML para escrever documentação, verifique a referência completa da HyperText Markup Language no MDN, a Mozilla Developer Network, hospedada pelo projeto web Mozilla.</p></div></div></div><h2>Artigos relacionados:</h2><ul><li><a href="https://pt.linux-terminal.com/?p=8021">Minhas 5 principais ferramentas para evitar distrações e escrever mais - ou qualquer trabalho, na verdade</a></li><li><a href="https://pt.linux-terminal.com/?p=5040">Ultimate Plumber - Escrevendo Linux Pipes com visualização instantânea ao vivo</a></li><li><a href="https://pt.linux-terminal.com/?p=4151">Escrever! – Aplicativo de escrita sem distração para sua produtividade</a></li><li><a href="https://pt.linux-terminal.com/?p=3150">Como usar conteúdo Markdown para gravação em vários formatos [Linux], Parte 1</a></li><li><a href="https://pt.linux-terminal.com/?p=3061">Três aplicativos úteis de escrita criativa para usuários de Linux</a></li><li><a href="https://pt.linux-terminal.com/?p=2968">Escrevendo seu primeiro programa Lua no Linux</a></li><li><a href="https://pt.linux-terminal.com/?p=2767">5 aplicativos de escrita sem distrações para Linux</a></li><li><a href="https://pt.linux-terminal.com/?p=2602">QuiEdit oferece uma experiência de escrita sem distrações no Ubuntu</a></li><li><a href="https://pt.linux-terminal.com/?p=1525">Project Brainstorm - um aplicativo de anotações para escrita, prototipagem e folhas de dicas gratuitas</a></li><li><a href="https://pt.linux-terminal.com/?p=1409">Os 15 melhores aplicativos de escrita de poemas para dispositivos Android</a></li><li><a href="https://pt.linux-terminal.com/?p=858">Os 10 melhores aplicativos de escrita para iPad para expor suas habilidades de escrita</a></li><li><a href="https://pt.linux-terminal.com/?p=847">Os 10 melhores aplicativos de escrita para Android para liberar sua criatividade</a></li><li><a href="/?p=34031">Escrevendo LeNet5 do zero em PyTorch</a></li><li><a href="/?p=34029">Escrevendo ResNet do zero em PyTorch</a></li><li><a href="/?p=34027">Escrevendo CNNs do zero em PyTorch</a></li></ul>
<!--
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<ins class="adsbygoogle"
style="display:block"
data-ad-format="autorelaxed"
data-ad-client="ca-pub-6366716774018597"
data-ad-slot="6954854262"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
-->
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-6366716774018597"
crossorigin="anonymous"></script>
<ins class="adsbygoogle"
style="display:block"
data-ad-format="autorelaxed"
data-ad-client="ca-pub-6366716774018597"
data-ad-slot="9511294053"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
<hr />
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- linux-console.net - после рекомендуемого контента -->
<ins class="adsbygoogle"
style="display:block"
data-ad-client="ca-pub-6366716774018597"
data-ad-slot="3562404162"
data-ad-format="auto"
data-full-width-responsive="true"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
</div>
</div>
<!-- /.row -->
</div>
<!-- /.container -->
<!-- Footer -->
<footer class="py-3 bg-dark">
<div class="container">
<p class="m-0 text-center text-white">Todos os direitos reservados. © Linux-Console.net • 2019-2024</p>
</div>
<!-- /.container -->
</footer>
<!-- Bootstrap core JavaScript -->
<script src="https://linux-console.net/vendor/components/jquery/jquery.min.js"></script>
<script src="https://linux-console.net/vendor/twbs/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
<!-- Yandex.Metrika counter -->
<script type="text/javascript" >
(function(m,e,t,r,i,k,a){m[i]=m[i]||function(){(m[i].a=m[i].a||[]).push(arguments)};
m[i].l=1*new Date();
for (var j = 0; j < document.scripts.length; j++) {if (document.scripts[j].src === r) { return; }}
k=e.createElement(t),a=e.getElementsByTagName(t)[0],k.async=1,k.src=r,a.parentNode.insertBefore(k,a)})
(window, document, "script", "https://mc.yandex.ru/metrika/tag.js", "ym");
ym(53753182, "init", {
clickmap:true,
trackLinks:true,
accurateTrackBounce:true,
webvisor:true
});
</script>
<noscript><div><img src="https://mc.yandex.ru/watch/53753182" style="position:absolute; left:-9999px;" alt="" /></div></noscript>
<!-- /Yandex.Metrika counter -->
</body>
</html>