7

I have a couple of code snippets, included in my thesis. What is the most convenient way to format code in a Word document, particularly, in regard to keeping the syntax highlighting, etc.? And the guidelines say that text should use double space. Does this apply to the embedded code as well?

  • 1
    Whatever you do, don't do it by hand. Use an automated tool. Doing things by hand makes you lazy: when you have to change something in the code, you'll be too lazy to reformat and retest it properly, and this will lead to errors. – Federico Poloni Aug 20 '15 at 7:53
  • Why are you using Word for writing your thesis? I'd suggest using TeX, which would make it much more comfortable for you. – Eenoku Aug 20 '15 at 9:23
  • Using Latex avoids lots of cumbersome elements while compiling large scripts and documents, however, it requires some familiarity with its packages, It worths the learning curve though thus I am planning to familiarise myself for the next one. – KonVas Aug 21 '15 at 15:16
4

You should create a paragraph style with the appropriate settings—a monospaced font for one thing, probably some indentation—and use that.

When using Microsoft Word you should resist the temptation to change any properties of the font at all manually. (Ideally remove the font bar from the ribbon altogether.) Instead you should create paragraph and character styles and apply them as you go along. Then they can easily be edited globally later.

If you really need syntax highlighting, the "best" way would probably be to write a macro that tagged the different parts of the code with a different character style for each code element, and then adjust the colours in the character style editor later. Then run the macro on each code block. I suspect such a macro probably exists somewhere.

The "quick" way would be to copy and paste from another program where the text is already coloured.

  • I'd go for copy/paste from something that does syntax highlighting, then tidying up and applying the right paragraph style. If the snippets are to be in-line with text, rather than in (say) an appendix, then consider whether you want full-on coloured syntax highlighting or whether that would stand out too much compared to the rest of the document. Bold highlighting may be a halfway house, if the highlighting is important, as might greyscales (though be careful with readability). – Flyto Aug 19 '15 at 14:17
3

The most common formatting I have seen is to use Courier (or Courier New) as font, and put keywords (such as int etc.) in bold. I am pretty sure the line spacing does not apply to embedded code (in this sense, the code can be similar to a figure, where you usually would not use double spacing as well).

This is however something you can and should discuss with your administration, who might be able to give you the exact layout and formatting requirements. You can also you older theses as a baseline for these requirements.

  • 1
    In some situations the code may also benefit with from numbers (for example, if you want to refer to a particular line in the code). That may be tricky to automate in MS Word though (I do not want to suggest to paste a piece of code and add line numbers manually, and then repeat this procedure again after you've modified it!) – Alexander Konovalov Aug 19 '15 at 23:04
  • _ put keywords (such as int etc.) in bold_ — Oh please no. Nicklaus Wirth should have his Turing award revoked for starting that execrable typographical practice. Why on earth would you want to emphasize the syntactic sugar? – JeffE Aug 21 '15 at 15:35
  • @JeffE: agree with you. Using or not the syntax highlight is a matter of taste, and it may be not a good idea to impose it on the reader. OTOH, if the author will make the code also available electronically, then those who wish to study it in more details will have an option to open it with their preferred editor (possibly with syntax highlight, folding and many other nice features). – Alexander Konovalov Aug 24 '15 at 8:54
  • @JeffE: What do you suggest as an alternative? – mdd Aug 24 '15 at 14:27
  • @MatthiasDiener Don't put the keywords in bold. – JeffE Aug 24 '15 at 14:33
3

If you're writing a document of any real size in Microsoft Word, your goal should be to typeset your document, or to have a set of predefined formatting rules for the whole thing. To enable this, you should never, ever set the look and feel of your text via the individual formatting options in the Home ribbon. It becomes really difficult and time consuming to tweak a small detail of a formatting style later if you do.

Microsoft Word has a hidden goldmine -- the Styles panel. Learn it and you'll discover a whole new world of simple productivity. In Word, in the Home ribbon, under the Styles section, you'll find a small "more" button (highlighted): A screenshot of the Microsoft Word ribbon, with the Styles menu opening button highlighted.

When you click the button, you'll get the Styles panel: A screenshot of the Microsoft Word Styles panel.

This is where all of your text formatting needs should live. Two main types of styles exist: paragraph and text. The majority of your styling should be paragraph styles, which means you set formatting for an entire paragraph block (there will be a little paragraph symbol next to these), while the other just changes the look of the text (there will be a little "a" character next to these).

In order to see all of the existing styles, you can click on the Options button at the bottom of the Style panel, and change the settings as follows: A screenshot of the Style panel Options menu.

This will show you all of the styles. I recommend generally leaving to show Recommended, or once you learn which styles you like best, to leave it on In Current Document (it'll be a much shorter list and keep your document cleaner).

For code styling specifically, the HTML Preformatted paragraph style works really well. Before: A screenshot of Lorem Ipsum text with an unformatted code block.

vs after (with Styles panel filtered to "In Current Document"): A screenshot of Lorem Ipsum text with a formatted code block.

If you don't like something about the way the styled block looks, it's a simple effort to right-click on the style in the Style panel and use the style settings to tweak it how you'd like. This then updates every piece of text in your document that has the same formatting style applied (this is something you want, see typesetting above).

If you don't find a style you like, you can also create your own (the new style button at the bottom of the Style panel). If you get a set of styles set up that you like, you can export them or save them (Styles panel > Manage Styles button > Import/Export, then store the new styles in your default Normal.dotm, or save your styled document as a new dotm that you can import styles from).

If you continue to do academic writing or have reports or things to write for your job eventually, remembering this will make you a superhero of Word productivity (and help you make your documents look incredibly clean and polished).

2

A couple of points. Firstly, I would suggest you to carefully consider whether you indeed want to retain syntax highlighting in a source code, embedded into a thesis document. While using some color styling is acceptable and, even, recommended (unless it is explicitly prohibited by your thesis/dissertation guide for certain elements or at all), overusing it can be damaging to the impression of your committee members due to potential issues of readability and accessibility.

Secondly, if you would want and be able to generate your thesis Word document from a LaTeX one (I do not recommend it, as it can be quite tricky, unless you have experience in that), then source code formatting transforms into a pretty trivial task, thanks to corresponding LaTeX packages and excellent free and open source pandoc software. Markdown (in combination with pandoc) can also be a feasible alternative to LaTeX, if your thesis is light on mathematics and your formatting needs are relatively modest. There are many detailed guides on the above-mentioned approaches, but, even ignoring some complexities (and, potentially, steep learning curve) reported results are mixed.

Thirdly, to find the optimal Word-only solution, try to review first several pages of more then 3M results of Google search source code highlight word document. I am pretty sure there are some decent methods out there. If you want a simplistic approach, consider using a monospaced font. Some other simple solutions can be found in answers to this popular question on StackOverflow.

  • 1
    Personally, I'd want syntax highlighting in every situation where I read code. – Federico Poloni Aug 20 '15 at 7:51
  • @FedericoPoloni: I certainly understand you. However, it all depends on personal preferences and/or context (i.e., there is a significant difference in context between reading some code snippets in a tutorial on screen and looking at code, embedded into a mostly black and white academic document, such as a thesis). – Aleksandr Blekh Aug 20 '15 at 9:16
1

I think this is going to depend on the purpose. You should ask your thesis advisor(s) / department chairs. I needed to include some code snippets in my thesis. I was told by my chair members to post the code on Github and obtaining a DOI number associated with it.

Take a look at these two links: https://guides.github.com/activities/citable-code/ and http://figshare.org/ as they might help you in your process.

If you must include the code in the body of the thesis, instead of as a citation or link in the appendix, take a look at this stackoverflow response, as it seems like it would serve perfectly: https://stackoverflow.com/a/2653406/4885396

0

The best solution I found, (that works nicely for me) is coding in the languages' IDE which applies the highlight according to the languages' style. Then, I copy and paste in an embedded object (word document) in Word editor. The nice thing about that is Word treats it as a figure so I can place a caption, and Word won't try to spell-check. This is the link I got the solution that worked for me.

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.