2

I would like to typeset some source code (~70k lines).

The language is Objective-C so it is organized into classes. I would like a table of contents, and page numbers. I would also like each class to start at the top of a page.

It would be good to be able to add inline comments to some parts of this code. It would also be nice to add some cross-reference links between certain parts of the document. (Both of these manually).

Which is the best package to produce something like this (you can also tell me not to use TeX)?

  • I don't know this language but listing package is probably what you are looking for. In CTAN there a a list of some other packages related with typesetting programs. – Fran Jan 13 '14 at 16:23
  • @Fran "listing" could be it... but how do I use this? – martin jakubik Jan 13 '14 at 16:40
  • This has been answered, but when you kown nothing about a LaTeX package, just try to run texdoc package_name (in this case texdoc listing). – Fran Jan 13 '14 at 17:14
3

Here are three powerful packages you can use to typeset Objective-C source code:listings, minted, verbments. All three packages

  • support Objective-C,
  • have a "list of listings" feature,
  • allow for inline comments in the source code,
  • allow for cross-referencing.

So, which one should you choose? It depends on your requirements. A couple of things to know before you make your decision:

  • The minted and verbments packages are very similar. See minted vs. texments vs. verbments for a more detailed comparison. They're both based on pygments and require a call to some Python code, which means you need to enable -shell-escape when compiling your tex file. In comparison, listings performs all the syntax highlighting directly in TeX.
  • The listings package has limited lexing and syntax-highlighting capabilities compared to the other two packages. minted (or verbments) listings often look prettier, in my opinion.
  • However, listings allows for some customisation of the syntax highlighting in the .tex file, whereas the others require some extra Python fiddling outside the .tex file.
  • listings has an automatic line-breaking feature, which the others don't offer. The bottom last screenshot below shows what happens when minted is used to typeset a listing that is too wide to fit on the page. Of course, you may choose to reduce the font size to avoid that kind of problem.

Here is an example using listings. See the documentation for more details.

enter image description here

enter image description here

\documentclass{article}

\setlength\parindent{0pt}

\usepackage{lipsum}             % for filler text
\usepackage{lmodern}            % for, among other things, bold typewriter font
\usepackage{xcolor}
\usepackage{listings}
\usepackage{filecontents}   % for writing to the .m file from within this .tex file

% http://www.otierney.net/objective-c.html
\begin{filecontents*}{sampleObjCcode.m} 
#import <stdio.h>

int main( int argc, const char *argv[] ) {
    printf( "hello world\n" );
    return 0;
}
\end{filecontents*}

% http://www.ultraweaver.com/2010/04/13/objective-c-and-for-loop-with-fibonacci/
\begin{filecontents*}{fibonacci.m}
int i; // used in the "for" loop
int fcounter = 20; // specifies the number of values to loop through
int f1 = 1; // seed value 1
int f2 = 0; // seed value 2
int fn; // used as a holder for each new value in the loop

for (i=1; i&lt;fcounter; i++){

fn = f1 + f2;
f1 = f2;
f2 = fn;

printf("%d: ", fn); // print each value of fn

}
\end{filecontents*}

\lstdefinestyle{myObjCstyle}
{
    language=[Objective]C,
    basicstyle=\ttfamily,
    frame=single,
    keywordstyle=\color{blue},
    breaklines=true,
}

\begin{document}
\lstlistoflistings

\lipsum[1] % filler text

\lstinputlisting
[
    style       = myObjCstyle,
    caption = {Hello World in Objective-C},
    label = hello,
]{sampleObjCcode.m}

As you can see in Listing~\ref{hello}, blah blah blah
but in Listing~\ref{fibo} on page~\pageref{fibo}, we'll improve blah blah blah

\lipsum[2-5]

\lstinputlisting
[
    style       = myObjCstyle,
    caption = {Fibonacci sequence},
    label = fibo,
]{fibonacci.m}
\end{document}

minted example

minted1

minted2

\documentclass{article}

\setlength\parindent{0pt}

\usepackage{lipsum}             % for filler text
\usepackage{lmodern}            % for, among other things, bold typewriter font
\usepackage{xcolor}
\usepackage{listings}
\usepackage{minted}
\usepackage{filecontents}   % for writing to the .m file from within this .tex file

% http://www.otierney.net/objective-c.html
\begin{filecontents*}{sampleObjCcode.m} 
#import <stdio.h>

int main( int argc, const char *argv[] ) {
    printf( "hello world\n" );
    return 0;
}
\end{filecontents*}

% http://www.ultraweaver.com/2010/04/13/objective-c-and-for-loop-with-fibonacci/
\begin{filecontents*}{fibonacci.m}
int i; // used in the "for" loop
int fcounter = 20; // specifies the number of values to loop through
int f1 = 1; // seed value 1
int f2 = 0; // seed value 2
int fn; // used as a holder for each new value in the loop

for (i=1; i&lt;fcounter; i++){

fn = f1 + f2;
f1 = f2;
f2 = fn;

printf("%d: ", fn); // print each value of fn

}
\end{filecontents*}

\begin{document}
\listoflistings

\lipsum[1] % filler text
\begin{listing}
\inputminted[frame=single]{objective-c}{sampleObjCcode.m}
\caption{Hello Word in Objective-C}
\label{hello}
\end{listing}

As you can see in Listing~\ref{hello}, blah blah blah
but in Listing~\ref{fibo} on page~\pageref{fibo}, we'll improve blah blah blah

\lipsum[2-5]

\begin{listing}
\inputminted[frame=single]{objective-c}{fibonacci.m}
\caption{Fibonacci sequence}
\label{fibo}
\end{listing}

\end{document}
1

I recommend doxygen for source code documentation. Doxygen supports various output formats. LaTeX is one of them, and the result is rather good in my opinion, given that a sequence of A4 papers is not the best media for the cross-referencing nature of code.

An example of what the output would look like is this.

The documentation is extracted out of the comments in the source code, so you would have to edit the source code for a documentation, which is not a bad thing to do at all.

  • But I actually want to typeset all the source code, not just the interfaces. My impression is that Doxygen only outputs interfaces (class names, method names, constants, etc...). The audience for this doc is the developers that will be maintaining this source code. – martin jakubik Jan 13 '14 at 16:36
  • If you set INLINE_SOURCES to yes, then the source code will also be displayed. – texnokrat Jan 13 '14 at 16:42

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.