Unity manual to eBook

Steps and a script to reformat the Unity3d user manual to an eBook-friendly html files.

Download the offline manual

Download the offline documentation from the unity3d page. For example: 2018.2

 wget https://storage.googleapis.com/docscloudstorage/2019.2/UnityDocumentation.zip
 unzip UnityDocumentation.zip -d /tmp/unity/
 cd /tmp/unity/Documentation/en

Convert images

This is an optional step. Not needed if you are using a device with full capable web browser.

There are jpg, png, gif, svg and pdf files included in the manual. I wanted all the images to be grayscale png files for my Kindle reader.

Convert svg with the Inkscape:

find . -name "*.svg" -exec inkscape -z -e {}.png {} \;

Convert jpg with ImageMagic's convert:

find . -name "*.jpg" -exec convert -verbose {} {}.png \;

The same for the gifs. Since the gif files are animated the convert will create multiple numbered png files for each frame. The Groovy script can deal with this but it takes only one frame from the animation.

find . -name "*.gif"  -exec convert -verbose {} {}.png \;

Convert all the pngs to grayscale with the pngcrush.

find . -name "*.png" -exec pngcrush -brute -l 9 -rem gAMA -rem cHRM -rem iCCP -rem sRGB -rem alla -rem text -c 0 {} {}.png \;

As an alternative the mogrify from the ImageMagic can be used too. But it would produce bigger images. The pngcrush is slow. It takes more than 30 minutes to convert all the pngs on an average pc. But the resulted images (after bit-depth reduction and grayscale) are 3x-5x times smaller.

#find . -name "*.png" -exec mogrify -verbose -type Grayscale -depth 8 -quality 9 -format png {}  \;

Note all the above commands (except the last one ) will produce a copy of the file with multiple extensions. Like foobar.svg.png.png. The Groovy script updates all the image links while prefering the longest file name. So the foobar.svg.png.png will be used instead of the original foobar.svg

Run the Groovy script

The ManualProcessor.groovy script:

• Parses the TOC file to recognize order of the pages .
• Linearizes and removes unnecessary content from each page.
• Concatenate multiple pages into single html file.
• For each first level chapter creates a new html file.
• Makes sure there are not too many pages in single chapters file.
• Add number prefix for each file so the order is obvious.
• Ensure the img links are correct after above image conversation.

To get the script simply clone this repo or just:

wget https://raw.githubusercontent.com/Premik/UnityManualEbook/master/UnityManual.groovy

• Get and install Groovy
• Review the Groovy script. At the top there is Param class. If you are going to use a web-browser for reading set the removeLocalUrlLinks = false to keep the local links. It is set to false by default to avoid Calibre from nesting all the referenced pages into eBook making hudge files.
• Run the script inside the unziped folder Documentation/en/:

groovy UnityManual.groovy

It will produce a new Manual-flattened folder with the linearized html files beside the original 'Manual' folder:

• Manual
• Manual-flattened
  • 01-UnityManual-partA-UnityManual.html
  • 02-UnityOverview-partA-UnityOverview.html
  • 02-UnityOverview-partB-AssetStore.html
  • 02-UnityOverview-partC-PresetLibraries.html
  • 03-ImportingAssets-partA-ImportingAssets.html
  • ...
• ScriptReference
• StaticFiles
• StaticFilesManual
• upload

Calibre

• In the Calibre import all the html files from the Manual-flattened folder as individual books. Or just drag them to the library view.
• Convert them to the desired format. I used AZW3 aka KF8 for my Kindle as the Mobi format had problems placing the images on proper location.
• The total size of the User Manul in the AZW3 format in may case was slightly over 90MB.

Limitation

• Current the process doesn't work for the ScriptingManual. Probably the html structure is slightly different to the User Manual one so the script removes too much. Perhaps I'll fix this once I'm done reading the User manual..