search

jeremyhansen / rooksguide-cplusplus

The Rook's Guide to C++
44 stars 12 forks source link

Sanity check all source code examples #4

Closed jeremyhansen closed 10 years ago

craigr-au commented 11 years ago

Related to Jeremy's comment at https://github.com/jeremyhansen/rooksguide-cplusplus/pull/8

Pulling in the broken-out source code snippets - we should aim to use \lstinputlisting{subdir/whatever.cpp} in lieu of the \begin{lstlisting}...\end{lstlisting} when possible.

This is the ideal situation and I agree completely. There is a small problem with how I've formatted some of the snippets. As an example, refer to https://github.com/jeremyhansen/rooksguide-cplusplus/blob/master/src/Blocks/inline_code_1.cpp

In this example there is code present that is not in the text. Code that is not contained in the text is enclosed between two "special" comments: //##ignore-start and //##ignore-end. I added that code merely so that I could compile and execute the snippet from the text (just to be sure ;-)) There are other ways I could have done (e.g. using linking and/or pre-processor tricks) but those other solutions still would have required changes to the snippet itself. So this is a small problem. Could grep for //##ignore before final (tex) build and remove them I guess. Another solution I started is in src/__private/tolatex.c. That could easily be adapted to just remove the //##ignore blocks (at the moment it reads in [from the dir it is run in and recursing subdirs] .cpp and .h and outputs *.cpp.TeXFrag but that could change)

Issue #2 is the filenames I used... I guess they could be more descriptive, but in my defence I just wanted to get them as *.cpp files as quickly as possible for a start :-)

jeremyhansen commented 11 years ago

I'd just leave them in for now until we are closer to the end, at which point we can grep them out, like you said.

craigr-au commented 11 years ago

Yep, I'll leave them.

I've now checked all the src code except for the calculator program (in src/Sample Programs/).

Everything now compiles. For most of the code I also checked that the code produced what was expected (based on the text and comments in the code). Where I didn't have a clue what the expected behaviour was I made note in the relevant README.txt (grep for TODO or FIXME).

All of the code will have to be checked again in conjunction with editing the text. For example, I wasn't too critical in my checking in has the text changed, but at least everything should be free from syntax errors.

Note that I also removed all instances of system("PAUSE"); If this is important in the course then perhaps it should be mentioned in the text (I don't think it belongs in example code).

craigr-au commented 11 years ago

Oh, I also tried to leave the src as close as possible to what the student's wrote even when I disagreed. My aim was to get a common base as close to what the student's wrote as possible. From this base additions and corrections (or renaming variables etc) can then be made...

jeremyhansen commented 11 years ago

Sounds good to me.

jeremyhansen commented 10 years ago

We'll get back to streamlining the source after the first release -- I've manually fixed up all of the source.