Comment formater le code source dans un document Framemaker? [fermé]

Question

Je dois rédiger un document technique dans Framemaker qui explique divers codes source de programmation.

Mon document consiste donc en un groupe de texte, suivi d'un groupe de code source (Java, XML), suivi de davantage de texte, etc.

Cette question ne concerne pas la question de savoir si je devrais ou non utiliser Framemaker - c’est le logiciel que je dois utiliser. . .

Ce qui me trouble, c'est comment formater le code source dans le cadre de mon document. Quelqu'un a-t-il fait cela pour un document technique et est-il tombé sur des instructions ou des conseils? Jusqu'à présent, ma recherche sur Google n'a rien produit qui corresponde à ce que je dois faire.

Answer 1

Créez au minimum un style de paragraphe pour les exemples de code, utilisez une bonne police à espacement fixe et n'oubliez pas de désactiver la césure.

Quand j’avais l'habitude de faire cela, je créais un style de tableau et y collais le code; j'avais donc un bel en-tête de titre au-dessus, et il se démarquait un peu. Le seul problème est que les cellules du tableau Frame ne se séparent pas d'un saut de page. Par conséquent, si votre code est plus long qu'une page ou menace de descendre sous le bas de la page, vous devrez créer plusieurs lignes dans votre tableau. séparez le code dans les lignes.

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.