Over the weekend, I posted an update to “The Yii Book“. This is version 0.5, which means I’m halfway there. This is about the time I was hoping to have the book done. So much for good intentions. With that in mind, my sincerest thanks to everyone for their patience. I know this is taking longer than we’d all like, but I’m doing my best and very much appreciate the understanding on everyone’s part. It’ll get done, I promise. And trust that “The Yii Book” is not taking a back seat to anything as far as my work goes these days.
As for this particular update, it started innocently enough. I wrote two new chapters: one on authentication and authorization and another on widgets (Chapters 11 and 12). Those are good, useful chapters, I think. Almost 80 pages of new material, making it the largest update thus far, bringing the total page count (as a PDF) to over 300 pages.
Then, I thought “You know, I wasn’t pleased with the quality of the 0.4 release, so why don’t I take a bit of time to polish this thing up a bit while I wait to hear back from the tech editors?” The tech editors do great at providing feedback, but it still takes them a couple of days. And, as I said, I didn’t think I was attentive enough with the 0.4 release, so re-editing the entire book to this point would be a good idea. And that process would allow me to go back and add internal links to chapters that have since been added (e.g., I wouldn’t have linked Chapter 8 in Chapter 5 when Chapter 8 hadn’t been published yet).
Also, while I was at it, I thought it would probably be a good idea to re-test all the code. Re-testing also allowed me to provide new, updated code as a download. And with the various font and margin changes I’ve made since the first release, sometimes existing code is too long, so I thought it’d be beneficial to revisit all the code to make sure it breaks properly and doesn’t run too far into the margins.
And…while looking at the early chapters, I thought the images were a bit blurry, so why not re-take every image, too? And some of the images were too big, so I should resize those. And some material could benefit from having additional images, both to break up the visual pages and to clarify points being made.
As you can see, a simple idea quickly expanded to a lot of work. All of this work took quite a bit of time (about a week and half), but I think it was useful, both in terms of the quality of the existing material and how I go about writing the rest of the book.
Oh! I did something wonderful. Beautiful. Really sharp. I finally figured out how to format all the tips, notes, and warnings a bit differently so they really stand out from the other text. Oh, it was nice. A thing to behold. At least I thought so, what do you think?
You see: I’ve been making notes along the way about things I’d like to figure out (in terms of formatting, functionality, etc.) before I say the book is done. One of those desires is to format tips, notes, and warnings so they stand out from the rest of the text. After much research and experimenting (and more learning about LaTeX, which is used to create the PDF), I came up with the above look. I like it. Notes would be similar, but blue; warnings would be red. I figured out how to make that happen in LaTeX; it was then a matter of changing all the MultiMarkdown source code to allow me to create the proper LaTeX. While re-editing the entire book, I made all the formatting changes to support this new look.
Finally, at 7pm on a Saturday night, I had edited 313 pages, including the two new chapters, re-tested all the code, and re-took about 3 dozen images. And then I exported the PDF, and it kind of worked, but I had to fix a few minor things. (Note: it takes a long time to even scan 300 pages for obvious problems.) And then I exported the PDF one last time, and looked at it one more time. And…it was a big mess.
Yuck. Ick. It was working, and then it wasn’t. Some tips et al. were formatted, others weren’t. At 7:30 on a Saturday night. And so, as I needed to get the update out, I had to forgo those formatting changes this time around. My beautiful tips and such! Fortunately, thanks to the formatting changes I made, it was just a matter of doing a search and replace to undo the formatting changes. And I’ll still be able to re-implement them later, when I can. So all the effort wasn’t wasted per se, but the fruits of my labors are nowhere to be seen today. Drat.
I always knew that self-publishing this book would be a learning process, an experiment. One lesson I’ve learned already is that when self-publishing, it’s easy to spend hours getting secondary things to work, or having things not work at all. These time-spenders (or time-wasters) are the sorts of things that would not be my problem if I used a traditional publisher. In short, a lot of my time is being spent not writing. On the other hand, almost all the money earned is now mine. But so are the delays. Well, those belong to use all!
But I’m learning. And the time spent learning about LaTeX and the secondary stuff will reap rewards if, or when, I go to self-publish another book.
In the meantime, I’ve got more writing to do!
. Thanks!
Why are you having so much trouble producing a PDF? That is not supposed to be as hard as you’re making it sound. Which software are you using for authoring? Perhaps I can be of some assistance. I have some technical writing experience. Send an email if you’d like.
Mike K.
p.s. I wasn’t sure how to get a message to you, so I just posted this comment.
Hello Mike. Thanks for your comments. I’m having trouble producing a PDF because I’m using Scrivener to write in MultiMarkdown. Then I export MMD from Scrivener. Then I use Pandoc to create a PDF from the MMD source using LaTeX (and I use Pandoc to create an epub from the same MMD source). I’ve never worked with LaTeX before, so getting the PDF exactly the way I want it takes some research and trial and error. And then I need to go back two steps to get the MMD in Scrivener become the right exported MMD which can then become the right LaTeX which can then become a PDF that works and looks like I want it to.
So if you have any experience with Scrivener, MultiMardown, Pandoc, or LaTeX, let me know. Thanks!
Sorry for my slow reply. I have a project that I’m working and it’s completely consumed my schedule.
Wow — that sounds like a LOT of work for publishing a PDF. I’ve been publishing educational materials for 25 years. I mostly use Microsoft Word (I actually have Microsoft Office) on a Mac for publishing.
I have no experience with Scrivener, MultiMardown, or Pandoc. I looked at LaTex a long time ago and saw that it did not fit my needs. I’m not sure why you picked those, but if you’re trying to publish PDFs, then you have a bit of a clumsy solution (if I may say so).
Word is a WYSISYG tool. After you have what you want, publishing a PDF is: Save As, Select PDF format, and then Save Button. I’m not sure what format you need for self-publishing. I have never actually done a self-publish project.
Word “used to be” very easy and intuitive to learn. As functionality has beed added, it’s become a bit more cumbersome, but it might not be too hard to pick up.
If you want, I’d be happy to attempt to import a draft to Word and then export the PDF, just to see how it goes. I’ve never imported anything from Scrivener before, so I’m not sure how that would go. If you want to take this thread off-line, you may contact me via email.
Best of luck to you,
Mike K.
Hello Mike. No need to apologize for the delay and I appreciate your offers of assistance. However, you and I are actually talking about two entirely different processes. Yes, I could use MS Word (or Apple’s Pages) to output a PDF easily. In fact, I’ve written 23 books using MS Word, so I’m pretty comfortable with it and know what it’s capable of. I also know what a lousy program it is. Most importantly here, I could only output a PDF (or terrible HTML). My book is being published as a PDF, as an ePub, as a mobi, and as HTML. My solution is not clumsy, on the contrary, it’s the most flexible solution possible. I write using one medium (MultiMarkdown) and I can output in any format currently available or to be invented. A clumsy solution would be to write in Word and then try to create all the possible outputs. What I’m doing is also pretty much the standard approach for technical self-publishing.
And what I’m doing is actually not a lot of work at all. Not even remotely. I write in plain text, using special characters to indicate formatting. I don’t have to take my hands of the keyboard to highlight text or click buttons, and I don’t need to memorize keyboard commands. I can write, or edit my writing, using any application. The images are kept separate, so they are easy to use and maintain. While I’m writing, I don’t have to worry about layout or formatting or document size or anything but the words. I then do one export from my writing application. So there’s one step. Then I open up the command line and execute one command that outputs a PDF. That’s a second step. And that’s it. I now have a great PDF, complete with a self-generated and linked TOC, an index (if I want), a glossary (if I want), internal links, etc. When I want to output an ePub, I enter a different command, but use the same source code. If I want to change the features or formatting of any output type–PDF, ePub, HTML, I just need to change a template or my command and I get new results without touching my original source. Write once, publish everywhere.
It’s really a supremely capable and flexible solution, vastly superior to MS Word in almost every way. It just requires that I learn some new things, that’s all. But I’d rather learn how to use the best tools for the job than just accept the tools I already know how to use (e.g., MS Word).
Thanks again for your offer and good luck with your project.
Larry,
My apologies if I offended in any way or sounded condescending. I made an observation with limited information and attempted to offer help (obviously unneeded) based on that.
I meant no disrespect for whatever process you have in place for authoring. Sounds like you’ve got it under control and the tools do what you want. The description in your original post made it sound like you were using a tedious and cumbersome process. Perhaps that’s not what you intended to convey and I just missed the intent.
Of course, Word is not the “end all to all”, but it’s what the majority of my clients, who are generally not hardcore IT people and not self-publishers, and not Web programmers, prefer to use. PDFs from Word are simple and accurate, and that’s why I chimed in. HTML from Word is terrible, I agree.
Thanks for sharing your self-publish tactics. Interesting to see the process. Your programing skills serve you well in the environment your working in.
Keep up your good work.
Best regards,
Mike K.
Hello Mike. It’s absolutely no problem at all, and, again, I appreciate the offer of assistance. But as I said, you and I are talking about two different processes. It is very easy to create PDFs from Word (or other applications), but just creating a PDF is not my need. And, yes, there are definitely aspects of the process that are tedious and challenging, but only because of my lack of knowledge.
But thanks again for your input and for your interest in helping. Both are quite kind of you.
Best wishes,
Larry
Larry,
thanks for sharing your progress in your work. A complete version is not only a success in your career, but our readers as well because we can get complete knowledge of Yii.
you’re thinking to self-publish another book! It sounds you have become stronger on the bumpy road of this first self-publishing book. Keep it up.
Thanks, Debra! It’s an interesting experiment. As for self-publishing another book, well, I’m definitely not planning on it today, but expect I will again in the future. I’ll have learned a lot through this experience; it’d be a shame not to capitalize on that newfound knowledge. That being said, it’d have to the right book.