Como o formato de código-fonte em um documento Framemaker?[fechado]

Question

Eu tenho de escrever um documento técnico, em Framemaker que explica vários de programação de código-fonte.

Então, a minha documento consiste de um monte de texto, seguido por um bando de código-fonte (Java, XML) e, em seguida, seguido por mais de texto, etc.

Esta pergunta não é sobre se eu deveria ou não deveria usar Framemaker - que é o software que eu uso ...

O que eu estou confuso sobre como formato de código-fonte como parte do documento.Ninguém tem feito isso por um documento técnico e vir através de quaisquer instruções ou sugestões?Até agora, meu Pesquisando ainda não produziu nada de relevante para o que eu preciso fazer.

Answer 1

No mínimo, crie um estilo de parágrafo para amostras de código, use uma boa fonte monoespactada e não se esqueça de desativar a hifenação.

Quando eu costumava fazer isso, eu criava um estilo de tabela e colava o código lá, então eu tinha um bom cabeçalho de título acima dele, e ele se destacava um pouco. O único petcha é que as células da tabela de quadros não vão quebrar uma quebra de página; portanto, se seu código for mais longo que uma página ou ameaça ficar abaixo da parte inferior de uma página, você precisará criar várias linhas em sua tabela e quebre o código nas linhas.

Answer 2

A partir de um artigo que eu escrevi sobre isso alguns anos atrás, que estará disponível online novamente na próxima semana.

Tipógrafos estão principalmente preocupados com a legibilidade, e ter ferramentas, práticas e tradições datam de centenas e, de fato, milhares de anos em que se possa confiar quando a configuração de textos em línguas naturais.No entanto, os programas de computador são escritos em línguas naturais.Eles está escrito em "linguagens de programação':línguas artificiais, que têm suas próprias regras de a sintaxe, as suas próprias convenções de apresentação, e os seus próprios critérios de legibilidade.Computador o código é, portanto, um domínio especial para a composição, assim como o são a música, a matemática e a química.Estes domínios têm suas próprias regras, que não são as regras utilizadas quando a configuração natural idiomas.

Programação de computador em si é de origem recente, e o prática de colocá-la em tipo de não voltar mais do que cerca de 45 anos:volumes significativos de código de computador têm sido publicados nos últimos 20 anos ou menos.O associado de digitação a disciplina é imaturo ou, de fato, praticamente inexistente, e a digitação as expectativas dos profissionais da área também são baixos, como você pode ver, inspecionando muitos comércio de livros.Não há nenhuma razão porque você não pode tentar fazer melhor.

1. Use um tipo de letra sans serif.Em um dos meus livros eu usei a mesma família de tipos de letra, FF Scala para o texto e FF Scala Sans para o código.Eu acho que ele parece grande, mas existem opiniões contrárias:estes podem forçar você a usar uma fonte monoespaçada, embora, pessoalmente, eu acho que isso é muito desatualizado.Evitar Courier, ele não se mistura com nada.

2. Recuo é parte da notação.Você deve respeitar a existente recuos à esquerda.O código-fonte já estará com guias.Reduzir cada guia para um ou dois espaços no mais, caso contrário, você vai ficar sem horizontal quarto.

3. Tente perder o máximo de espaço vertical possível, por exemplo,suprimir linhas em branco.Tente obter a amostra inteira em uma página.Deixe-o flutuar, se necessário, para realizar isso.

4. Quebras de linha são parte da notação.Não adicione quebras de linha, sem consulta ao autor.

5. As aspas são parte da notação.Não altere simples para o dobro ou vice-versa.

6. Justificação:Os programas de computador são escritos sempre, visto e definido justificado à esquerda, clique com o botão direito irregular.

7. As quebras de página.Quando a configuração de código de computador em um livro, as quebras de página não podem basta seguir o simples órfãs/viúvas princípios utilizados quando a tipografia línguas naturais.Em vez disso, a lógica de 'blocos' de código devem ser mantidos juntos, se possível.Geralmente não é possível para o tipógrafo para determinar o bloco de limites no código, embora uma linha em branco é geralmente aceitável aponte para uma quebra de página.'Bloco dos comentários deve ser mantido, com o seguinte bloco de código.Se você não sabe quais são, pergunte ao autor.

8. A hifenização.Linguagens de programação não são línguas naturais, e não observar o costume de hifenização convenções.Consultar o autor, se você precisa para hifenizar, ou simplesmente não.Palavras no texto do programa não deve nunca ser hifenizadas ou de linha quebrada, exceto de acordo com o autor instruções.

9. Maiúsculas e minúsculas.Caso em que o código do programa é geralmente significativo para o computador, e praticamente sempre a escritores e seus leitores.Pares de palavras são muitas vezes usadas, que diferem apenas no caso, representa coisas diferentes:exemplo:BufferedOutputStream e bufferedOutputStream.Programadores, especialmente autor-programadores, são geralmente altamente sistemática sobre caso, em formas que não necessariamente pode fazer sentido para o tipógrafo (ou outros programadores!).

Recomendações práticas

• Recuo em unidades.A solução para muitos dos problemas na composição de programas de computador é o em.O autor guias provavelmente será para o próximo múltiplo de 8 espaços (1 , 9 , 17, ...);tipográficas, as guias para o código do programa deve ser em múltiplos de 1 ou 2 ems.Adotando o em como a unidade de recuo à primeira 'engraçados' para o autor, como os recuos podem ser muito mais estreito do que o visto em telas ou impressões.No entanto, enquanto o alinhamento vertical da guia pára, está preservada, a intenção do autor é totalmente preservada.
• Quebras de linha deve ser conforme MS.
• Quebras de página:Se as quebras de página podem ocorrer no meio de um código de programa, o autor deve ser consultada a página preferida pontos de quebra.Normalmente, isso é para ser evitado em curto exemplos;em mais programas, o autor deve indicar todas as possíveis quebras de página no MS.
• Citações:Convencionalmente, a 'reta' aspas são usadas, não tipográficas cotações.Isto é historicamente determinado, mediante o uso de fontes sem aspas tipográficas (e.g.Courier, Helvética) na escrita de código de computador.Ele não é requerido pelas propriedades da notação.Eu não vejo nenhuma razão contra o uso de aspas tipográficas quando a configuração de programas de computador como enquanto aspas simples ficar aspas simples e duplas estadia duplo, i.é.enquanto o autor as aspas são preservados em vez de 'corrigida' padrão tipográfico prática.
• Numerais:Convencionalmente, forro romanos sempre foram usados no código do programa.Se você pode ser incomodado usando numerais em estilo antigo no código de programa, ou se o tipo de letra é construída dessa forma, eu posso ver nenhuma razão contra ele.Você deve escolher um tipo de letra em que 1, I, e l (minúscula L) são distintas, como também de 0 (zero) e O.