Page MenuHome

modifications to allow compilation of PDF manual
Closed, ResolvedPublic

Description

Currently, the PDF manual cannot be created without modifying the sources. This modification changes the sources to allow latex to work on it. The html manual remains unchanged. Below is a list of changes.

  1. patch some files in exts directory to tell sphinx to ignore vimeo and youtube videos.
  2. In image file names, dots that do not represent file extension are replaced with "_dot_". rst sources are modified and some image files are renamed for this.
  3. some jpg images do not have dimensions. I have added dimensions to them. If this is not done some images will appear oversized in the PDF.

There are 12 gifs in use and all are animated. Those gifs are included in the .tex file, but if you ignore the errors due to those files, the PDF can be compiled.

I am using the following commands to compile the PDF.
sphinx-build -b latex ./manual ./latex
cd latex
pdflatex -interaction nonstopmode blender_manual.tex # 3 times

The tarball of the modified repository and the compiled PDF is available here:
https://www.dropbox.com/sh/rvt5nld2f7fj1p3/AACf14A4q8ESltKvl79vywgWa/blender_manual.pdf?dl=0



Details

Type
Patch

Related Objects

Event Timeline

Teo Guo Ci (guoci) added a project: BF Blender.
Teo Guo Ci (guoci) set Type to Patch.
Teo Guo Ci (guoci) created this task.
Teo Guo Ci (guoci) raised the priority of this task from to Needs Triage by Developer.

Thanks for looking into this.

Are you interested to have commit access to the manual to help maintain this?

Details below:


I've committed changes to svn based on your edits:

  • Mostly the _dot_ in the names were redundant so replaced with -.
  • Removed strange characters from images.
  • Set all jpeg's to 72dpi (using exiftools so no resaving).
  • Added back PDF target to makefile, using -interaction nonstopmode as you suggested.

There are some remaining issues though, so I wouldnt consider the PDF quite finished/complete yet.

1Package longtable Warning: Table widths have changed. Rerun LaTeX.
2
3[1537] (./blender_manual.aux)
4
5Package rerunfilecheck Warning: File `blender_manual.out' has changed.
6(rerunfilecheck) Rerun to get outlines right
7(rerunfilecheck) or use package `bookmark'.
8
9
10LaTeX Warning: There were undefined references.
11
12
13LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.
14
15 )
16(see the transcript file for additional information){/usr/share/texmf-dist/font
17s/enc/dvips/base/8r.enc}</usr/share/texmf-dist/fonts/type1/public/amsfonts/cm/c
18msy10.pfb></usr/share/texmf-dist/fonts/type1/urw/courier/ucrb8a.pfb></usr/share
19/texmf-dist/fonts/type1/urw/courier/ucrr8a.pfb></usr/share/texmf-dist/fonts/typ
20e1/urw/courier/ucrro8a.pfb></usr/share/texmf-dist/fonts/type1/urw/helvetic/uhvb
218a.pfb></usr/share/texmf-dist/fonts/type1/urw/helvetic/uhvbo8a.pfb></usr/share/
22texmf-dist/fonts/type1/urw/helvetic/uhvr8a.pfb></usr/share/texmf-dist/fonts/typ
23e1/urw/helvetic/uhvro8a.pfb></usr/share/texmf-dist/fonts/type1/urw/times/utmb8a
24.pfb></usr/share/texmf-dist/fonts/type1/urw/times/utmbi8a.pfb></usr/share/texmf
25-dist/fonts/type1/urw/times/utmr8a.pfb></usr/share/texmf-dist/fonts/type1/urw/t
26imes/utmri8a.pfb>
27Output written on blender_manual.pdf (1539 pages, 38938838 bytes).
28Transcript written on blender_manual.log.
29Makefile:58: recipe for target 'blender_manual.pdf' failed
30make[1]: *** [blender_manual.pdf] Error 1
31make[1]: Leaving directory '/src/manual/build/latex'
32Makefile:60: recipe for target 'pdf' failed
33make: *** [pdf] Error 2

I will like to have commit access and will look into the issues you have mentioned.

in the PDF if they link to videos on YouTube would be an asset to the visualization.

yes, in my old wiki-to-pdf manual, I did something like that. It was a horrible hackish php script though... the result was not so great... but I hosted also translated versions, here: https://archive.org/details/BlenderWikiPDFManual

I just grabbed the video url using a regexp and then inserted a link instead, pointing to the url.

Thanks so much for bringing pdf manual to blender users...!


I updated the PDF after resolving the issues. Modified the generated tex file only, so nothing to commit. Link to pdf:
https://www.dropbox.com/sh/rvt5nld2f7fj1p3/AADMgOuj57J7N4XfCjsgV50ba

@Teo Guo Ci (guoci), manually updating the PDF isn't really an option long term.

Can you note what you changed in the TEX file, so there is a possibility to automate it?

@Campbell Barton (campbellbarton)
Please see the attached script.

I tested rst2pdf. It did not succeed for the full documentation.

The output of the first chapter looks like this.
It includes bookmarks.

@Matt Nelsen (teo) Guo Ci
Maybe parts of it can be done via sphinx extension ?

@Gyro Gearloose (pink.vertex)
I used sphinx with pdflatex to generate the pdf, not rst2pdf. You can see the generated pdf in the link below.
https://www.dropbox.com/sh/rvt5nld2f7fj1p3/AADMgOuj57J7N4XfCjsgV50ba?dl=0

@Teo Guo Ci (guoci)

I know. It was just a test to see wether rst2pdf would work out of the box and wether the result would look better.

Modified the .tex file generation via sphinx extension and pdflatex exits without errors now (someone else might test this). I did not deal with the unicode characters.

Only intended to build without errors. There might be some things missing now in the final result because they don't work with latex, like figures in figures (i.e. modifiers/simulate/particle_instance.rst)

It turns out replacing the unicode characters in the extension is rather easy.

from sphinx.util.texescape import tex_escape_map, tex_replace_map
#...

def setup_latex(app):
    if app.builder.name == "latex":
    #...

        substitutes = "\\ding{51}", "\\ding{51}", "\\ding{55}"
        for char, substitute in zip("✓✔✗", substitutes):
            tex_escape_map[ord(char)] = substitute
            tex_replace_map[ord(char)] = '_'

Add the package in conf.py

# Additional stuff for the LaTeX preamble.
  'preamble': '\\usepackage[left=0.75in, right=0.75in, top=1.0in, bottom=1.0in]{geometry}\n'
              '\\usepackage{pifont}',

Tables with images get screwed. Some who knows latex better than me might fix this.

Did anyone look into having images show in tables?

As far as I can see this is a show-stopper, since we have this reasonably often.
We could always remove, but having images side-by-side is quite reasonable thing to do.

If theres no solution for that, we can consider PDF generation incomplete ~ (report to sphinx developers, and only look into it again if they resolve the problem).

Also, if theres fixes to existing PDF generation, please provide a diff instead of code-snippets. eg: svn diff > pdf.patch, they can be attached or linked to.

@Campbell Barton (campbellbarton)
I used the script attached to modify the sphinx generated .tex file before compiling with pdflatex. The images in tables do show up in the pdf.

make pdf still exits with an error . However

cd ./build/latex
pdflatex -interaction=nonstopmode blender_manual.tex

does not.

Also in the log file blender_manual.log there are no more errors. Just warnings about floats too large and undefined references.
So the makefile might need some fix?

I removed the entries from the index.rst file because these are already defined in the subfolder below which caused duplication in the .tex file.

This extension currently splits rows in image tables with figures into two rows, where the first row contains the images, second one contains the captions.

Does not look that good and might be improved by using a latex package like subfig or subcaptions. Did not look into that, yet.

Can someone please write an updated patch and give instructions on how to build the PDF version.

Thanks

Aaron Carlisle (Blendify) closed this task as Resolved.Aug 11 2016, 9:59 PM

Images are done. We are just wait for sphinx's PDF compiler to mature