On Wednesday 29 April 2009 02:19:34 am Thomas Løcke wrote: > Hey, > > I'm about to start the process of writing the 2nd edition of a fairly > long (+150 A4 pages) internal manual. It's about a set of software > systems and programming practices in my business. The 1st edition was > written using OpenOffice. I remember spending a lot of time trying to > make things "look good", and when I'm reading the manual today, I'm > constantly reminded of how hard I failed at that. :o) > > So for this 2nd edition, I've been looking for some better tools, and > this has brought me to LyX. I've installed LyX and TexLive on my > Slackware 12.1 system, and I've tinkered some with it. It appears to > be *exactly* what I'm looking for. > > But before I start writing, I'd like to ask if there are any good > resources on using LyX for writing what is essentially a book on > programming. I'd really like to avoid painting myself into a corner, > like I did with OpenOffice. > > Any and all advice is more than welcome. > > Sincerely, > Thomas Løcke
Hi Thomas, In my opinion, LyX is exactly the right tool for what you're doing. With its WYSIAWYG (What You See Is Almost What You Get) environment, you can pound out content as fast as your fingers can type, and never have to spend time remembering codes or have codes get in your way when proofreading. Almost all appearance will be done by styles, so during authoring you needn't spend time fine tuning the look of the book. And because LyX uses LaTeX under the hood, your book comes out typeset very pleasingly. I've used LyX to write a 309 page 8.5x11, a 201 page 8.5x11, a 231 page 8.5x11 eBook, 2 more eBooks in the 100+ page range, one that was 90 pages, and I'm working on one that's probably going to weigh in at about 150. You mentioned this is a programming book and you want to avoid getting painted into corners. You need to figure out ahead of time what styles you'll need. You'll definitely need a paragraph style for code (paragraph styles are called "environments" in LyX). Personally I make my own (mycode), which is really just a copystyle of lyx-code. You'll also need a character style for code (mycodec). Presumably you're going to need styles Tip, Warning, Caution, and Note for callouts. You might also need a generic callout, so if you want a box with heading DON'T RETURN A LOCAL POINTER FROM A FUNCTION and text explainging why the pointer went out of scope, you can do so. If necessary I can send you my code for these styles. You might also want to change the listing styles. For instance, I always modify the listing environments to make them take less vertical space. When I do that, I give the modified styles new names. Presumably you'll also need a convention of how you're going to do screenshots. Do you want them always exactly in line with the surrounding text, or would you prefer they be able to "float" to nearby pages so LaTeX can optimize page filling? Are you going to personalize the books? Personalization puts the reader on notice that if he/she makes the choice to republish the book on the Internet, his/her name goes with it. In my opinion, personalization is a must with eBooks, and it's easy with LyX. I'd suggest you read all the LyX help files, especially the customization one. I'd also suggest you read "Litt's LyX Library" at http://www.troubleshooters.com/linux/lyx/index.htm. Search the Internet for a doc called "TeX for the Impatient" and read it. There's also a "Not So Short Introduction to LaTeX" or something like that, read it. The Memoir document class has some must-read documentation -- read it, but I don't recommend you actually use the Memoir document class. A guy named Herbert Voss, who used to be a mainstay on the LyX list, has a website with all sorts of cool LaTeX riffs. Last but not least, there are a few dead-trees books on LaTeX. They're expensive, but helpful. By spending the first 3 days of your project reading, you'll understand all the corners you can get out of, and you'll probably discover any you can't. Remember when you're creating your styles that they don't have to be perfect the first time around -- you can change them later. Make em quick and dirty at first, but just be sure to use them every time. The docs on my website are a pretty good reference for how to make your own styles. Now I'm going to give you some very controversial advice, and many will argue with it. DO NOT use the facilities of your document class for your frontmatter -- instead use custom styles and ERT (inserted LaTeX code) to fine-tune your front matter exactly how you want it. There's nothing sadder than the guy who picks a document class to get the frontmatter just right, and then has to live with that document class's ideosyncracies throughout the book. Personally, I always start with the plain old Book document class, and use a layout file to add the features I need. You've picked a great tool to write your book. SteveT -- Steve Litt Recession Relief Package http://www.recession-relief.US Twitter: http://www.twitter.com/stevelitt
