Wie Source-Code in einem Framemaker-Dokument zu formatieren? [geschlossen]

Question

Ich muß ein technisches Dokument in Framemaker aufzuschreiben, die verschiedenen Programmier Quellcode erklärt.

Also mein Dokument von einem Bündel von Text besteht, gefolgt von einer Reihe von Quellcode (Java, XML) und dann um mehr Text gefolgt, usw.

Diese Frage ist nicht, ob ich soll oder nicht Framemaker verwenden soll - das ist die Software, die ich zu verwenden. . .

Was ich bin verwirrt ist, wie Quellcode als Teil meines Dokument zu formatieren. Hat jemand dies für ein technisches Dokument und kam über irgendwelche Anweisungen oder Hinweise getan? Bisher meine googeln nichts produziert hat relevant, was ich tun muss.

Answer 1

Am allerwenigsten, ein Absatzformat für Code-Beispiele erstellen, verwenden Sie eine gute proportionale Schrift, und nicht vergessen hyphenation auszuschalten.

Als ich dies tun verwendet, würde ich einen Tabellenstil erstellen und den Code dort einfügen, so dass ich hatte einen schönen Titel Header darüber, und es stand ein wenig aus. Die Gotcha nur dort ist, dass die Rahmentabellenzellen werden nicht über einen Seitenumbruch brechen, so dass, wenn Ihr Code länger als eine Seite oder droht unter dem Ende einer Seite zu gehen, werden Sie mehrere Zeilen in der Tabelle erstellen müssen und brechen Sie den Code über die Reihen auf.

Answer 2

Aus einem Papier, das ich vor einigen Jahren auf diesem geschrieben, die wieder Online nächste Woche verfügbar sein werden.

Typographen sind in erster Linie um die Lesbarkeit und haben Werkzeuge, Praktiken und Traditionen Hundert zurück und in der Tat Tausende von Jahren, für die Datierung zu verlassen, wenn Texte Einstellung in natürliche Sprachen. Allerdings sind Computerprogramme nicht in natürlichen Sprachen geschrieben. Sie Kunstsprachen, die ihre eigenen Regeln haben: in ‚Programmiersprachen‘ geschrieben Syntax, ihre eigenen Konventionen der Präsentation und ihre eigenen Kriterien der Lesbarkeit. Computer Code ist daher eine spezielle Domäne für den Satz, wie es Musik, Mathematik und Chemie. Diese Domänen haben ihre eigenen Regeln, die nicht die Regeln verwendet, wenn natürliche Einstellung Sprachen.

Computer-Programmierung selbst ist von sehr jungen Ursprungs, und die Praxis der es in Art Einstellung nicht zurück gehen, um mehr als etwa 45 Jahre: erhebliche Mengen an Computer-Code hat nur in den letzten 20 Jahren oder weniger veröffentlicht. Die zugehörige typographische Disziplin ist unreif oder in der Tat praktisch nicht existent, und die typographischen Erwartungen der Praktiker auf dem Gebiet sind ebenfalls niedrig, wie Sie durch Inspektion viele Handel Bücher zu sehen. Es gibt keinen Grund, warum Sie nicht versuchen können, es besser zu machen.

1. eine serifenlose Schrift verwenden. In einem meiner Bücher habe ich die gleiche Schriftfamilie, FF Scala für den Text und FF Scala Sans für den Code. Ich denke, es sieht gut aus, aber es gibt im Gegensatz Meinungen: diese zwingen Sie können eine proportionale Schrift zu verwenden, obwohl ich persönlich denke, diese sehr veraltet ist. Vermeiden Sie Courier, es nicht mit irgendetwas nicht mischen.

2. Die Einrückung ist Teil der Notation. Sie müssen die bestehenden linke Einzüge respektieren. Der Quellcode wird bereits mit Registerkarten werden. Reduzieren Sie die einzelnen Registerkarten, um einen oder zwei Räume höchstens, sonst werden Sie aus dem horizontalen Raum laufen.

3. Versuchen Sie, so viel vertikalen Raum wie möglich zu verlieren, z.B. unterdrücken leere lines.Try die gesamte Probe zu erhalten auf einer Seite. Lassen Sie es schwebt, wenn notwendig, das zu erreichen.

4. Die Zeilenumbrüche sind Teil der Notation. Fügen Sie keine Zeilenumbrüche, ohne den Verfasser zu konsultieren.

5. Die Anführungszeichen sind Teil der Notation. Nicht einzelne ändern oder umgekehrt zu verdoppeln.

6. Begründung:. Computerprogramme werden immer geschrieben, angezeigt und eingestellt linksbündig, rechts zerlumpte

7. Seitenumbrüche. Wenn Computer-Code in einem Buch Einstellung, Seitenumbrüche folgen können nicht nur den einfachen Waisen / Witwe Prinzipien verwendet, wenn natürliche Sprachen Schriftsatz. Stattdessen müssen die logischen ‚Blöcke‘ des Codes gehalten werden zusammen, wenn möglich. Es ist normalerweise nicht möglich, dass die Typograf die Blockgrenzen im Code, um zu bestimmen, obwohl eine Leerzeile im allgemeinen ein akzeptabler ist Punkt für einen Seitenumbruch. ‚Block Kommentare‘ sollten mit dem folgenden Code-Block gehalten werden. Wenn Sie nicht wissen, was diese sind, fragen Sie den Autor.

8. Hyphenation. Programmiersprachen sind nicht natürliche Sprachen und haben die üblichen hyphenation Konventionen nicht beobachten. Wenden Sie den Autor, wenn Sie die Silbentrennung müssen, oder einfach nicht. Worte im Programmtext dürfen niemals mit dem Autor Anweisungen.

außer in Übereinstimmung mit Bindestrich oder linien gebrochen sein

9. Groß- und Kleinschreibung. Case in Programmcode ist in der Regel signifikant auf den Computer, und praktisch immer an Autoren und ihre Leser. Wortpaare werden oft verwendet, die sich nur darin unterscheiden, falls, die verschiedene Dinge: z.B. BufferedOutputStream und BufferedOutputStream. Programmierer, vor allem Autor-Programmierer, sind in der Regel sehr systematisch über Fall in einer Weise, die nicht unbedingt sinnvoll, den Typograf (oder andere Programmierern!) machen können.

Praktische Empfehlungen

• Einrücken in em-Einheiten. Die Lösung für viele der Probleme in Computerprogrammen Schriftsetzen ist em. Die Registerkarten des Autors wird höchstwahrscheinlich auf das nächste Vielfache von 8 Räume (1, 9, 17, ...); typographischen Registerkarten für Programmcode sollte ein Vielfaches von 1 oder 2 EMS. Die Annahme der em als Einheit der Vertiefung kann zunächst ‚komisch aussehen‘ an den Autor, wie die Einschnitte sein können, viel schmaler als auf Bildschirmen oder Ausdrucke gesehen. Doch solange die vertikale Ausrichtung von Tabstopps beibehalten wird, ist die Intention des Autors voll erhalten.
• Zeilenumbrüche müssen pro MS sein.
• Seitenumbrüche: Wenn Seitenumbrüche in der Mitte des Programmcodes auftreten können, muss der Autor als auf bevorzugte Seite Bruchstellen zu Rate gezogen werden. Normalerweise ist dies vermieden werden insgesamt in kurzen Beispielen; Der Autor sollte alle möglichen Seitenumbrüche in den MS in mehr Programme an.
• Zitate: Konventionell ‚gerade‘ Anführungszeichen verwendet werden, nicht typografische Anführungszeichen. Dies ist historisch bedingt, durch die Verwendung von Schriften ohne typografische Anführungszeichen (zum Beispiel Courier, Helvetica) in typeset Computer-Code. Es wird nicht durch die Eigenschaften der Notation erforderlich. Ich sehe keinen Grund, gegen typografische Anführungszeichen, wenn der Computer Einstellung Programme solange Apostrophe einfache und doppelte Anführungszeichen bleiben doppelt, das heißt, solange der Autor des bleiben Zitate werden beibehalten und nicht auf Standard typographische Praxis ‚korrigiert‘.
• Ziffern: Herkömmlicherweise sind Auskleiden Ziffern immer in Programmcode verwendet. Wenn Sie im alten Stil Ziffern in Programmcode gestört werden können, oder wenn die Schrift auf diese Weise aufgebaut ist, kann ich keinen Grund, dagegen sehen. Sie müssen eine Schriftart, in der 1, I und l (Kleinbuchstaben L) verschieden sind, wie auch 0 (Null) und O wählen.