Come formattare il codice sorgente in un documento di Framemaker? [chiuso]

Question

Devo scrivere un documento tecnico in Framemaker che spiega vari codici sorgente di programmazione.

Quindi il mio documento è costituito da un mucchio di testo, seguito da un mucchio di codice sorgente (Java, XML) e quindi seguito da altro testo, ecc.

Questa domanda non riguarda se dovrei o non dovrei usare Framemaker - questo è il software che devo usare. . .

Ciò di cui sono confuso è come formattare il codice sorgente come parte del mio documento. Qualcuno ha fatto questo per un documento tecnico e ha trovato istruzioni o suggerimenti? Finora il mio Google non ha prodotto nulla di rilevante per quello che devo fare.

Answer 1

Per lo meno, crea uno stile di paragrafo per esempi di codice, usa un buon carattere a spaziatura fissa e non dimenticare di disattivare la sillabazione.

Quando facevo questo, creavo uno stile di tabella e incollavo il codice lì dentro, quindi avevo una bella intestazione del titolo sopra di esso, e si distingueva un po '. L'unico problema è che le celle della tabella Frame non si romperanno in un'interruzione di pagina, quindi se il tuo codice è più lungo di una pagina o minaccia di andare sotto la parte inferiore di una pagina, dovrai creare più righe nella tabella e suddividere il codice tra le righe.

Answer 2

Da un articolo che ho scritto alcuni anni fa, che sarà di nuovo disponibile online la prossima settimana.

I tipografi si occupano principalmente di leggibilità e dispongono di strumenti, pratiche e tradizioni risalenti a centinaia e addirittura migliaia di anni su cui fare affidamento quando si inseriscono i testi lingue naturali. Tuttavia, i programmi per computer non sono scritti in lingue naturali. Essi sono scritti in & # 8216; linguaggi di programmazione & # 8217 ;: linguaggi artificiali, che hanno le loro regole di sintassi, le proprie convenzioni di presentazione e i propri criteri di leggibilità. Computer il codice è quindi un dominio speciale per la composizione, così come la musica, la matematica e la chimica. Questi domini hanno le loro regole, che non sono le regole utilizzate quando si imposta naturale lingue.

La stessa programmazione informatica ha origini molto recenti e il la pratica di impostarlo nel tipo non risale a più di circa 45 anni: volumi significativi di il codice del computer è stato pubblicato negli ultimi 20 anni o meno. Il tipografico associato la disciplina è immatura o praticamente praticamente inesistente e tipografica anche le aspettative dei praticanti sul campo sono basse, come si può vedere ispezionando molti libri di commercio. Non c'è motivo per cui non puoi provare a fare di meglio.

1. Usa un carattere sans serif. In uno dei miei libri ho usato la stessa famiglia di caratteri, FF Scala per il testo e FF Scala Sans per il codice. Penso che sia fantastico, ma ci sono opinioni contrarie: potrebbero costringerti a usare un carattere a spaziatura fissa, anche se personalmente penso che questo sia molto obsoleto. Evita Courier, non si fonde con nulla.

2. Il rientro fa parte della notazione. È necessario rispettare i rientri di sinistra esistenti. Il codice sorgente sarà già a schede. Riduci al massimo ogni scheda a uno o due spazi, altrimenti rimarrai senza spazio orizzontale.

3. Cerca di perdere più spazio verticale possibile, ad es. sopprimere le righe vuote. Prova a ottenere l'intero campione su una pagina. Lascialo fluttuare se necessario per farlo.

4. Le interruzioni di riga fanno parte della notazione. Non aggiungere interruzioni di riga senza consultare l'autore.

5. Le virgolette fanno parte della notazione. Non cambiare da singolo a doppio o viceversa.

6. Motivazione: I programmi per computer sono sempre scritti, visualizzati e impostati giustificati a sinistra, sfilacciati a destra.

7. Interruzioni di pagina. Quando si imposta il codice del computer in un libro, le interruzioni di pagina non possono semplicemente seguire i semplici principi orfani / vedove utilizzati per la composizione delle lingue naturali. Invece, il logico & # 8216; blocca & # 8217; del codice deve essere tenuto insieme, se possibile. Di solito non è possibile per il tipografo per determinare i limiti di blocco nel codice, sebbene una riga vuota sia generalmente accettabile punto per un'interruzione di pagina. & # 8216; Blocca commenti & # 8217; dovrebbe essere mantenuto con il seguente blocco di codice. Se non sai cosa sono, chiedi all'autore.

8. sillabazione. I linguaggi di programmazione non sono linguaggi naturali e non osservano le consuete convenzioni di sillabazione. Consultare l'autore se è necessario sillabare o semplicemente non farlo. Le parole nel testo del programma non devono mai essere sillabate o interrotte di riga se non in conformità con le istruzioni dell'autore.

9. Maiuscole e minuscole. Il caso nel codice del programma è di solito significativo per il computer e praticamente sempre per gli scrittori e i loro lettori. Si usano spesso coppie di parole che differiscono solo nel caso, che rappresentano cose diverse: ad es. BufferedOutputStream e bufferedOutputStream. I programmatori, in particolare gli autori-programmatori, sono di solito molto sistematici caso, in modi che potrebbero non avere senso per il tipografo (o altri programmatori!).

Consigli pratici

• Rientro in unità em. La soluzione a molti dei problemi nella composizione di programmi per computer è quella. Le schede dell'autore molto probabilmente saranno al prossimo multiplo di 8 spazi (1, 9, 17, & # 8230;); le schede tipografiche per il codice del programma devono essere in multipli di 1 o 2 ems. Adottarli come unità di rientro può inizialmente sembrare & # 8216; divertente # & # 8217; per l'autore, poiché i trattini potrebbero essere molto più stretti di quelli visualizzati su schermi o stampe. Tuttavia, fintanto che l'allineamento verticale dei punti di tabulazione è conservato, l'intenzione dell'autore è pienamente preservata.
• Le interruzioni di riga devono essere conformi a MS.
• Interruzioni di pagina: se possono verificarsi interruzioni di pagina nel mezzo del codice del programma, è necessario consultare l'autore in merito ai punti di interruzione di pagina preferiti. Di solito questo deve essere evitato del tutto in brevi esempi; nei programmi più lunghi, l'autore dovrebbe indicare tutte le possibili interruzioni di pagina nella SM.
• Citazioni: convenzionalmente, & # 8216; straight & # 8217; vengono utilizzate le virgolette, non le virgolette tipografiche. Ciò è storicamente determinato dall'uso di caratteri senza virgolette tipografiche (ad esempio Courier, Helvetica) nel codice del computer composto. Non è richiesto dalle proprietà della notazione. Non vedo alcun motivo per non usare virgolette tipografiche quando si impostano programmi per computer come fintanto che le virgolette singole rimangono singole e le virgolette doppie rimangono doppie, vale a dire fino a quando l'autore le virgolette vengono conservate anziché & # 8216; corrette & # 8217; alla pratica tipografica standard.
• Numeri: in genere, i numeri di rivestimento sono sempre stati utilizzati nel codice del programma. Se puoi essere infastidito usando numeri vecchio stile nel codice del programma, o se il carattere è costruito in quel modo, non vedo alcun motivo per farlo. Devi scegliere un carattere in cui 1, I e l (L minuscola) sono distinti, come anche 0 (zero) e O.