December 23, 2011

Happy Holidays From The Salvettes


December 19, 2011

Stop the SOPA Before It's Too Late

In case you haven't heard, the House of Representatives in the old country are going to vote early this week on passage of the Stop Online Piracy Act (SOPA). As the Electronic Frontier Foundation explains, the law is basically a cowtow by the corrupt US government to lobbyists in the film, media, and pharmaceutical industries. The law would not only allow for the federal government to seek court orders against sites that stream content that is under copyright, but to file court orders against search engines (e.g. Google) and payment systems (e.g. PayPal) that do business with these sites--very Orwellian stuff.

Hot Air has some good analysis on what the SOPA is really about:
In other words, a site like YouTube could be shut down just because one of its users posted content that infringes copyright laws. As critics have pointed out, that’s akin to punishing a car company because a car user crashed his vehicle into another person’s vehicle. In other words, to critics of the bill, SOPA is not about piracy — it’s about censorship.
If you enjoy websites with user-generated content (Facebook, YouTube, Reddit, etc.), it may be a good idea to write an angry letter to your congressman regarding the havoc that SOPA will wreak on the way we get information in the 21st century.

Piracy of digital goods was a longstanding problem even before the internet came into popularity in the 1990s. I seem to recall the silly DRM of early games like the original SimCity, where you had to type in a code based on some cardboard readout included in the software packaging. Unfortunately, laws like the SOPA and various DRM schemes do nothing but inconvenience honest users. In the developing world where piracy flourishes, the problem is that legitimate content is way too expensive for the average person to afford.

Hopefully, we will see a new distribution system whereby citizens in countries with lower GDPs can purchase digital goods on a sliding scale. This would be a mechanism to undermine the root cause of piracy and for creators of content to make a few bucks in the process. Until then, we will continue to see these ridiculous lobbyist-created laws that could potentially ruin the internet.

December 16, 2011

Amazon Sells Over 1 Million Kindles per Week

In the past, Amazon has tended to remain mum about the specific sales volume of Kindle eReaders and eBooks. The only figure you hear is the occasional snippet from the CEO, Jeff Bezos, that Amazon was making "millions" of Kindles or they had sold millions since the device was released in 2007. However, Amazon issued a press release on Thursday, December 15, that they were selling millions of Kindles per week. From the press release: today announced that Kindle devices remain the hottest products this holiday season – for the third week in a row, customers are purchasing well over 1 million Kindle devices per week, and Kindle Fire remains the #1 bestselling, most gifted, and most wished for product across the millions of items available on since its introduction 11 weeks ago.
The rock-bottom prices for the Kindle is certainly contributing to the high sales, and as Liza Daly points out in this excellent, scholarly report on eBooks, Amazon really revolutionized the content distribution infrastructure for their gadgets. But we all need to beware of the Ides of March. Large companies that get too big to fail tend to collapse under their own bureaucracy and lack of innovation. The poor roll-out of the new Kindle Format is just one symptom of a larger problem. The embarrassing deletion of best-selling Sugar & Spice from the Amazon UK store is another symptom.

While I'm generally supportive of Amazon, they can hopefully address some of the issues that publishers, self-publishers, and readers are complaining about. Because, Amazon is a lot like Frank Sinatra, it's their world and we just live in it.

December 5, 2011

An EPUB 3 Discussion

Are you a publisher/author trying to figure out what the new EPUB 3 spec means for the future of eBooks? Well, that's make two of us. I did a little bit of research on the nascent subject and wrote an article for Password Incorrect if you're interested. It includes some of the new features we can hopefully look forward to down the road (better interactivity, better layouts, and some other goodies).

November 23, 2011

Fear and Loathing with the New Kindle Format 8

Last month, Amazon announced that the Kindle Fire will support a new Kindle Format 8 with HTML5/CSS3 features. If you are confused by those nerd terms, it basically means that the new Kindle Fires will be able to better display interactive graphics, different fonts, better design, and hopefully some other fun features for eBooks. However, it has been a month and there has still been no further news on the new formats besides the original press release. If there are no guidelines for developers and publishers on how to build these new eBooks with Amazon's proprietary format, then how the hell are readers supposed to access the potential of the Kindle Fire that they shelled out 200 bucks for. The frustration can be seen over at this Kindle forum where authors and publishers alike are clamoring for answers about how to design eBooks for their readers in the Kindle Format 8.

You can signup your email here if you want to receive notification of when the new developer guidelines are out, but so far all I've heard is crickets.

The actual Kindle Fire tablet received a pretty lukewarm review from the folks at Wired, most notably that it had a very clunky web browser:
The Fire’s processor, a 1GHz dual-core chip, appears all but insufficient for fluid, silky-smooth web browsing, an area where I found performance to be preternaturally slow.
Technically speaking, eBooks are basically big long websites built with the same type of code. Therefore, it does not bode well that the Kindle Fire can't render simple websites, let alone a complex eBook.

Hopefully, Amazon is not suffering from oligopoly syndrome, where a small number of large companies have massive market share thereby squashing the economic forces that compel companies to innovate and devote themselves to customer satisfaction. If you want an example of oligopolies run amok, just look to my home state of Michigan. Most of the auto assembly plants were shut down years ago followed by the taxpayers having to bail out two of the Big Three. I hope that Amazon can stay on their toes in the fast-changing world of ePublishing, because a lot has changed just in the last six months and readers are clamoring for better eBooks.

November 18, 2011

How to Make an eBook with Sigil - Free

For those who don't want to get into the nitty-gritty of eBook formatting (I don't blame ya), you can take the easy way out and build an eBook with a free program called Sigil, that turns regular text and images into the EPUB format. Based on a 3-part series I guest posted for Piotr over at Password Incorrect, I decided to put it into eBook format for those who would prefer the content in file format. Below is the blurb for How to Make an eBook with Sigil:
Creating a perfect eBook from a manuscript requires technical knowledge that many authors in the self-publishing community either do not have or do not have time to learn. By using the free program Sigil, you can quickly and easily convert your manuscript into an EPUB eBook that is ready to be uploaded to many of the eBook stores. Also, you can easily convert the eBook made in Sigil into a format that is ready to upload to Kindle.

How to Make an eBook with Sigil is a 2,000-word guide for self-publishers that teaches you to quickly format your manuscript into an eBook.
 Check it out for free over at Smashwords.

November 14, 2011

Prevent Deployment Boredom with Operation eBook Drop

For those indie authors looking to do a small service to help out some of our troops in harm's way, there's a way to send our servicemen free eBooks through Operation eBook Drop. This program was founded by an author and veteran, Edward Patterson, and Mark Coker of Smashwords helps out as well. The way it works is you issue a free coupon on your Smashwords account for your latest masterpiece, and then you send the coupon and link to your self-published eBook to a mailing list of military members and family members that Edward Patterson has compiled.Write to Ed to gain access to the mailing list, and there's about 180 addresses on the distribution with plenty of room for more. If you use Gmail, you can BCC up to 500 contacts, so you don't need anything fancy to email this many people on one shot.

This is a great program, because I was in Iraq for a year in the bygone days of 2007-2008, when eBooks were virtually unheard of. Being a Green Zone fobbit, the Groundhog Day phenomenon, where every day is exactly the same, began setting in about month 2 (with 10 months left to go). Lucky for me I was able to order print books from Amazon, but some of our troops living on combat outposts might not have that luxury. Therefore, an eReader stocked with eBooks is a great thing to bring to war to stave off boredom and the mid-deployment blues. With no alcohol, serious restrictions on co-mingling with the opposite sex, and having to work 14-hour days, reading is a great activity for active duty personnel to keep sane (at least I felt so, and YMMV).

A big concern is that internet connections in war zones can be atrocious, despite the US government shelling out millions to contractors to provide this service for the troops. I'm not sure if speeds have improved in the last 4 years, but when I was in Iraq, it was virtually impossible to download anything over 1MB. Therefore, you may want to consider not sending that 8MB eBook full of high-res pictures.

Hit or Miss Internet Connection (me in Iraq - 2007)

So, head on over to the Operation eBook Drop website and write to Ed for the email list. It's an easy thing to do. Hopefully, some of the big publishing houses will consider providing a similar service to our troops.

November 7, 2011

How to Prepare a PDF for Conversion into an eBook

Thank you for visiting this eBook design tutorial. We now have an eBook design startup—BB eBooks—dedicated to helping independent authors and small presses get their eBooks formatted, converted, and ready for sale at all the major online retailers (e.g. Amazon's Kindle Store, Barnes & Noble's Nook, iBookstore, Smashwords, etc.) Please contact us for a no-obligation quote. For those writers, editors, and publishers looking to go the DIY route for eBook production (you probably are if you visited this page), we offer free online tutorials and apps to help you professionally design your eBook. Please visit our Developers page and let’s work together to improve the overall standards of eBooks. Also, please sign up for the mailing list for promotions, design & marketing tips, plus eBook industry news.

Problematic Formatting on eBooks due to Direct PDF Conversion

Complaints about poor eBook formatting from the big publishing houses are becoming more numerous from readers. You would never see improper page breaks, erroneous fonts, and garbled text on a print book, so why are the publishing houses allowing these sloppy standards into eBooks? Neal Stephenson’s latest eBook Reamde, a technothriller ironically about a computer hacker, had random hyphens scattered throughout the Kindle edition. Amazon eventually had to temporarily yank it until HarperCollins got their act together to justify the $14.99 cost.

While not knowing the workflow that happened behind the scenes at HarperCollins, I’m guessing the Reamde flub was the result of poor conversion from a finalized PDF for print into the eBook formats. Karen Dionne at the Huffington Post highlights the problem in converting PDFs into eBooks:
Self-published authors frequently take the hit for poorly edited and badly formatted e-books. But the truth is, many of them are more careful about proofing their work than traditional publishers seem to be.

"I don't think I've yet seen an e-book that didn't have some pretty blatant formatting and typographical errors in it," says Keith Cronin, author of the novel Me Again, "and I'm talking about even bestselling books from the major publishing houses. In some cases I've also owned the paper version of the book, and have confirmed that the error only appears in the e-book."

Portable Document Format (PDF)

The PDF was developed in the 1990s by Adobe as way for computer users to read complex documents in a standardized format—not edit. Unlike the PDF’s fixed-layout format, MOBI (the eBook format for Amazon) and EPUB (the eBook format for everywhere else) have reflowable content to accommodate differently-sized eReaders. This means that a PDF cannot be easily changed into eBook formats by any third-party software. Even when a PDF is created from an InDesign layout, which is frequently done in the professional publishing industry, it is not a simple task to convert it back to the source InDesign file. Unfortunately, many publishing houses and authors with backlists only have their final print available in PDF format and not in a word processor format (like Word’s .doc or .rtf). Sucking the information out of a PDF is a challenging task, but here are some tips to make it a bit more manageable. Since this is time-consuming and prone to error, these methods should only be used if you have no access to any other source files (i.e. a Word document, InDesign files, etc.)

Use Acrobat Pro to Save As a Word Document

Acrobat Pro is similar to the free Acrobat Reader offered by Adobe, but the Pro version has a lot more features. Unfortunately, the software is priced at $199 and many writers don’t want to shell that out during these hard times. Assuming you want to go this route, let’s take a look at my PDF version of How to Format Your eBook for Kindle, NOOK, Smashwords, and Everything Else. The PDF contains a significant number of images, text, bulleted lists, and other complexities. Trying to cut and paste from the PDF will leave a lot of hard breaks and mangle the formatting. You want to make sure that the text is reflowable prior to trying to build an eBook.

Perform the following steps to convert your PDF into a .doc format.
  1. Open the PDF with Acrobat Pro
  2. Select “Export” under the File tab
  3. Select “Word Document”
  4. Click on “Settings”
  5. Ensure that the “Retain Flowing Text” button is checked; otherwise, you will have hard breaks on each line
  6. Do Not Click the button for “Regenerating tags” or “Including Comments” as this may crash your computer
  7. Select “Ok”
Steps 2 and 3
Step 4
It may take a while for the conversion to take place and create a valid Word document, but it will eventually finish up.

Alternative Method for Converting PDF to RTF with Calibre (Free)

RTF (Rich Text Format) is similar to the .doc format and can be opened with Microsoft Word and many other word processing programs. Calibre is an open-source eBook content management system that can do a variety of conversions between formats with an extensive amount of options. The Calibre manual advises to use a source PDF as a last resort, so this tutorial assumes you have absolutely no other option to make your eBook.
To convert a PDF to RTF perform the following in Calibre:
  1. Click “Add books” on the main page to add your source PDF
  2. Click “Covert Books”
  3. Select “RTF” under the Output format in the upper right hand corner
  4. Press “Ok”
Steps 1 and 2
Step 3
Calibre is a great program that is absolutely free, and the conversion results from PDF to editable content are almost exactly the same quality as Acrobat Pro.

Examining Your Converted Content in a Word Processor

This is the ugly and labor-intensive part. You will notice that the editable content that you open in either Microsoft Word or Open Office looks completely terrible. Problems converting from PDF include (but are not limited to):
  • Headers and footers from the PDF showing up in the content
  • Garbled characters
  • Extraneous spaces and indentations
  • Content placed into text boxes
  • Images located all over the damn place
The Ugly Results of PDF Conversion
To prepare your document to be converted into XHTML as part of the MOBI and EPUB workflow, you really need to spend some time editing this messy content. Look for patterns that became garbled during conversion (e.g. loss of certain capital letters, loss of bulleted lists, etc.) and do your best to rectify the myriad of problems. You can use the Find and Replace feature (Ctrl+H) to help make short work of this task. For the extraneous spacing before and after paragraphs, you can get rid of these with the “Trim leading and trailing spaces” in a text editor like Notepad++.

This process may sound lousy, but it is better than trying to directly convert to plain text from PDF, because you retain some of the formatting (e.g. italics, headings, etc.) when converting from PDF to .doc or .rtf.

Extracting Images from and RTF or DOC

Hypothetically, you could go image by image and copy and paste to Powerpoint or Photoshop and then save the image. This can be a tedious task if your eBook has an extensive number of images. To extract all images from a document, perform the following steps:
  1. Save your .doc or .rtf as a .docx file
  2. Open the .docx file with 7-zip or another unzipping utility
  3. Look for the folder /word/media
  4. All images are located in this folder
Location of Image Files in the .docx Package
Once you extract all these images, they will be conveniently numbered based on their location within the document. This will be useful as you construct your eBook with XHTML.

Build Your eBook from the Ground Up

Now that you have a workable source document, you can begin the workflow process from the ground up to ensure a 100% perfect conversion. A detailed tutorial on how to construct an eBook from a manuscript can be found on this website. The entire process can be very labor intensive if you have a complex eBook. However, if you are a publisher planning on charging $14.99 for a Kindle copy, you should be sure it’s perfect.

November 3, 2011

Possible Code to Fix the Double Cover Issues on eBooks


If you take the advanced route and work with EPUB code to format your eBooks, it may be advantageous to have a separate XHTML file that can be accessed to display the cover image. I like to link to this file in both the eBook's HTML Table of Contents and the meta Table of Contents (NCX) in case the reader wants to check out the cover. There's a file in my EPUB package that has the following code:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "">
<html xmlns="" xml:lang="en">
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />
<style type="text/css">
  @page {padding: 0pt; margin:0pt;} <!--Remove for MOBI-->
  body {text-align: center; padding:0pt; margin: 0pt;}
  div {padding:0pt; margin: 0pt;}
  img {padding:0pt; margin: 0pt;}
<img src="cover.jpg" alt="The Book's Cover" style="height: 100%;" />

In the content.opf file, the brain of the eBook, the coverpage.html file is located at the beginning of the spine section to indicate that it should show up first. This works swell for eBook readers like Adobe Digital Editions. However, you will get two cover images after you run your EPUB through KindleGen and upload to the Amazon Kindle Store. This is because Amazon requires the following code in the metadata section of the content.opf file:
<meta name="cover" content="My_Cover_ID" />

And the following code is in the manifest:
<item href="cover.jpg" id="My_Cover_ID" media-type="image/jpeg" />
<item href="coverpage.html" id="coverpg" media-type="application/xhtml+xml" />
So when the reader pulls up your eBook in the Kindle the get two cover images on two different pages at the beginning. This was apparent in the new Steve Jobs Biography, which means Simon & Schuster was having the same problems as the rest of us.

As a workaround to the double cover issue, you can try adding the following XML into the spine section:
<itemref idref="coverpg" linear="no" />
The linear attribute is "yes" by default, and it makes the section inside the eBook available, but it cannot be accessed by page turning. It should be a good method, but unfortunately nothing ever works as its supposed to in the MOBI format. Both the Kindle and Mobipocket stick the cover in the back for some reason with strange results when you try to click through the navigation with prev/next section or prev/next page.

Conclusion: It looks the best option for the Kindle is to completely remove the coverpage.html file and adjust the Table of Contents as necessary making no reference to the coverpage.html. If anyone has a better way, I'd sure to like to hear it.

October 30, 2011

Raid on Soi 5 Now Available for Free

Taking a page from the Lindsay Buroker playbook, I'm trying to release more freebies on Smashwords to help promote books that actually make me money. Raid on Soi 5 was first seen at the Flash Fiction Offesnive, so I decided to turn it into an eBook. It's free over at Smashwords, and below is the blurb:
Beneath Thailand’s veneer of smiling people and luxury hotels lies a dark underworld. Drugs, prostitution, and robbery await the throngs of hapless tourists who visit the country on holiday. Sukhumvit Road is a pleasant location in Bangkok to visit by day, but at night the filthy underbelly floats to the surface, engulfing those who dare to venture into its sleazy alleyways.

Raid on Soi 5 is a 1,000-word short story thriller about the corruption and treachery of those who deal drugs to tourists on one of Bangkok’s most notorious streets.

October 27, 2011

The 2011 Thailand Floods - What it All Means

Above is a video entitled "รู้สู้น้ำท่วม" or "know about the flood" which explains the current flooding calamity in Thailand brought about by a combination of deforestation, heavy rains, and improper water management (with English subtitles!). Like many things Thai, it is a very cutesy approach to explain a complex problem. The situation is incredibly grim for residents in Ayuthaya, Pathum Thani, and other burbs north of Bangkok, and the deluge has shattered communities and destroyed the economy--hundreds of factories have had to close resulting in a crippled worldwide automotive and motorcycle industry. Like most natural disasters, the elderly, the sick, and children are the most vulnerable, and we were fortunate enough to have had the opportunity to evacuate our baby up to high ground in northeastern Thailand to avoid the deluge.

Similar to the Bangkok riots and arson in 2010, living in this city is sort of like the opening scene from Dawn of the Dead. Reality around us is shattering as we wait for the inevitable waves to breach the flood barriers and swamp inner Bangkok. There's no one else for the water to go, and our fate is sealed. Through all the suffering in this country, maybe something good will come out of this, like a tale of great heroics or a more civic-minded society. Time will tell.

October 24, 2011

Amazon Releases New Kindle Format - KF8 with Weak CSS3 Support

Amazon announced via press release that it will be releasing a new version of it proprietary MOBI format. This comes on the heels of the recent finalization of the EPUB3 spec, which is the open standard eBook format used by pretty much everyone except Amazon (e.g. Barnes & Noble, iBookstore, etc.) The new format will hopefully be a vast improvement over the previous MOBI format used by Amazon, which left many a self-publisher frustrated due to its erroneous rendering of tables, lists, and images.

The Kindle Format 8 is based on HTML5 and CSS3, which is geek-speak for the current standards of web design and development. The new HTML5 tags (such as <section>, <nav>, and <article>) are more geared toward developing more pretty HTML source code and not very exciting for the average eBook reader. However, CSS3 is a way to "style" the eBook in new ways. You can do lots of fun things with it to improve the reader's experience like adding animations (for an example see my social media icons on the right sidebar), adding shadow effects (see my wife's business' website), and even adding headers and footers to every page with the @page feature.

Unfortunately, if you take a look at the supported tags and properties in the new KF8, it supports none of the aforementioned tricks you can do with CSS3. This is in addition to the fact that the new KF8 will most likely not be backwards compatible with older Kindles, which is sure to piss off a lot of readers. Also, no support for JavaScript, so forget about pop-up footnotes. The only real useful feature I'm seeing on the new KF8 is that you can now float images (i.e. wrap text around images). There's also some support for embedded audio and video. This coding has been around since Friends was the #1 show on TV, so it's really not anything too exciting. But hey, it's better than nothing.

October 18, 2011

A Handy App to Make Curled Quotes for eBooks

Attention typography nerds. Now that the digital age has dawned upon us, the straight up and down double quotes, single quotes, and apostrophes in eBooks need to become as extinct as the typewriter and trustworthy politicians. Readers (i.e. the customers) seem to prefer the "fancy" or "curled" quotes, especially for works of fiction, so there is no excuse for letting them linger like outdated relics inside your eBook.

Below is an example of straight vs. curled quotes:
"Hey, knock that off!" said Gamera's illegitimate offspring.
“Hey, knock that off!” said Gamera’s illegitimate offspring.
It's easy to spot the difference, and readers will take note if you're not using fancy quotes in your eBooks and think that you're some yahoo. Many of us are self-publishing on our laptops while not wearing any pants, but we want to give the reader the impression that we are professionals. Now it would be an incredibly painful task to go through your manuscript line-by-line to turn each straight quote into a curled quote. Fortunately, there are two options at your disposal.

Getting Microsoft Word to Automatically Format Curled Quotes

Microsoft Word has autoformatting features that convert all straight quotes into curled quotes. Apostrophes are also converted from a straight up and down mark to a closing single quote. The first thing to do is enable this autoformatting feature, which is usually on by default. More information on how to do this is available at my eBook formatting tutorial or in my book How to Format Your eBook for Kindle, NOOK, Smashwords, and Everything Else.

Perform the following steps:
  1. Click the Windows Icon in the upper left
  2. Click Word Options
  3. Click Proofing
  4. Click AutoCorrect Options
  5. Under the Autoformat tab, deselect all boxes except for Straight Quotes for “Smart Quotes” and Hyphens (--) with Dash (—)
  6. Under the Autoformat as you Type tab, deselect all boxes except for Straight Quotes for “Smart Quotes” and Hyphens (--) with Dash (—)
Next, you should use the Find and Replace function (Ctrl-H) to replace all " with " and ' with '. It may sound a bit counter-intuitive, but you are forcing Microsoft Word to use it's magic on all double and single quotes throughout your manuscript to make them curled. Here are some screen shots of the Find and Replace window:
The process is pretty quick and easy, so do not overlook this as you are putting the final touches on your manuscript.

Online App for Converting Boring Quotes to Curled Quotes

For Open Office users, automatically formatting the quotes works for doubles, but not for the singles. That is why a fellow named Thomas Giles created a very handy app that automatically converts everything into fancy quotes. It is written in JavaScript, so all you need to run it is 1) a web browser, and 2) knowledge of how to copy and paste text (Ctrl-C and Ctrl-V respectively).

For Tom's app you basically just slap in some text into the window and click "fix". The formatted text will appear in the same window. The app is free, so there is no excuse to use antiquated straight up-and-down quotes ever again.

Nerd Note: When you format your eBook in HTML, don't forget to convert all the fancy quotes to HTML entities, because some eReaders will display junk when rendering the curled quotes since they are outside the ASCII character set.

October 13, 2011

Free Tablets for Thai Youth Could be Problematic

Best Technology Yet - (photo credit: gadgetsbuzz)

It seems a bit aloof and naive to write an article when so much suffering is going on in Thailand due to the flooding, but there was an interesting article from the faculty at Asian University discussing the Prime Minister's campaign promise to give all children in Prathom 1 (Grade 1) a free tablet. From the Bangkok Post:

Thailand is going to face great difficulties if it attempts to introduce tablet computers as fully-fledged learning tools at the lower levels of primary education for a number of reasons. First of all, until now relatively few learning applications are available in Thai language and the operating systems used for tablets all feature English. This means that students have to acquire some form of basic proficiency in English to navigate their new learning tool. This has been acknowledged by Education Minister Woravat Au-apinyakul and he has encouraged schools to provide extra English tuition to tackle this problem.
It is a common complaint amongst the business community in Thailand that the education system woefully unprepares its students for the IT-centric 21st century. A big issue is the poor level of English in Thailand. With most software written in English, this does not make it easy for students to learn how to use computers. Training for teachers on how to utilize this technology is absolutely critical, but this needs to be coupled with English language training as the author mentions.

Unfortunately, creating eBooks is a shoddy process at the moment and uses developing techniques from the late 1990s (XHTML), which is not well-suited for designing educational textbooks, especially in Thai. The new EPUB3 format for eBooks (just finalized by the International Digital Publishing Forum) will hopefully standardize multiple languages and allow functionality of MathML code to display mathematical equations. If it doesn't then the Thai government will have to develop some kind of mobile app to handle all this content so that children can read textbooks on their subsidized tablets. Best of luck to them.

October 9, 2011

Sigil Tutorial

While waiting for the flooding deluge to hit Bangkok, I managed to write up a tutorial on creating eBooks with Sigil that Piotr at Password Incorrect was kind enough to post at his place (as well as at Teleread). Sigil is a neat open source program that takes all the pain and suffering out of creating a valid EPUB eBook. Lindsay Buroker also re-posted a 1,000-word post I wrote on the ups, downs, and all-arounds of eBook formatting. It goes without say that getting backlinks from high-traffic bloggers is very helpful, and you should never underestimate the power of flattery.

Thank you for visiting this eBook design tutorial. We now have an eBook design startup—BB eBooks—dedicated to helping independent authors and small presses get their eBooks formatted, converted, and ready for sale at all the major online retailers (e.g. Amazon's Kindle Store, Barnes & Noble's Nook, iBookstore, Smashwords, etc.) Please contact us for a no-obligation quote. For those writers, editors, and publishers looking to go the DIY route for eBook production (you probably are if you visited this page), we offer free online tutorials and apps to help you professionally design your eBook. Please visit our Developers page and let’s work together to improve the overall standards of eBooks. Also, please sign up for the mailing list for promotions, design & marketing tips, plus eBook industry news.

October 6, 2011

Prime Minister's Twitter Hacked

Prime Minister Yingluck's twitter account was not the most exciting thing in the world. Unlike the perpetually hilarious and controversial Chuvit (@chuvit_online), the Prime Minister's staff used her Twitter account (@PouYingLuck) to post your standard press releases of wai-ing monks, wading through flooded streets, etc. Nevertheless, someone hacked the account and a 20-year old Chula student picked it up on 4chan or somewhere else within the "Underground Hacker Community", whatever that is. From the Bangkok Post:
Aekawit Thongdeeworakul, a fifth year student attending the Faculty of Architecture of Chulalongkorn University, has confessed publicly that he hacked into Prime Minister Yingluck Shinawatra's Twitter account on Sunday.

The 20-year-old made the admission at a press conference at the Ministry of Information and Communication Technology on Wednesday afternoon.
Chula is the Harvard of Thailand, but apparently the poor kid wasn't smart enough to use an IP spoofer. Now Khun Yingluck's Twitter account has vanished from the internet like Oh well.

Whenever a politician's online whatever gets hacked, nothing real juicy ever comes up. There were no secretive direct messages between Yingluck and her older brother, Thaksin Shinwatra (@ThaksinLive), and the information revealed was as big a dud as when Sarah Palin's email got hacked back in 2008. Politicians are either too smart to know that they shouldn't be involved in shenanigans in the brave new digital world, or they are so stupid that they get in trouble being themselves, like sending unsolicited crotch shots.

October 2, 2011

Kindle Superuser by Gary McLaren

In case you don't know, Gary McLaren runs the always helpful and insightful Publish Your Own Ebooks, which is a great resource for self-publishers. For people looking to self-publish on Kindle, NOOK, Smashwords, Lulu, and others, I highly recommend checking out his free self-publishing reference card that focuses on royalties, formats, and other information about the big eBook distributors. McLaren wrote a useful primer for readers looking to make the jump from dead tree to eBooks called The Beginner's Guide to Ebooks, and he has a new eBook out about tips and tricks for the Kindle (specifically the Kindle 3).

Here is my 5-star review of Kindle Superuser - 101 Ways to Get More from Your Kindle at

In the new world of cheap, and sometimes free, eBooks and low-cost eReaders, there is a significant amount of information available to publishing houses and self-publishers alike to create, distribute, market, and promote eBooks. Unfortunately, the brave new digital world has neglected the most important group of people during the world-wide transition from print books to eBooks: the consumer.

Guides on how to properly utilize your Kindle can be terse at best and affiliate marketing scams at worst. That is why McLaren's Kindle Superuser is a handy reference for all Kindle lovers who want to maximize use of their eReading device. This guide is a nice follow-up to The Beginner's Guide to Ebooks, which helps readers understand more about eBooks.

As the product description implies, Kindle Superuser highlights a number of features that I had no idea existed on a Kindle 3. This includes basic energy saving tips, accessing content that is free at the Kindle store, and even the more uncommon feature of using natural logarithm functions on the built-in calculator. Probably the most important tidbit of information is how to get eBooks and files in non-Amazon formats onto your Kindle 3. This process is not well-explained by the powers that be (obviously because they want you to buy different versions of the same content), so McLaren's guide is indispensable as a money saver.

Kudos to McLaren for creating this useful guide with the reader in mind, and I hope that he creates a similar eBook once the Kindle Fire starts to proliferate.

September 30, 2011

Sacred Heart School Director Offers "Deeply Apologies" After Nazi Fiasco

From Prachathai - Notice the Strange Picture of John Lennon

I don't mean to pile onto the misery in Chiang Mai at the moment, because it is experiencing serious flooding that has destroyed a lot of people's homes and crops. However, the recent sports day event at Sacred Heart College where students dressed up in Third Reich regalia and marched around deserves some attention. It certainly drew a lot of scorn from the American, German, French, and British Consulates in Chiang Mai (article is in ภาษาไทย).

Obviously, the children did not deliberately mean any ill-will toward the millions murdered under the scourge of National Socialism and military imperialism. Judging by the letter from Sacred Heart College Director [pdf], I don't think the teachers meant any intentional. Rather, it appears to be a case of complete ignorance of one of the worst genocides in history. Sure, it's easy to get up on a high horse, but this is a serious problem with education in Thailand.

This is not the first time Nazi symbolism has been used as fashion in Thailand. You can walk into Chatuchak market (one of the biggest markets in Bangkok) and see tons of weird t-shirts with Hitler wearing sunglasses and the like. Also, popular band Slur has a video where they dress up in Nazi gear like some kind of joke.

A commentary in the Bangkok Post said that Thailand is over-militarized. I disagree. It's another example of why education is important, and with four Thai kids, I can only blame myself if they end up goosestepping.

September 28, 2011

How to Format Your eBook for Kindle, NOOK, Smashwords, and Everything Else

Warning This Content is Out of Date. Please head on over to the BB eBooks Developers Page for the most up to date information on eBook creation.

As a self-publisher I wanted to learn about how to properly format and design an eBook so that I could place my first novella, America Goes On, on sale at the Kindle Store, Barnes & Noble NOOK, and Smashwords. With a few notable exceptions (such as Guido Henkel's guide on eBook formatting best practices and Paul Brookes' guide on formatting for Kindle) the information available on formatting is rather scarce at this time. Since we are all in this together, I decided to make some tutorials on formatting for the Kindle Store and NOOK, as well as a supplemental guide discussing formatting for Smashwords.

The response from the self-publishing community has been quite positive, indicating that there is a strong need for this type of information. Therefore, I decided to turn the tutorials into an eBook itself that self-publishers can utilize as a technical reference when formatting their own eBooks.

On Sale
How to Format Your eBook for Kindle, NOOK, Smashwords, and Everything Else is available for the low price of $2.99 at the Kindle store, Barnes & Noble NOOK, and Smashwords. Since the economy is still in the drink, I'm offering a recession special whereby I'll send you a complimentary PDF in exchange for a friendly email to me. The eBook contains edited versions of tutorials on this site, which have been edited, as well as some extra goodies to make your life easier as you publish your eBooks.

Product Description of How to Format Your eBook for Kindle, NOOK, Smashwords, and Everything Else 

Online sales of eBooks have exploded recently, and the trend will only continue with the availability of low-cost technology. Unfortunately, guidelines on how to properly format an eBook to sell on, Barnes & Noble NOOK, Smashwords, and other distributors are terse and geared toward web developers rather than self-publishers. Templates and third-party programs advertised to quickly convert a manuscript into an eBook often leave the final product in a dismal state of sloppiness that offends readers. This is because eBooks need to be converted to the same code that is seen on websites, not what is in a word processor.

This guide was designed by an indie author for indie authors in the self-publishing community to provide the requisite knowledge to professionally format an eBook in all major formats. It will take you step-by-step from a manuscript on your computer to the perfect eBook formats you need for Amazon, NOOK, Smashwords, and other markets.

In this guide you will learn how to:
  • Layout your manuscript for conversion into the major eBook formats (i.e. MOBI, EPUB, PDF) for all the big markets (i.e. Amazon, Barnes & Noble, Smashwords, and others)
  • Add styles to different types of text in your eBook
  • Add hyperlinks, bullets, and images to your eBook
  • Create a clickable Table of Contents for your eBook
  • Generate eBooks using open source software
No prior knowledge of web programming is needed, because this guide provides detailed instructions and images to improve your level of knowledge from the ground up. The following detailed tutorials are covered in this guide:
  • Converting your manuscript from a word processor into a text editor
  • Web programming tutorial (XHTML)
  • Web programming needed to add styles to your eBook (CSS)
  • Using Microsoft Word for Smashwords
  • Using Calibre to convert XHTML into all eBook formats
  • Publishing your eBooks on Kindle, NOOK, and Smashwords
  • XHTML/CSS source code
For those interested in the advanced methods and techniques of eBook formatting, this guide also provides the following tutorials:
  • Regular Expressions for eBooks
  • Creating an EPUB from the ground up
  • Using KindleGen to create a MOBI file
  • EPUB source code
Buy this 46,000-word (~200-page) guide that comes with over 150 helpful images, and you will never have to pay to have your eBook professionally formatted.

We now have an eBook design startup—BB eBooks—dedicated to helping independent authors and small presses get their eBooks formatted, converted, and ready for sale at all the major online retailers (e.g. Amazon's Kindle Store, Barnes & Noble's Nook, iBookstore, Smashwords, etc.) Please contact us for a no-obligation quote. For those writers, editors, and publishers looking to go the DIY route for eBook production (you probably are if you visited this page), we offer free online tutorials and apps to help you professionally design your eBook. Please visit our Developers page and let’s work together to improve the overall standards of eBooks. Also, please sign up for the mailing list for promotions, design & marketing tips, plus eBook industry news.

September 21, 2011

Book Bloggistas Save the Day

So you've self-published your brilliant novel, and the only people who have bought it are your sister and the people you kept bugging at work. This is a common problem for the indie author, so don't feel discouraged. Both Amanda Hocking and Stephen Knight have said that book bloggers were keys to their success, and that's why it is important to submit free copies of your work to book bloggers in the hopes that they will review it and perhaps even publish an interview with you. This should be an essential part of your marketing strategy, because book bloggers will publish reviews on Amazon, GoodReads, Nook, etc.  and provide links that are crucial for search engine optimization. Without NY reviews on the sites of the big distributors, most readers are going to think your book is a dud before they even read the product description.

Unfortunately, previous knucklehead writers have pissed off book bloggers in the past by not following submission guidelines, complaining like Kindergartners in the comments about negative reviews, and other shenanigans. Remember that the reviewer is doing you a favor by taking the time to read through and publish their opinion of your work, so treat them with respect.

For my latest novella, America Goes On, I submitted it to approximately 10 book bloggers for review, and so far I've gotten 4. Not bad for a nobody! America Goes On received a 5-star review from Bornean Bookworm, a 3-star review at Novella Reviews, a 4-star review at Hampton Reviews, and a 3.5-star review at My Four Bucks. At Bornean Bookworm and My Four Bucks, I even got an interview published.

Here are some helpful tips when approaching book bloggers to keep yourself out of the shits:
  • You can find a helpful list of book bloggers open to submissions in various genres at Simon Royle's, the GoodReads Indie Book Collective group, and the Book Blogger Directory. Make sure that the genre of your book fits with the reviewer's taste.
  • Every book blogger has different submission guidelines, conveniently located under a tab that is usually labeled "Submission Guidelines." If they want a MOBI file for their Kindle, don't send them a 7MB RTF file with uncompressed pictures. Be sure to provide all the requested information (picture, bio, description, etc.)
  • Do not mass mail book bloggers. Do you like your inbox being shit-bombed with spam about penis enlargement pills? Didn't think so. Every email should be individually written and should address the book blogger by name (if they are not anonymous). Also, about 90% of book bloggers are women, so if there's something you wouldn't say to your mother, you probably shouldn't say it to them.
  • Under no circumstance should you contest a review, because everybody has different opinions. That is why the written word is so interesting--the words mean different things to different people. You should respect their review and learn from it.
  • Don't ever pay for a review. That is just unethical and weird.
  • If your book gets reviewed, be sure to reply with a nice thank-you email for the time they took to read your book. Also, make sure to provide links to their website to help promote yourself and them.
Book bloggers provide an invaluable service in promoting the self-publishing community, and they do it all for free. As long as you are not a jackass and you spend some time searching for book bloggers, you will have no problems getting your book reviewed. Best of all, the reviews provide helpful feedback on how to improve your writing in the long-term.

September 13, 2011

How to Self-publish your eBook on Kindle, NOOK, and Smashwords

Thank you for visiting this eBook tutorial. We now have an eBook design startup—BB eBooks—dedicated to helping independent authors and small presses get their eBooks formatted, converted, and ready for sale at all the major online retailers (e.g. Amazon's Kindle Store, Barnes & Noble's Nook, iBookstore, Smashwords, etc.) Please contact us for a no-obligation quote. For those writers, editors, and publishers looking to go the DIY route for eBook production (you probably are if you visited this page), we offer free online tutorials and apps to help you professionally design your eBook. Please visit our Developers page and let’s work together to improve the overall standards of eBooks. Also, please sign up for the mailing list for promotions, design & marketing tips, plus eBook industry news.

Warning This Content is Out of Date. Please head on over to the BB eBooks Developers Page for the most up to date information on eBook creation.

So, this is it. This is the final step toward having your eBook available for sale to the international marketplace of readers. For publishing on the Kindle store, you will need a MOBI file. For publishing on the Barnes & Noble NOOK store, you will need an EPUB file. Finally, for publishing on Smashwords, you will need a clean .doc file. Please consult the eBook formatting tutorials for MOBI/EPUB and Smashwords for further assistance.

This guide does not cover how to market your eBook, which is the hard part, but there are a lot of great authors who provide free advice on the matter, such as Lindsay Buroker, Stephen Knight, and Dean Wesley Smith. The Amazon Kindle store, Barnes & Noble NOOK, and Smashwords have very author-friendly methods toward placing your eBook on the market. This is of course because they get royalty payments on every copy that is sold, so they would be lousy businesses if they made the process difficult for the self-publisher.

You can self-publish to the Kindle store through the Kindle Direct Publishing platform. Barnes & Noble uses the PubIt platform (US authors only). Finally, Smashwords uses their Meatgrinder and Autovetter system.

One additional tool that may come in handy as you self-publish is the eBook Publishing Quick Reference Guide by Gary McLaren [free]. He also has a freebie entitled The Beginner's Guide to eBooks, which discusses various eBook formats from a reader's perspective.

Pricing: Pricing strategy is an important aspect directly related to marketing. Smashwords allows you to distribute your eBook for free or at any price that has ".99" at the end of it in US Dollars. and Barnes & Noble do not allow you to distribute your eBook for free, and the lowest you can go is $0.99. However, if you make your eBook free at Smashwords, the Kindle store and Barnes & Noble NOOK may decide to make your eBook free. The process is a bit finicky, but it has worked for others. Royalties vary depending on how you price your eBook.

Taxes: Like death, taxes are completely inevitable, especially with the United States Government going more into debt by the day. US-based authors need to provide a Social Security Number for tax reasons, and Amazon will withhold some of your earnings. Amazon and Smashwords require international authors to obtain an Individual Tax Identification Number (ITIN). Like most bureaucracies, it takes 6-10 weeks to apply for one by mail with the United States Internal Revenue Service (IRS). The author of this guide applied for an ITIN on behalf of his Thai wife, Lisa, and her passport came back with water damage all over it.

Important Note: You should apply for only one ITIN.

Depending on your country of residence, may not withhold your earnings from sales (nominally 30%) based on existing tax treaties. Consult the FAQ for more details on how taxes work for self-publishers.

The complicated tax structure in America has made Barnes & Noble NOOK reluctant toward allowing users from outside the USA to self-publish using the PubIt platform. Supposedly, they will be opening up the NOOK store to authors from outside the USA soon, but it has been slow.

Metadata: Even though you embedded metadata into your EPUB and MOBI files, you still need to add the metadata online when you self-publish your work. This guide recommends having a set of keywords and your eBook's description ready for exactly how it will appear on the Amazon, Barnes & Noble, and Smashwords sites. Do not overlook your eBook's description, as this blurb is what the reader will see before making the decision to purchase or sample. It is also important so that readers know your book exists as they perform searches.

Cover Images: Cover images are also important to have ready when uploading your eBooks to the international marketplace. Even though the cover images were embedded inside your MOBI and EPUB eBooks, you still need to upload the JPEG file. A good rule of thumb is to use a 600x800px image for the Kindle store, 547x730px image for the Barnes & Noble NOOK, and 600x800px image for Smashwords. You can publish an eBook on all these sites without a cover image, but it is strongly discouraged.

Sales: All of these sites have comprehensive methods to track your sales on a very responsive basis. The only exception is the Smashwords sales that take place at the markets they distribute to (e.g. Kobo, iBookstore, etc.), because those markets report sales to Smashwords on a delayed basis. However, do yourself a favor and don't check it more than once a day. You will drive yourself completely mad.

ISBNs: It costs you absolutely nothing to use Kindle Direct Publishing, PubIt, and Smashwords to self-publish. Additionally, you do not need an ISBN for these three splatforms. ISBNs are automatically assigned by Smashwords when distributing to markets that require them (e.g. iBookstore).

Copyright: If you wrote the eBook, you have the copyright. You do not need to register this with the United States Government, which is where, Barnes & Noble, and Smashwords are based. This is the law. The moment you type your own original work, you have the exclusive copyright, because the law actually works in your favor.

Consult Passive Guy if you need legal services with regards to copyrights. He is a lawyer with a lot of knowledge and experience in this area, and he can help authors at a reasonable rate.

DRM: Digital Rights Management (DRM) is a terrible, no-good way to discourage piracy. Not since Crystal Pepsi have consumers so universally hated something foisted upon them. Smashwords is philosophically opposed to DRM and does not allow it for any of the eBooks sold on their website. When you upload to the Kindle store and Barnes & Noble NOOK, you have the option to use or not use DRM. You should strongly consider not utilizing DRM in your eBooks, as a courtesy to your readers. Instead of creating unnecessary hassles for the customer and fretting about someone downloading a torrent of your eBook, which will happen whether or not you use DRM, you should focus on impressing your customer and using a pricing strategy that maximizes distribution.

Publishing on the Kindle Store
Amazon has the Kindle Direct Publishing (KDP) platform that you need to register with before self-publishing. They have a Frequently Asked Questions (FAQ) section that covers every inquiry you probably have about royalties and practicalities. The only thing that is terse is the formatting section, but since you have these tutorials, that is not an issue.

Once you have setup a KDP account, add a new title from your dashboard. The process is very straightforward, and there are help pop-ups for everything you have to fill out. You only get to choose seven keywords, so make them count. Also, make sure that you don't check the option to make your eBook public domain. This means you don't have any rights to the eBook.

The important step is when you upload your MOBI file. You will have the opportunity to "Preview book", which pulls up a miniature Kindle app in your web browser. Click through the sections and make sure that everything looks the way it did in the Kindle Previewer. You may notice that the text goes right up against the edge with no margin. This is actually what you want, because the Kindle has a built-in margin that does not appear on the "Preview book" function.
Example of Proper Preview on KDP

There is a section where you set the price, and you cannot get the 70% royalty unless you set a minimum of $2.99. Any pricing below $2.99 will only yield 35% royalties. You will also have the opportunity to enable lending, which allows Kindle readers to lend your eBook to someone else for a 14-day period. At this time, only allows readers to sample the first 10% of the eBook's content for free. This is unfortunate, since most readers like to sample more of an eBook before they buy it.

Once you have finished updating your information, it takes approximately 24-48 hours before your eBook is live in the Kindle store. Be mindful of this delay if you plan on a specific date for an eBook launch. It is also advisable that you maintain an Amazon author page to tell readers a little about yourself, which will be linked to the product page of your eBook.

Publishing on Barnes & Noble NOOK
Barnes & Noble began PubIt following the success of's Kindle Direct Publishing platform. It is essentially the same concept as KDP, and it allows indie authors to self-publish with ease at the NOOK store. The royalty structure is similar to Amazon: 65% for any eBook sales $2.99 or above and 40% for any sales under $2.99. Registering an account on PubIt is a very straightforward process, and the FAQ section is helpful. At this time, you can only register on PubIt if you have a US tax ID (Social Security Number, ITIN, EIN, etc.), a US credit card, and a US bank account.

On the PubIt dashboard, click on "Add a Title". Everything in there is self-explanatory; however, keep in mind that you will need to add an author biography for every eBook you upload.

When you upload the EPUB file, it will automatically go to a mini-NOOK preview screen. Spend some time to verify that your EPUB is showing up correctly.

Example of Proper Preview on PubIt

Once you have uploaded your EPUB, expect it to go live in about 3-4 days.

Publishing on Smashwords
Obtaining an account on Smashwords is simple and open to the international community. However, publishing on Smashwords requires some additional attention, because you have to troubleshoot how your .doc file gets processed through the Meatrgrinder. Your first attempt through the Meatgrinder will most likely have some wrinkles to iron out.

To publish on Smashwords, sign in and click on the "Publish" tab. You will need to enter some metadata to include a short (<400 characters) and long (<4,000 characters) description. The cover image is required to obtain access to the Premium Catalog, and a 600x800px JPEG is recommended. You will be able to set the pricing for your eBook on this page, but it must be free or have a "$.99" affixed at the end due to the pricing policy on the iBookstore.

In regards to the formats, you have the options of making your eBook available as an EPUB, LRF, MOBI, PDF, PDB, RTF, and TXT. You should maintain the default of having the Meatgrinder convert to every available format. For some reason, uploading your .doc file with Firefox produces a strange error on the Smashwords site. If you are having problems uploading in Firefox, try using another web browser (e.g. Internet Explorer, Safari, or Chrome).

After you press "Publish", your document gets put through a queue in the Meatgrinder. In the past it took hours, but now it only takes 5-10 minutes to get all of your formats processed, depending on the time of day you are uploading. After the eBook shows up on your Dashboard, you can view the product page and download all the files for troubleshooting the Meatgrinder conversion. The files will be immediately available to the public for sale on the Smashwords site.
Various Formats on Smashwords

You will receive a notification on the Smashwords Dashboard that you have to assign your eBook an ISBN. Follow the instructions that Smashwords provides, and they will assign you a free ISBN that can be used only for Smashwords.

Autovetter errors: Within an hour, you will receive a lengthy form-generated email from Smashwords talking about your eBook being available online. At the bottom of the email, it should say if there were any Autovetter errors. Fix your .doc source file if you have any issues, because you need to have no errors to gain Premium Catalog distribution status.

Now that all the formats have been processed through the Meatgrinder, it is necessary to verify them. The most important format is the EPUB file, because it goes to most of the retailers (e.g. Barnes & Noble NOOK, iBookstore, Sony, etc.) You can use Adobe Digital Editions to inspect the EPUB on your PC. It also advantageous to validate the EPUB, just to be sure.

There are always going to be one or two problems on the first pass through the Meatgrinder. You can adjust your source .doc file, and re-publish in your dashboard by clicking "Upload New Version". It will once again go through the Meatgrinder queue and create entirely new formats. As Smashwords advises, do not publish the same eBook more than once.

Common problems with Meatgrinder conversion are as follows:

Erroneous page breaks: Try using the pagination features in Microsoft Word on your Heading 2 style.

Erroneous margins: Verify that you have set the correct spacing values in the Style Menu in Microsoft Word on each of your styles. Also, check to see that you have not accidentally declared the wrong style in each paragraph. Finally, make sure you do not use tabs anywhere in your .doc file.

Faulty NCX Table of Contents: Inspect the bookmarks in your .doc file to ensure that they are located in the correct place. When inserting a bookmark at your headings, try clicking the cursor in the middle of the heading's text, and then insert the bookmark. It is recommended that you do not select the entire heading, as this can cause bugs during the Meatgrinder conversion.

You should consult the Smashwords Style Guide for detailed troubleshooting, and don't be frustrated if it takes a few times to get it right.

Premium Catalog: To gain access to the Premium Catalog, a Smashwords team member has to look over your eBook. While this is ongoing, your eBook will say "Pending Review" under the dashboard. The review process takes about one week. If there are any problems, you will be notified via email. You should endeavor to gain access to the Premium Catalog, because that will allow your eBook to ship to all markets. Once it is approved, your eBook will say "Approved on mm/dd/yyyy".

Important Note: For the Premium Catalog, you need to make sure that you have no links to Otherwise, you get an Orwellian message saying that other eBook retailers do not like to know that exists. It is advised to not mention Amazon at all in your Smashwords .doc source file.