4

My question is not concerned with the output, but the readability of the input.

I am looking for advice for making text-heavy latex code more readable. I know there are already topics on making code more readable, and I get that I should indent, etc. But I still find that when I am writing text-heavy latex code it ends up not as readable as I would like.

I think my issue is that, let's say there are 5 paragraphs, each 4 or so (full) lines each, and with a bit of math mode in-between ($c=0$, $x \leq y$ etc). Then you have ~20 lines, with only 4 lines separating them. The lines may also be of different lengths depending on where you break them.

I am asking how people make these more readable. All I can think of is perhaps using comment lines (%) to add more space, but then there is % signs everywhere. Or perhaps aiming to break every line at about the same length, but I find this difficult unless I constantly break mid-sentence. Also, regarding breaking text lines, where do people tend to break them? Because I often have to break them mid-sentence...

Any chance part of the issue is the fact that my code is in a window the size of half my 13-inch screen? (so it is somewhat compressed)? Resolution is standard, though (hd). That is, perhaps it is suggested to work in full-screen mode?

  • 2
    Every sentence in the input file I start on a new line. If a sentence gets too long and I choose to break it into 2 or more lines of input, I indent all subsequent lines of the sentence by a few characters. – Steven B. Segletes Jan 19 '16 at 0:51
  • 1
    I aim to break at the end of each sentence, although some of my older files have continuous paragraphs. But this is mostly for version control. I find that the font, font size, font colouring and background colour are crucial for readability. – cfr Jan 19 '16 at 1:03
  • 4
    why is breaking mid sentence an issue? sentences normally break in the output and people read without problem, normally I set the editor to break lines automatically around column 75 or so. – David Carlisle Jan 19 '16 at 9:04
  • 2
    @majmun sorry I honestly can not guess what you mean by blank space on the screen. perhaps it's an issue with your editor? If writing mostly text the source should be as readable as a plain text document, or an email etc there don't appear to be any special issues you can use either a space or a newline between words as seems fit, some people avoid newlines and let their editor wrap the long lines, some (myself included) prefer to have real linebreaks but it looks more or less the same in the editor, but difference mostly if you cut and paste eg to this site, when short lines avoid scrollbars. – David Carlisle Jan 19 '16 at 21:18
  • 1
    Interesting: dustycloud.org/blog/… --- I also asked about it at vi.stackexchange.com/q/6004/854 .... – Rmano Jan 21 '16 at 22:11
3

As mentioned in some of the comments, the text editor you use and its configuration are crucial in making text readable or alienating. The stuff you can act on:

  1. Font. In my opinion, fixed-width fonts give the best results because the letters are evenly spaced across all lines, which makes it easier on the eyes (there is some kind of vertical symmetry), and also because it doesn't cram letters together. By comparison, with a “regular” font, especially sans (Arial, Helvetica, etc.), thin letters have a tendency to make things difficult to read. Some such fonds have ridiculously narrow letter-spacing for l or i which is practically unreadable on-screen (don't forget that print font were created… for print). I always use Latin Modern Mono.

  2. Line height. If you can set it on your editor, you should pick a spacing factor higher than one. For displayed text, I usually favour something around 1.1 or a bit higher. Again, this depends on the font: some fonts have a large x-height which calls for greater line-spacing. If you compare, say, Arial 12pt and Garamond 12pt, the former looks larger because the short letters are bigger relative to the font size.

  3. Line length. Most editors allow you either wrap or break lines at an arbitrary number of characters such as 80 (standard) or 65 (optimal readability, used in books).

  4. Main colours. Set the background colour to something non-white and the text colour to something non-black (on in reverse). The Solarized palette is a good implementation of this principle.

  5. Secondary colours. Set your editor to automatically put certain characters in a specific colour (green, red, blue, whatever). Use is for the obvious syntax colouring, but also for colouring stuff inside macros (e.g. my footnotes display in grey and my citations in maroon). If you set it properly, it can also colour stuff like punctuation in order to make the grammatical structure of the sentence more obvious without having to manually break lines. You shouldn't be using too many colours, but you can do a huge lot of things with just 4-5 of them. Again, Solarized may be your friend here.

  6. Styling. Similarly, you can program your editor to put those elements in italics or bold automatically for you.

  7. Distraction-free. Use distraction free mode (a.k.a. full-screen). Text feels more legible when you are just looking at the text without having other stuff on screen. Split-screen with text on the one hand and output on the other also works (at least for me).

  • This is pretty helpful, thanks. I have been doing full screen and it helps (although I guess there are apps that supposedly help create better distraction free modes now, but perhaps not with/for latex-editors). I've also done $(2), (3),$ and $(5)$. I had not though of $(4)$, but I've seen it done in other applications and it makes sense, so I will try it. It just hadn't occurred to me. I would never have considered font-spacing though, and I think that will make quite the difference, at least for me. – majmun May 2 '16 at 3:02

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.