small medium large xlarge

Generic-user-small
20 Nov 2010, 19:30
Larry Jones (89 posts)

So far, the majority of my writing has been straight text.

Because I plan to include both text and source code in my book, I’m wondering what effective ways y’all have found to organize your text and source code. Ideally, tools exist that allow me to pull source code into my writing; however, since I do not have those tools yet, how can I avoid problems that y’all have already run into and solved?

Thanks.

Keep up the writing!

Travis-tiy-sq_pragsmall
20 Nov 2010, 21:55
Travis Swicegood (117 posts)

Hey Larry;

Best idea is to denote the code inline with your text as something that’s text. You do it in ReST by adding a @::@ on a line by itself and then following it by an indention. Markdown’s just an empty line followed by indented text. Either work well for this case. It’s rare you want to show a full module at one whack, so the smaller blocks work well like this.

For the final source source, I’d create a @code/@ directory and then possibly any number of @chapterN/@ directories inside that to contain the completed code for each chapter.

For my book I’m creating the example project as I go along. Once I get to the end of the book I’ll have the entire project. At that point I’m going to throw it out (or, more accurately, create a new clean directory) and walk through all of the examples in a new Git repository. Each step will be a commit, with chapters tagged at the end. This will make it easy for me to export a full tarball with all of the code from each chapter plus provide people with a Git repo that has everything in it.

-T

Generic-user-small
21 Nov 2010, 01:29
Larry Jones (89 posts)

Thanks, Travis.

So far, I used ReST to include code literals just as you suggested.

I’d thought of a src directory with named chapters underneath. (I’ve not yet quite organized things into chapters. I’m still focusing on writing content to be organized at a later date.) Do you worry about duplicating code and text at this point?

In addition, what process do y’all use in writing code? Do you write code and then comment on the process afterward? Do you write code and text together?

My day was productive in terms of accomplishing my goal (~1100 words), but I spent much more time to generate 1100 words plus some code. At this point, I’m thinking: “There must be a better way.”

Have a great day!

Avatar_pragsmall
21 Nov 2010, 03:03
Diego Zamboni (69 posts)

I’ve thought that for technical books where you develop a body of code throughout the book, it might also be interesting to try literate programming to interweave code and text, and have the full code available at the end.

I used a tool called noweb many years ago in school to write and document school projects, and I found it an interesting exercise, but I’m not sure how well it would scale to a book-sized thing. Donald Knuth can do it, but that doesn’t mean any other human can do it as well :)

Dave_gnome_head_isolated_pragsmall
21 Nov 2010, 18:43
Dave Thomas (389 posts)

When you write with our toolset, you keep the code in external, testable source files, and include chunks of it into your book. That way the code in the book is code that you can run. It also means we can upload the code as collateral for the book.

Generic-user-small
21 Nov 2010, 19:37
Larry Jones (89 posts)

Thanks, Dave.

Your explanation helps me to better understand Travis’ earlier suggestion.

Burk_175x175_pragsmall
22 Nov 2010, 20:25
Burk Hufnagel (1 post)

Dave, Is the toolset you mentioned available for not-yet PragProg authors? Sounds like it would make things much easier for us if it was…

Travis-tiy-sq_pragsmall
23 Nov 2010, 01:26
Travis Swicegood (117 posts)

@Diego: Have you seen Docco (and it’s various forks)? It’s used to create the annotated source for CoffeeScript and is quite nice. There are ports for Ruby, Python, and shell.

-T

Avatar_pragsmall
23 Nov 2010, 05:57
Diego Zamboni (69 posts)

Travis, thanks for the pointer! It looks interesting, plus easy to expand to new languages.

You must be logged in to comment