Confidently Display Code Snippets in MS Word With These Set-Ups to Keep the Formatting
Working with code snippets
Imagine having to write a document in Word that is filled with text, bullets, visuals, graphs, and links. That’s already a handful to layout, isn’t it? Somewhere in the middle, you are required to show code changes that you’ve made on a project, and you have no idea where to start.
This can happen in a number of situations. In work settings when preparing a project report for a client or when submitting a test for a job application. Other examples are when submitting a paper for a study, and preparing a correspondence with mentors or friends. So technically you have a feeling that it can be done… but you’ve never done that.
If you've never had to copy and paste your code into a Microsoft document, then good for you. Hopefully you never have to, in which case all is well. But when you need to...
Bear in mind
Copy and paste does not guarantee you'll keep the code formatting as is!
The problem with good ol’ copy + paste
- No guarantee. Maybe it works for your first one to three lines of codes, but when you have to copy and paste 1,000 lines of codes and retain their formatting, then you might have a problem. Or not. In fact, there’s just no way to tell, unless you’ve been there.
- The characters are out of place. There has been reports that when you copy directly from a computer program and not a code editor, the semi-colons and the curly brackets end up being in the wrong places.
- Inconvenient editing. Okay, so you might have successfully copied and pasted a snippet of code in the middle of a page. Everything looks good. But when you begin editing regular text, your codes will move and become scrambled, getting in the way of your editing. It's going to be nearly impossible to edit any text at all if your code is pages long.
- Styling issues. You might need to present your code with a pink background. Or with line numbers, or in certain types of fonts, and with differing colors. These styling requirements are beyond the scope of a simple copy and paste technique.
1. Use a syntax highlighter
Many helpful tools are freely available online. The syntax highlighter is a tool that will display your codes in different colors and fonts, according to their categories. There are so many highlighters available, and you can even create your own in no time.
- Copy the code block from your computer program;
- Paste the snippet of code into Planet B input area;
- Choose a language from the drop down selector below the input box, and then click the "Show Highlighted" button;
- Copy the resulting code snippet and paste it into your doc;
- Style it. You can change the font type and size from the Word doc setting to make your code snippet look at home.
Note that when using this highlighter, the resulting code snippet will automatically have line numbers, and these you cannot get rid of. It's just a default output of the text editor feature. Although this may result in a very crowded code block, the syntax highlighter is a quick and easy option.
If you do a quick search on the web with "free online syntax highlighter" as your keywords, you will find many alternatives to Planet B. Here are a few available highlighters that I have tried my hands on:
By modifying existing Word styles, you can display your snippets of codes in a specific style.
2. Create a style and call it 'code'
In Word, there are built-in styles and themes already available for you to modify and customize according to your needs. You can change the formatting of the style, such as font size, color, indentation, fill color, and so on. The default code block style for Word that I use is set using Consolas, in a slightly smaller font size than the paragraph, with the shading set to fill with light grey, and in single spacing.
You can later modify this formatting depending on your taste. Instead of grey, you can fill the block with beige or sheer yellow, or your favorite color. Play around with what looks best to suit your paper.
Here is how you can create that style:
1. First, you must copy your block of code from the computer program and then paste it into your Word doc. The tricky part about copying and pasting a block of text from the Web is there will usually be some kind of highlighting on the text that won't go away after you paste it. What you do to clear the unwanted highlights from the pasted text is select the entire block of code and then click Ctrl + Spacebar. That would get rid of that.
Ctrl + Spacebar
Remove unwanted highlighting from copied texts by selecting the pasted code block, and then clicking Ctrl + Spacebar. Sometimes the highlight is white, making it barely noticeable.
2. Next, highlight that code snippet in the document and then right-click on the selection. You will find two dialog boxes open. Look for a "Styles" option and click on it.
3. The second step is to create a Style. After you select "Styles" from the dialog box, you will be presented with an option to "Create a Style". It is very important to know where to find the create a Style option, because this cannot be found anywhere else in the panels.
4. When you see the New Style formatting option, you will be able to change the name of the Style from the default "Style 1" to a new name. Because this style is going to apply for just your code snippets, let's name it "Code". Next, you're going to modify your newly created style.
5. After you click on the "Modify" button, you will be taken to the Modify Style dialog box and you'll start personalizing the formatting of your new style.
a. Start with selecting "Paragraph" as your Style type.
b. Choose "Normal" for the "Style based on" option.
c. Selecting a "Normal" for the "Style for following paragraph" will make sure that the next paragraph after your code snippet will not get all jumbled up.
6. The next thing you want to do is modify some other formatting elements of the style:
a. Choose a font. I usually use Consolas for codes, because they look flexible and easy on the eyes.
b. Select a font size. Most of the times I have my normal paragraph written in 12 pt size, so I would suggest a slightly smaller font for the code, maybe 11 pt or 10.5 pt.
c. Select a font color. You can select automatic color, but there are plenty of other options.
On this dialog box, you are presented with a preview of how your style would look like on the page. So before you apply the style, be sure to take a look at the preview box, and then click on the "Format" option.
7. From the Format option, select "Paragraph" and then go to the Spacing. Select "Single" for your Line spacing, and then click OK.
8. Again, from the Format option, select "Border". Once the Border dialog box opens, click on the "Shading" tab, and choose a fill color. You can select one of the theme colors, such as the light grey that I usually use as default. You can select any color you wish. Once you've got the right shading fill for your code selection, click OK.
9. Back in the Modify Style dialog box, select "Format" and navigate to the "Frame" section. This will open a Frame dialog box, where you will select "Around" as your text wrapping. Don't change anything else, and just click OK.
10. Finally, preview your Code style and make sure that everything looks great. Be wary of annoying additional highlighting that won't go away. This usually happens when you copy and paste texts from the web. If you encounter this, just select your code block and clear the font (see step 1). When you're happy with the way it looks, click OK.
3. Using Insert > Object > Open Document Text
The last method is using the Insert option. Although this is kind of like copy and paste, remember not to copy codes directly from your program. This is how to do it:
1. First, get your code ready. You need to paste your code into a code editor, and then copy the snippet to paste onto the document.
2. From the "Insert" tab on the top of your Word doc, select "Object". This will open a dialog window.
3. From the "Create New" tab, choose the OpenDocument Text option, and then click OK. This will open a new, blank document.
4. Copy your code snippet from the code editor and then paste it into the new blank Word doc. After you paste the entire block, save the file, and then close the document.
5. There you have it. Your code insertion is right where you want it in the document. You can now continue editing your paper and make the necessary adjustments.
Some issues to anticipate
1. Modifying the Normal style
If you've played around with styles, for your final paper for example, you know that it is quite easy to modify a style from the top-right panel. This is an option, but it is best not to modify the "Normal" style, because it is the basis for the rest of the styles.
Any changes to the Normal style could affect all the other styles. The Headings, Subtitle, Quote, etc. might also change. If you only make changes to the font size and color, you might not even realize that the rest of the Styles are also changing.
But when you add a filler to the shading, your entire document might turn grey!
2. Deleting a style
When you delete a style by selecting "Remove from style gallery", it doesn't really go away. Say you want to remove your Code style because it was not working properly and you want to redo it. You remove it from the gallery.
When you redo the process and name your style "Code", you will see this message:
To resolve this issue, simply go to the Style dialog box from the gallery and look for the style that you want removed.
3. Not using a code editor.
It's wise to invest on a code editor early on. There are many free or partially free code editors, such as Sublime Text 3, Atom, Notepad++, and the Code Writer from Microsoft app store.
This article is accurate and true to the best of the author’s knowledge. Content is for informational or entertainment purposes only and does not substitute for personal counsel or professional advice in business, financial, legal, or technical matters.
Questions & Answers
Does your "create a style" technique cure Words compulsion to replace double-quotes and apostrophe with right-and-left double and single quotes?
Interestingly, when you copy and paste your codes directly onto Words, some issues may become apparent. And you can't ignore them. For example, as far as Words is concerned, the apostrophe is practically identical to single quotes. Good old MS Words is not a code writer, so don't rely on it to sort out your code format or syntax. It's best to work with free code editors by pasting the source code first onto the code editor before copying it and then pasting it onto the code style you just created. You might encounter additional issues if you copy XML code, for example, and save it in a different language, such as HTML, without first converting your block of code. So be sure to do that first.
© 2018 Lovelli Fuad