How to format source-code in a Framemaker document? [closed]

Question

I have to write up a technical document in Framemaker that explains various programming source-code.

So my document consists of a bunch of text, followed by a bunch of source code (Java, XML) and then followed by more text, etc.

This question is not about whether I should or should not use Framemaker - that is the software I have to use . . .

What I'm confused about is how to format source code as part of my document. Has anyone done this for a technical document and come across any instructions or tips? So far my Googling hasn't produced anything relevant to what I need to do.

Answer 1

At the very least, create a paragraph style for code samples, use a good monospaced font, and don't forget to turn off hyphenation.

When I used to do this, I would create a table style and paste the code in there, so I had a nice title header above it, and it stood out a bit. The only gotcha there is that Frame table cells won't break across a page break, so if your code is longer than a page or threatens to go below the bottom of a page, you'll need to create multiple rows in your table and break up the code across the rows.

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.