I authored a scientific paper containing code and recently received the proofs, i.e., what the journal’s typesetters created from my manuscript.
The result was not acceptable: The indenting is inconsistent; there is a full stop at the end of each code block; quotation marks have been destroyed, etc.
Note that all the errors were not specific to the programming language I used.
Now, I can see why somebody who has no programming experience and no external resources would make such mistakes, but in times of the Internet nobody should not be without external resources.
Thus, I consulted my favourite search engine to search for something to suggest and found … nothing.
There are a lot of guides for programmers how to beautifully typeset code in LaTeX or similar, which is all nice and proper, but this obviously not made for the typesetter who has to typeset somebody else’s code.
I am looking for a resource that:
- explains the basics of typesetting code,
- is targetted at typesetters without programming experience.
Maybe the real point is that code should not really be typeset the way people understand typesetting. So when putting code into a document it should be put there verbatim, as in all spaces, tabs, special or not special characters and line breaks intact.
- Tabs should be as wide as 4 or 8 spaces (four being the most common)
- Font should be a fixed width font. And almost universally has to be.
Make sure your application does not do any substitutions!
That means no ligatures.
Also many programs (like Word and InDesign) application change straight quotes to typographers pairs. Make sure such options are disabled before you put the code into your document.
- Do not let code automatically flow from one line to another. Do not touch the code, you are not the expert!
Code is not body text, it does not follow any typographic conventions. Ask yourself would you typeset text in a illustration?
If you are an expert
If you are an expert and you know the language in question then following applies.
Note: Do not guess or infer, read what was said. Lots of languages look the same and the code may be some pseudo language that looks like real code. Then you can:
Do editor like coloring/bolding/italizing of keywords if and only if your substitution has same fixed width. Best let a editor do this for you (editors like say scintilla can export the formatted code). Remember that the editor needs to know the language, maybe libraries also.
Note if you do this wrong it causes more harm than good.
If you are a domain expert. As in know the language and library and understand the code in question:
Then you can realign the code into several lines if it does not fit your layout. Do not do this unless you really know what your doing, you may end up doing irreparable harm.
The litmus test is could you have written the code in question. If not then you can not judge. Ask the author.
How to deal with this? Programmers understand code style standards. Just write in the submission guideline that you can only fit X characters per line. Programmers can then do this themselves. Code editors frequently have tools for this. Yet another reason to use a mono spaced font.
But then you knew all of this, you were an expert after all. Better let the author edit the code.
Some programming languages and use cases may benefit from line numbers. Be careful here though, since this is a faux pas in some languages.
Be aware that no matter what you do you may in fact be up against impossible technical hurdles. Code should not really be typeset it should just be unformatted text. This leads to surprising problems.
For example: Languages like Python can not be handled by many PDF viewers, like Adobe Acrobat. If you paste the code out of the PDF file the editor decides not to include the preceding space when copy pasting. This destroys the ability to paste code from PDF to editor. There is really no good way to handle this!