Source code in written technical reports

[Tracy Reed]

I need to prepare some technical reports doing a sort of comparison between one
codebase and another. Normally we simply do everything via email. But we don't
normally include a page or two of code at a time. I am concerned that the
inability to have page numbers and potential for formatting issues may cause
readability (and therefore understandability) issues.

It seems like emailing a PDF might be the best way to go here. I usually
generate PDFs with OpenOffice. But I have never had to include source code in
it before. Anyone have any tips on how to get nice looking source code with
fixed format etc in OO (or feel free to suggest other more appropriate tools)?
I know LaTeX etc. can do stuff like this but I'm hoping to knock this out in
the next couple of days and don't have time for a lengthy learning process.
--
Tracy Reed
http://tracyreed.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.kernel-panic.org/pipermail/kplug-lpsg/attachments/20100930/554b04f7/attachment.pgp

[Carl Lowenstein]

Post by Tracy Reed
I need to prepare some technical reports doing a sort of comparison between one
codebase and another. Normally we simply do everything via email. But we don't
normally include a page or two of code at a time. I am concerned that the
inability to have page numbers and potential for formatting issues may cause
readability (and therefore understandability) issues.
It seems like emailing a PDF might be the best way to go here. I usually
generate PDFs with OpenOffice. But I have never had to include source code in
it before. Anyone have any tips on how to get nice looking source code with
fixed format etc in OO (or feel free to suggest other more appropriate tools)?
I know LaTeX etc. can do stuff like this but I'm hoping to knock this out in
the next couple of days and don't have time for a lengthy learning process.

I would prepare the source code listing with the editor of my choice
(vi) and then set a fixed-width font (Courier) in OO and import the
text.

carl

[Tracy Reed]

Post by Carl Lowenstein
I would prepare the source code listing with the editor of my choice
(vi) and then set a fixed-width font (Courier) in OO and import the
text.

That is what I am doing. So far I have discovered that "styles" come in handy
here. I can select a chunk of source code and set it to my self-defined "source
code" style which sets the fixed width font etc. I have turned on per-page line
numbering for the document so I can get line numbers to refer to. By default
line numbering applies to every style. So I have to explicitly disable line
numbering for the non-source code styles.

I cannot seem to do line numbering by section. So a piece of code which spans
more than one page gets the line numbers starting over again on the next page.
That means I have to specify code by page and line number and if anything
shifts things get thrown off.

Now I am wondering how to best tie my code citations to the correct
line/page/section/whatever. Right now if I insert text and everything gets
pushed down it messes up my citations. It would be nice if each chunk of source
code could be referred to similar to how you refer to pictures or graphs by
saying "Figure 1" but somehow link this piece of text to a particular section
so it gets automatically updated. I could make the whole chunk of source code a
graphic and insert that I suppose and really refer to it as "Listing 1" but
that sounds like too much work and I wonder if there isn't a better way. I am
putting each code listing at the end of the main document in a separate section
and starting each section on a new page for now in an attempt to keep things
simple. That way at least I don't have to worry about my per-page line numbers
getting shifted, just the pages themselves.

I have most of the discussion of the code already prepared in vi awaiting
insertion once I am comfortable that I have these other issues sorted out.
--
Tracy Reed
http://tracyreed.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.kernel-panic.org/pipermail/kplug-lpsg/attachments/20100930/e2acbf88/attachment.pgp

[Neil Schneider]

Post by Tracy Reed
I need to prepare some technical reports doing a sort of comparison between one
codebase and another. Normally we simply do everything via email. But we don't
normally include a page or two of code at a time. I am concerned that the
inability to have page numbers and potential for formatting issues may cause
readability (and therefore understandability) issues.
It seems like emailing a PDF might be the best way to go here. I usually
generate PDFs with OpenOffice. But I have never had to include source code in
it before. Anyone have any tips on how to get nice looking source code with
fixed format etc in OO (or feel free to suggest other more appropriate tools)?
I know LaTeX etc. can do stuff like this but I'm hoping to knock this out in
the next couple of days and don't have time for a lengthy learning process.

Lyx will let you do it in plain text and format on output, like you would
expect. And it can put out pdf, latex, html, so many I forget them all. It's
very easy to use, not much learning curve, and it separates text from display.

Never used Oo for that kind of thing, and never pdfs. I just tried it with a
spread sheet I have been working on. The output isn't too bad. Trouble is you
have to deal with content and display in the same interface.

[Doug]

Post by Neil Schneider
Lyx will let you do it in plain text and format on output, like you would
expect. And it can put out pdf, latex, html, so many I forget them all. It's
very easy to use, not much learning curve, and it separates text from display.

Wow, it must format everything and the kitchen sink because it needs 750MB
to install on a Kubuntu system. Lots of tex and latex parts. Sounds good though.

[David Brown]

Post by Doug

Post by Neil Schneider
Lyx will let you do it in plain text and format on output, like you would
expect. And it can put out pdf, latex, html, so many I forget them all. It's
very easy to use, not much learning curve, and it separates text from display.

Wow, it must format everything and the kitchen sink because it needs 750MB
to install on a Kubuntu system. Lots of tex and latex parts. Sounds good though.

It needs a full LaTeX intall, because it uses LaTeX as its formatting
engine.

It's pretty close to what a system that has a nice GUI, but with the
power of LaTeX. It really is it's own format, but it is modelled
after LaTeX, so the mapping works quite well.

David

[Andrew Lentvorski]

Post by Tracy Reed
I need to prepare some technical reports doing a sort of comparison between one
codebase and another. Normally we simply do everything via email. But we don't
normally include a page or two of code at a time. I am concerned that the
inability to have page numbers and potential for formatting issues may cause
readability (and therefore understandability) issues.

Does "Dive Into Python" have its markup online?
http://diveintopython.org/

If so, you may be able to steal its process wholesale.

-a