I have made modifications to a few files of a C++ program. I would like to document on these changes in a nice LaTeX report, by showing exactly what I modified and explaining why I did so.

Since there are quite a lot of lines of code that have changed, it is not really an option to go through all of them manually, copy and paste relevant bits and add commentary.

My questions are:

  • How would you go about making such a document, preferably with colors or some markup to clearly show differences?
  • Would you show the code versions side by side, or rather show a kind of diff log?
  • Where would you add commentary?

I am thinking of using the terminal git diff color output as a basis, somehow getting LaTeX to typeset this and adding in my comments.

  • 1
    Welcome to TeX.SX! You can have a look on our our starter page to familiarize yourself further with our format. – Claudio Fiandrino Jun 22 '13 at 14:53
  • 17
    No time for a full answer now: Let git diff produce unified diffs (with +,- line prefixes); use the listings package to typset the diff, defining + and - as special line comment chars to typset them in e.g. different colors. – Daniel Jun 22 '13 at 15:17
  • 5
    See also Highlighting a .diff file – JLDiaz Jun 24 '13 at 9:03
  • 3
    You could use latexdiff, possibly with the CFONT option, to generate a latex file that highlights the changes. You could then splice this into your document and add comments. – Andrew May 29 '14 at 0:01

I agree with @hraish-kumar's suggestion to embed comments in the code. But if you want to compare branches or commits in a git repository, you might want to check this answer to how to use latexdiff with git.

  • Welcome to TeX.SX! You can have a look at our starter guide to familiarize yourself further with our format. Your answer might be better suited as a comment :) – Pier Paolo Dec 19 '14 at 15:10
  • Thanks, @Pier Paolo, I intended to do that comment, but I did not have enough reputation (I always find strange that you need more reputation for comments that for content sharing). If you think I should remove this answer, I'll happily let someone redo it as a comment. – juandesant Dec 20 '14 at 19:13

This not quite the answer you are looking for. But since I want to show a sceenshot I (mis)use the answer. In addition the question is pretty old by now.

If you want to show the differnces then I would recommend to have a look at the freeware WinMerge. Here's a screenshot taken from here

Screenshot

You cae easily show the differences in many ways:

  • What was added (grey in the screenshot)
  • What was changed (yellow in the screenshot)
  • What was deleted (grey in the screenshot)

Maybe you can use different screenshots and annotate them with your thoughts.

  • While the base concept of annotated screenshots might be an answer, the tool itself doesn't really matter. I personally would not use such a method, but that's just me. – Sean Allred Sep 20 '14 at 21:48
  • I see. Of course there are better options. Just wanted to help. – Dr. Manuel Kuehner Sep 21 '14 at 17:23

I strongly suggest that the comments be embedded in the code, not in a separate document. Inevitably, when it comes time to revise the code, you, or the person who inherits the code, will not be able to find whatever external document you use for your comments. Also, if they refer to things like module names and line numbers, those may all change, in time. Yes, formula look a lot prettier in LaTeX, but it's far more practical to have ugly, yet fully accessible, comments.

Now, if you want to make something to supplement the comments in the code, say to present to management or use for education, then your approach might work. The diff is a good starting point, but they always seem to need some cleaning up after. Also, they need more explanation, like the words "Added code", "Modified code" and "Removed code". I'd put the code in separate frames from the comments you add.

Your Answer

 

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

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