Submissão de Dica

Como escrever uma dica

Uma boa dica fornece informações que, de outra forma, não são facilmente obtíveis. Em geral, nós não estamos interessados(as) em dicas que copiem informações já no LFS ou no BLFS ou dicas que simplesmente listem os passos necessários para instalar um pacote conforme explicado no INSTALL ou no README de um pacote.

Isso ainda deixa um amplo escopo de assuntos. Dicas podem ser acerca de qualquer coisa para a qual uma correção ou hack não óbvio ou não trivial seja exigida. Uma dica também pode explicar uma instalação complicada de pacote ou uma configuração específica. Dê uma olhada em algumas outras dicas para ter uma ideia do que uma dica pode incluir. Verifique também o adote um programa de dicas caso exista alguma dica fofa que você gostaria de cultivar ou se alguém tiver sugerido um tópico para uma dica que você tenha conhecimento.

Depois de ter uma boa ideia para uma dica, você pode começar a escrever. Siga as seguintes regras de estilo se você quiser submetê-la para inclusão.

Diretrizes de submissão

• Antes de submeter uma dica, verifique se já existe uma dica acerca do tema. Se existir, então contate o(a) autor(a) se você tiver quaisquer atualizações. Se o(a) autor(a) anterior não estiver interessado(a) em manter a dica, ou se não existir resposta proveniente do(a) autor(a) por, pelo menos, um mês, então você poderá assumir a manutenção da dica. Lembre-se de incluir blfs-dev@lists.linuxfromscratch.org (como cópia) em toda a correspondência com o(a) autor(a), de modo que os(as) mantenedores(as) de dicas estejam cientes da mudança.
  Observe que isso não significa que dicas duplicadas acerca do mesmo tópico não sejam permitidas. Se você acha que o(a) autor(a) atual tem uma abordagem diferente para um problema e você tem uma que não corresponde à dica atual, sinta-se à vontade para enviar uma dica separada. Sugerimos comunicar-se com o(a)(s) autor(a)(es)(as) atual(is) antes de escrever a dica. Sugerimos escrever uma breve sinopse sobre como a nova dica difere da existente.
• Dicas deveriam ser reservadas para coisas que não podem ser incluídas no livro. Dicas relacionadas à instalação de pacotes e que caberiam facilmente no livro (geralmente o livro BLFS) deveriam ser submetidas à lista de desenvolvimento relevante. Se você estiver familiarizado(a) com DocBook e XML, então sinta-se à vontade para submeter um remendo para a versão de desenvolvimento atual do livro relevante. Se não, submeta um arquivo de texto que corresponda ao formato atual do livro e um(a) editor(a) do livro fará as modificações necessárias.
• Se você estiver no processo de escrita de uma dica acerca de um tópico, seria bom deixar uma linha na lista relevante, caso alguém esteja trabalhando em algo semelhante.
• Uma dica não deveria duplicar documentação que já está disponível em outro lugar acerca de um determinado tópico. Ela deveria complementá-la. Documentação disponível em outros lugares inclui documentação LDP e documentação disponível a partir do sítio web do pacote, documentação disponível por uma simples pesquisa no Google. Além disso, coisas que já estejam bem documentadas no(s) livro(s) ou no LDP não deveriam ser repetidas na dica, a menos que a dica descreva os assuntos com mais detalhes, de uma maneira diferente ou a partir de uma perspectiva diferente. Portanto, coisas como instalação do db, do freetype, do zlib, entre outros, podem ser referenciadas apenas por ponteiros para o livro.
• Autores(as) que não mais estejam interessados(as) em manter as dicas deles(as) deveriam enviar uma mensagem para a lista de discussão apropriada especificando que a dica está para adoção. O(A) autor(a) também deveria notificar a lista de dicas se a dica não mais for relevante.
• Dicas que tiverem sido integradas ao livro serão descontinuadas depois que uma versão estável do livro for lançada.
• Mantenha o nome do arquivo da dica curto, mas descritivo. A extensão para a dica deveria ser .txt. O nome pode ser composto de uma combinação de letras minúsculas, números e alguns símbolos _ - +.
• O documento de dicas é baseado em texto. O formato para as dicas é o conforme explicado no final deste documento.
• Evite incluir conjuntos de comandos sequenciados e remendos nas dicas. Mantenha-os em arquivos separados para evitar estragar a beleza da dica. :) Os remendos deveriam seguir o formato de remendos. Os remendos que você submeter serão enviados para o repositório de remendos (portanto, certifique-se de mencionar a dica na descrição do remendo) sob o nome do pacote apropriado. Os conjuntos de comandos sequenciados ou remendos que não se enquadrarem no projeto de remendos estarão disponíveis a partir do linque Anexos na página de transferência. Se você precisar referenciar quaisquer remendos na tua dica, aponte para o subprojeto de remendos (por exemplo, http://www.linuxfromscratch.org/patches/<nome_pacote>/<nome_remendo>). Se você precisar referenciar quaisquer anexos, aponte para o diretório de anexos (por exemplo, http://www.linuxfromscratch.org/hints/downloads/attachments/<nome_dica>/). Não se preocupe se os URIs estiverem incorretos; o(a) mantenedor(a) modificará os URIs antes de submeter. Como mantenedores(as) às vezes são preguiçosos(as), você pode precisar dar-lhes um empurrãozinho para "fazer a coisa certa".
• Para submeter ou atualizar uma dica, envie uma mensagem eletrônica para a lista de discussão blfs-dev. A partir daí ela será coletada pelo(a) mantenedor(a) da dica, que atualizará o índice da dica e o tarball. Você precisa estar inscrito(a) na lista para postar uma mensagem para evitar lixo eletrônico na lista.
• Observe que ao enviar uma dica, você concorda com as condições mencionadas nesta página com relação à dica. Em particular, você permite que outros(as) usantes assumam a manutenção da dica se outro(a) usante te contatar com uma solicitação (para assumir a manutenção ou integrar o trabalho dele(a) na tua dica) e você não responder à solicitação por um mês. Se você não deseja que alguém assuma a manutenção da dica, por favor indique isso claramente na dica. Os(As) autores(as) também deveriam manter as informações de contato atualizadas.

Formato de Dica

Cada dica deveria ter as seguintes seções, na ordem especificada aqui, para a finalidade de ter uma aparência consistente. Seções que sejam presumidas estarem em linhas únicas deveriam estar na mesma linha que o cabeçalho da seção. Seções que estejam em mais que uma linha deveriam começar a partir da linha seguinte ao cabeçalho. Confira a dica de exemplo para ter uma ideia acerca do formato.

AUTOR(A):

Esse campo pode ser repetido se existirem vários autores(as). Cada linha de autor(a) deveria ter nome e detalhes de contato do(a) autor(a) da dica. Restrinja esse campo para os(as) autores(as) atuais da dica. Autores(as) anteriores(as) deveriam ser reconhecidos(as) na seção AGRADECIMENTOS.

DATA:

A data que a dica foi atualizada pela última vez no formato internacional (AAAA-MM-DD).

LICENÇA:

A licença sob a qual a dica está licenciada. Os(As) mantenedores(as) de dicas sugerem a Licença GNU de Documentação Livre, mas você é livre para escolher a tua própria. A Licença GNU de Documentação Livre permite copiar tua dica e modificá-la sem restrições, com a exceção de que você sempre será creditado(a) como autor(a). Também indica que a dica não traz garantias. Para mais informações acerca de diversas licenças, visite o sítio do GNU. Antes de submeter a dica, verifique se uma cópia da LICENÇA sob a qual tua dica está licenciada está disponível no diretório de LICENÇAS. Se não, no momento da submissão da dica, inclua também uma nota e um URI para o(a) mantenedor(a) da dica baixar uma cópia de texto da LICENÇA.

SINOPSE

Uma descrição de uma linha acerca da dica. Por favor, mantenha isso curto e amável e restrinja-a a uma linha, pois esse é o título que seria incluído na página de dicas.

URI PRIMÁRIO:

Essa é uma seção opcional para autores(as) que gostam de hospedar as próprias dicas deles(as) e somente submeter atualizações ocasionais para o sítio de dicas do LFS.

DESCRIÇÃO:

Uma descrição curta acerca do por que a dica foi escrita, quem é o público-alvo, entre outras. Isso ajudaria um(a) usante a determinar se a dica é útil para ele(a).

ANEXOS:

Linques para transferências adicionais, como patches, conjuntos de comandos sequenciados, arquivos de configuração, entre outros. Essa seção é opcional.

PRÉ-REQUISITOS:

Nessa seção liste os pré-requisitos que o(a) usante precisa estar ciente antes de seguir a dica. Essa seção pode ser usada para indicar se a dica é aplicável somente para uma versão específica do LFS.

DICA:

Esse é o coração da dica. Liste os detalhes acerca da tua dica aqui. Não existe nenhuma restrição relativa a como você formata as coisas nessa seção, exceto (sempre existe alguma exceção) para evitar linhas que se pareçam com uma seção (ou seja, texto em MAIÚSCULAS seguido de ponto e vírgula). Além disso, faça teu melhor para restringir cada linha a 80 colunas (embora isso possa ser relaxado caso a caso). Evite incluir material que já esteja no livro.

AGRADECIMENTOS

Agradecimentos para pessoas que contribuíram para a dica. Essa seção é opcional.

REGISTRO DAS MUDANÇAS:

Inclui mudanças com registro de data e de hora que ocorreram na dica. Adicione as entradas mais recentes no final. Entradas nessa seção deveriam estar conforme segue:

• [AAAA-MM-DD]
•  * Mudou A
•  * Mudou B

OBSERVAÇÃO:

Essas instruções são baseadas nas respostas provenientes de muitos(as) usantes. Se você tiver sugestões para melhorar esse documento, sinta-se à vontade para discuti-las na lista de discussão blfs-dev.