13

Background

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.

Question

I am looking for a resource that:

  • explains the basics of typesetting code,
  • is targetted at typesetters without programming experience.
  • The difficulty with this is that it depends on language and conventions used, so the question is pretty broad, even if answers are just linking a resource – Zach Saucier Apr 1 '18 at 2:47
  • 2
    @Scott Well, regarding quotes, spaces, characters -- indeed one can generalize pretty well: they must be preserved. – Mikhail V Apr 2 '18 at 2:40
  • 1
    @MikhailV I merely feel that many code languages have more in common with foreign languages than merely guidelines. Sure you can roughly determine where spaces and line-feeds should be placed, But to be accurate, you really need to understand the language you are proofreading. Yes you can tell editors/proofreaders to leave "as is" that doesn't mean it will ultimately be correct though. – Scott Apr 2 '18 at 3:56
  • 1
    @Wrzlprmft Funny thing, one can not copy paste python form PDF without loosing all the preceding whitespace in acrobat or acrobat reader. It "intelligently" removes them. Likewise if you paste code into many WYSIWYG editors like word or INdesign they will replace quotes with typographers quotes (unless you disable such a feature), but for code that is indeed BAD. Also in idesign you can not really typeset code properly without introducing a different character for line breaking, which may well become a bad thing if you ever copy the code back. – joojaa Apr 2 '18 at 9:52
  • 1
    @usr2564301: First of all, this question is now being found by some search engines and so it is more likely that any typesetter having the same problems as mine can find a potential answer (and if they don’t, I could be properly smug about it). Second, yes, I would include a link in the response to my proofs, because it can prevent not-yet-committed errors in the second round of proofs. It also doesn’t hurt to have a reference if the typesetter is stubborn. Finally, this is a journal/publisher that rarely has to deal with code, so it’s somewhat different from the scenarios you depict. – Wrzlprmft Apr 2 '18 at 11:04
7

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.

Line numbers?

Some programming languages and use cases may benefit from line numbers. Be careful here though, since this is a faux pas in some languages.

Problems.

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!

  • @usr2564301 ah yes so true – joojaa Apr 2 '18 at 12:51
  • 1
    @usr2564301 Done, anyway i think that a readable font choice is something a typographer should understand. Anyway one that also distinguishes a lower case i without dot (yeah we debugged one piece fo code for a month because we didn't know that a lowercase 'i' is different form a uppercase 'I' in a Turkish locale) form a 1 too – joojaa Apr 2 '18 at 12:52
  • “Do not let code flow from one line to another” is good advice in theory. But if you’re typesetting for a standard 6x9 print format and you’ve got a line of code with 600 characters, you’ll be hard pressed to heed it. – Janus Bahs Jacquet Apr 2 '18 at 23:17
  • 1
    @JanusBahsJacquet Code is usually written at less than 80 characters per line. So if you get something like that then maybe your submission guidelines suck. Programmers know about submission guidelines, after all thats what codebases are. Thing is by breaking lines you may end changing the meaning of the code. – joojaa Apr 3 '18 at 4:33
  • 1
    @JanusBahsJacquet Thats why you ask the author, you update the guidelines so you dont need to do that too often. well in either case if the code cant be split form long lines then the typesetter cant do anything about it either. By the way what would a typesetter do to a too wide picture that can not resized or cropped? Anyway i will predict code submissions will be more common in the future – joojaa Apr 4 '18 at 17:30
4

The answer of course may depend on many factors, but if we start with correct, good formatted plain text code, then one can more or less generalize things here.

The initial ‘formatting’ in the source text will be: newline, space and tab characters. Note that the new line and manual line break (as in DTP software) are not the same thing, and vice-versa, some rare languages may allow other formatting characters, although I've never heard of such.

Comments are not executable part of code, so those may be reformatted without much risk, if one knows if it is really a comment. So first thing to look at is how comments are tagged.

Some basics about initial plaintext formatting is good to know. E.g., for Python, there is the PEP8 style guide. While made for Python, this formatting guide can be used as a reference for major languages such as C/C++ and Java. Looking into various example projects can help when in doubt.

Thus, the first principle would be: Don’t change the source text. I would go through a checklist - make sure that:

  • No character autoreplacing occurs on any stage.
  • No edits to the text are made (unless you are 100% sure they must be done).
  • No line wraps appear.
  • Indentations are preserved visually and are consistent (ca. four x widths per level of indentation).
  • The initial (zero) indent level should be visible.
  • Defined styles do not destroy the formatting of syntax (if syntax highlighting is used).
  • Have a backup of the source in plain text, so as to be able to recheck the original formatting or start anew.
  • Line numbers, if present, should be intact especially if they are referenced in explanations.

Actually if the original source is properly formatted, there should be no line wrapping at all. If wrapped lines still appear and are unavoidable, then a one-level hanging indent is most common solution (see above linked PEP). If line breaking is necessary – better consult the style guide or the author.

Still some minor ‘white space’ characters may require replacement. Since the source can include tab characters, this means of course that the typesetter must ensure that all tabs in the beginning of each line are consistent, i.e. nested indentations are preserved visually and every next level of indentation is of same width (ca. four x widths per one level of indentation).

Ideally, the indentations which were made with space characters or mixed spaces and tabs should be replaced with tabulation (or with what the DTP software can do better for nested indentations), so, if needed, adjusting the indentations may be easier.
Of course one may leave spaces, but it may be harder to manage their width when changing the font and harder to align inner-line indentations like in table columns.

Monospaced font + spaces

Note that if the source is formatted with spaces intentionally and was intended to be read in monospaced font only, (for example ASCII-diagrams or ASCII-art) one should preserve the spaces totally unchanged, but this decision should be made from the beginning. "Courier New" font is most common for this case. Still if not really needed, I advise against monospaced, because less and less new people choose monospaced for coding today, and in case of proofreading, proportional fonts will give better reading experience.

In general, condensed (e.g. Arial narrow) or smaller fonts may work better: it gives more emphasis in contrast to body text, it will make code more compact, and thus less probable that unwanted line wrapping will appear.

I think here one can draw a line, and if the above is done, then there is 99% probability that everything should be fine, at least for a plain single-font code block without colors.


Tools and advanced formatting

Further, the look can be significantly improved by using syntax highlighting.

  • color print or screen viewing: in a full-color layout every feature of highlighting can be used, so it is the best-case scenario, but printing may give some color changes.

  • grayscale or b/w print: here of course one can use bold (e.g. keywords) or italics (e.g. comments) but note that colors will be converted to gray with all consequences. For example grayed-out comments may look great on a display, but can become too pale on paper.

The most important question is, whether the layout maker have tools that can represent the code in a readable form. Fortunately, there are a lot of free tools for code editing, most prominent (for Windows) are: Notepad++, VSCode, Visual Studio. But be aware of possible implicit auto-convertions of tabs to spaces though.

In Notepad++ there is an option to export the code as RTF, which will preserve all formatting and syntax highlighting of the source.

If the layout does not require change of the text flow in code presentation, one may directly use images (screenshots) – it is not so flexible as text, but will preserve 100% formatting and line numbering, and can save a lot of time. E.g. line numbers can be tricky to preserve in text form. Also exporting to PDF is a good alternative – but not all DTP software can embed PDFs and some formatting can be lost when printing to PDF.

For example, my setup for Python code in Notepad++ look like this:
enter image description here

This is just to illustrate, that one can directly use screenshots and that may actually be the easiest method. There are various tools that can help with screen capturing – one may need ‘stitching’ the screens for higher resolution images.

The color scheme is of course upon individual, defined in the style configurator of the editor, which is already aware of the supported language, thus making it hard to make false formatting even if one doesn’t know the syntax. Here general typography rules should work: not too many colors, consistent fonts, indentations, comfortable line spacing.

Additional tools/plugins for custom language definitions are also common, but those require syntax knowledge.

  • This is a wonderful and carefully-thought out response. But screenshots can be sub-optimal if you're planning to have this printed, because of the resolution. Something to keep in mind. – Jeremy Carlson Apr 4 '18 at 15:11
  • 1
    @JeremyCarlson in Np++ the font size/line spacing can be adjusted as well - so in theory there is no limit for screenshot resolution, but it will be harder to create, especially on a small display. There may be even some trick to use virtual display and setting very big window size – Mikhail V Apr 4 '18 at 15:29
  • because less and less new people choose monospaced for coding today – This may be, but monospaced is still the used by the vast majority. You cannot just translate normal typesetting conventions to code. For example punctuation marks are more important than in normal texts (most arguments from this answer of mine translate to this). A non-monospace code typeface will differ considerably differ from one for regular text. Also, you often want certain similar structures to be horizontally aligned, e.g. a[i][j] = 1a[m][n] = 2. – Wrzlprmft Apr 8 '18 at 19:26
  • @Wrzlprmft thanks for the edits. And yes, there are not so many good fonts optimized for code&math (Verdana is ok). Indeed, Times has tiny period and colon and some other issues, but I use it all the way - 'the benefits outweigh the costs' – Mikhail V Apr 9 '18 at 0:14
-5

In HTML, there is a tagset <code>...</code> that tells the reader/interpreter to treat the content absolutely literally. also, <pre>...</pre> does much the same. As someone who often had to typeset formulas, equations, and code for publication, I also advocate the use of IMAGES to do this...make a .gif or .jpg or .png of the problematic item.

Another factor is that code is traditionally rendered in Courier monospace, or other monospaced font, because it semaphores or telegraphs to the reader that it is not body text. I subscribe to this style choice, I think it makes a lot of sense.

In most "legacy" typesetting systems, math equations of reasonably high complexity were excruciatingly time-consuming...and fraught with error.

  • of course, images are not cut 'n paste-able! – dwoz Apr 1 '18 at 22:21
  • 3
    I don't understand how this answers the question being asked at all – Zach Saucier Apr 2 '18 at 4:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.