Como escrevo páginas de manual? [fechadas]

16

Como escrevo uma página de manual?

Onde posso encontrar uma referência para todos os códigos de formatação?

Existem bons tutoriais sobre como escrever páginas de manual?

Qual é a maneira mais conveniente de escrever uma página de manual? Devo inseri-lo diretamente em um editor de texto? Existem editores WYSIWYG? Ou devo escrever em um formato diferente e depois converter?

Quais regras uma boa página de manual deve seguir?

documentation

— amarillion
fonte

Esta questão parece ser muito ampla. Ele conseguiu atrair apenas um monte de respostas somente para links e algumas opiniões sem suporte.

— 200_success 15/10/2014

man man, man groff.

— Jenny D

13

Aqui estão algumas páginas da Web que ajudarão você a começar:

Algumas ferramentas úteis:

— Pausado até novo aviso.
fonte

6

Existem ferramentas para escrever páginas de manual que ignoram a formatação de troff. As páginas de manual são uma linguagem pequena e bem delimitada e fácil de segmentar.

Duas ferramentas populares são:

xmltoman , uma linguagem xml pequena e bem estruturada que pode gerar páginas de manual e html. É usado pelos projetos de Lennart Poettering, syrep e pulseaudio , por exemplo .
asciidoc , usado pelo git, por exemplo .

yodl e zoem parecem ser outros formatos legais neste espaço.

Em suma, eu recomendaria o xmltoman porque é um dsl muito específico da página de manual que o guiará de perto.

— Tobu
fonte

"dsl" == "idioma específico do domínio"?

— Pausado até novo aviso.

sim (. da si 15 caracteres..)

— Tobu

11

Outra boa opção é ronn , que lê a linguagem de marcação de texto Markdown mais amplamente usada.

— poolieby

5

Eu escrevi um artigo bastante extenso sobre o tópico, que você pode encontrar aqui:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

— Nathan Osman
fonte

4

Seria útil se você pudesse ao menos resumir o artigo aqui - os links sozinhos não valem quando a página vinculada inevitavelmente se move ou desaparece.

— Caleb

Eu não concordo com Caleb. Esta é a web. A web é baseada em links e o stackexchange não carrega nenhuma exceção especial. Copiar conteúdo é contraproducente. Qualquer coisa ruim que possa acontecer com essa página ou documento também pode acontecer com esta . Não podemos acumular cópias raspadas de todo o conteúdo apenas porque o restante da Web pode desaparecer. (Deixe esse trabalho em sites como a máquina de retorno).

— Kaz

Kaz, você pode não concordar, mas o comentário de Caleb é definitivamente a melhor prática do ServerFault.

— MadHatter suporta Monica

2

Não conheço nenhum IDEs ou tutoriais, mas você pode começar copiando uma página de manual existente e modificá-la para atender às suas necessidades.

Para uma referência da linguagem groff com macros MAN (que é usada por uma página de manual), consulte a página de manual groff_man ou leia-a on-line aqui

— Dan Andreatta
fonte

2

Dê uma olhada no projeto ronn . É uma redução para o gerador de páginas de manual. Ele também pode gerar as páginas do manual em HTML, como este .

Eu gosto da idéia de escrever toda a documentação do meu software em um formato. Markdown IMO é uma boa escolha

— Bruno Polaco
fonte