¿Cómo formatear el código fuente en un documento de Framemaker? [cerrado]

Question

Tengo que escribir un documento técnico en Framemaker que explique varios códigos fuente de programación.

Entonces, mi documento consta de un montón de texto, seguido de un montón de código fuente (Java, XML) y luego seguido de más texto, etc.

Esta pregunta no se refiere a si debo o no debo usar Framemaker, ese es el software que debo usar. . .

Estoy confundido acerca de cómo formatear el código fuente como parte de mi documento. ¿Alguien ha hecho esto por un documento técnico y ha encontrado alguna instrucción o consejo? Hasta ahora, mi Google no ha producido nada relevante para lo que necesito hacer.

Answer 1

Como mínimo, cree un estilo de párrafo para muestras de código, use una buena fuente monoespaciada y no olvide desactivar la separación de palabras.

Cuando solía hacer esto, creaba un estilo de tabla y pegaba el código allí, así que tenía un encabezado de título bonito encima y sobresalía un poco. El único inconveniente es que las celdas de la tabla Frame no se dividirán en un salto de página, por lo que si su código es más largo que una página o amenaza con ir debajo de la parte inferior de una página, deberá crear varias filas en su tabla y divida el código a través de las filas.

Answer 2

From a paper I wrote on this some years ago which will be available again online next week.

Typographers are primarily concerned with legibility, and have tools, practices, and traditions dating back hundreds and indeed thousands of years on which to rely when setting texts in natural languages. However, computer programs are not written in natural languages. They are written in ‘programming languages’: artificial languages, which have their own rules of syntax, their own conventions of presentation, and their own criteria of legibility. Computer code is therefore a special domain for typesetting, just as are music, mathematics, and chemistry. These domains have their own rules, which are not the rules used when setting natural languages.

Computer programming itself is of very recent origin, and the practice of setting it in type doesn’t go back more than about 45 years: significant volumes of computer code have only been published in the last 20 years or less. The associated typographical discipline is immature or indeed practically non-existent, and the typographical expectations of the practitioners in the field are also low, as you can see by inspecting many trade books. There's no reason why you can't try to do better.

1. Use a sans serif font. In one of my books I used the same font family, FF Scala for the text and FF Scala Sans for the code. I think it looks great but there are contrary opinions: these may force you to use a monospaced font, although personally I think this is very outdated. Avoid Courier, it doesn't blend with anything.

2. Indentation is part of the notation. You must respect the existing left indents. The source code will already be tabbed. Reduce each tab to one or two spaces at most, otherwise you will run out of horizontal room.

3. Try to lose as much vertical space as possible, e.g. suppress blank lines.Try to get the entire sample on to one page. Let it float if necessary to accomplish that.

4. Line breaks are part of the notation. Don't add line breaks without consulting the author.

5. Quotation marks are part of the notation. Don't change single to double or vice versa.

6. Justification: Computer programs are always written, viewed, and set left-justified, right-ragged.

7. Page breaks. When setting computer code in a book, page breaks can’t just follow the simple orphan/widow principles used when typesetting natural languages. Instead, the logical ‘blocks’ of the code must be kept together if possible. It is not usually possible for the typographer to determine the block boundaries in code, although a blank line is generally an acceptable point for a page break. ‘Block comments’ should be kept with the following block of code. If you don’t know what these are, ask the author.

8. Hyphenation. Programming languages are not natural languages and do not observe the usual hyphenation conventions. Consult the author if you need to hyphenate, or just don't. Words in program text must never be hyphenated or line-broken except in accordance with the author’s instructions.

9. Upper and lower case. Case in program code is usually significant to the computer, and practically always to writers and their readers. Pairs of words are often used which differ only in case, representing different things: e.g. BufferedOutputStream and bufferedOutputStream. Programmers, especially author-programmers, are usually highly systematic about case, in ways which may not necessarily make sense to the typographer (or other programmers!).

Practical recommendations

• Indent in em units. The solution to many of the issues in typesetting computer programs is the em. The author’s tabs will most likely be to the next multiple of 8 spaces (1 , 9 , 17, …); typographic tabs for program code should be in multiples of 1 or 2 ems. Adopting the em as the unit of indentation may at first ‘look funny’ to the author, as the indents may be much narrower than seen on screens or printouts. However, as long as the vertical alignment of tab stops is preserved, the author’s intention is fully preserved.
• Line breaks must be as per MS.
• Page breaks: If page breaks may occur in the middle of program code, the author must be consulted as to preferred page break points. Usually this is to be avoided altogether in short examples; in longer programs, the author should indicate all possible page breaks in the MS.
• Quotes: Conventionally, ‘straight’ quotes are used, not typographic quotes. This is historically determined, by the use of fonts without typographic quotes (e.g. Courier, Helvetica) in typeset computer code. It is not required by the properties of the notation. I see no reason against using typographic quotes when setting computer programs as long as single quotes stay single and double quotes stay double, i.e. as long as the author’s quotes are preserved rather than ‘corrected’ to standard typographic practice.
• Numerals: Conventionally, lining numerals have always been used in program code. If you can be bothered using old-style numerals in program code, or if the font is built that way, I can see no reason against it. You must choose a font in which 1, I, and l (lower-case L) are distinct, as also 0 (zero) and O.