Gentle persons:
Roughly two months ago, there was a brief spat of email traffic about
LinuxCNC documentation not building on stable Debian.
Since the horrific events in my life earlier this year I've lost my zeal
for editing LinuxCNC documentation. On the other hand, I have been
building LinuxCNC on Ubuntu Precise, Ubuntu Raring, Debian Wheezy (e.g.,
stable), and Debian Jessie (e.g., sid) and it keep bugging me that I
couldn't build the docs across the board. They build on Precise but not
on the other three. It's not a critical matter for me since I can always
build them in Lucid or Precise or download them from Linuxcnc.org, but,
like I said, it bugged me.
I spent some time this afternoon and have managed to move the ball
closer to the goal line. I can now build all the English-language pdfs
on all the above-named O/Ses. Building French-language pdfs still fails,
but the information here should help some enterprising person fix that
too, iterating through the different language versions as necessary.
The following is taken from a Debian/Wheezy system working on my pull
today from origin/master on git.linuxcnc.org.
The clue came from the tail-end of the make output:
pdflatex -interaction=batchmode Master_User.tex
pdflatex failed
Master_User.tex:10280: Package utf8x Error: MalformedUTF-8sequence.
Master_User.tex:10280: leading text: G10 L2 P1 X3.
Master_User.tex:10280: Package ucs Error: Unknown Unicode character
65533 = U+FFFD,
Master_User.tex:10280: leading text: G10 L2 P1 X3.
Master_User.tex:10280: Package utf8x Error: Character160appearedalone.
Master_User.tex:10280: leading text: G10 L2 P1 X3.
The last five lines repeat two more times; then there are six
occurrences of the following, similar error:
Master_User.tex:10280: Package utf8x Error: MalformedUTF-8sequence.
Master_User.tex:10280: leading text: G10 L2 P1 X3.5 Y17.
Master_User.tex:10280: Package utf8x Error: Character160appearedalone.
Master_User.tex:10280: leading text: G10 L2 P1 X3.5 Y17.
Finally, we get
A possible reason for transformation failure is invalid DocBook
(as reported by xmllint)
Error: pdflatex compilation failed
I stared at the error lines while the coffee was brewing and realized
they must be complaining about some examples of G-code usage.
I took a look at docs/src/gcode/gcode.txt and sure enough, there are two
G-code example lines which seem to correspond but which looked fine to
my eye (line numbers are not in the source file of course):
654 .G10 L2 Example Line
655 [source,{ngc}]
656 ----
657 G10 L2 P1 X3.5 Y17.2
658 ----
659
660 In the above example the origin of the first coordinate system
661 (the one selected by 'G54') is set to be X=3.5 and Y=17.2.
662 Because only X and Y are specified, the origin point is only moved
in X and Y;
663 the other coordinates are not changed.
664
665 .G10 L2 Example Line
666 [source,{ngc}]
667 ----
668 G10 L2 P1 X0 Y0 Z0 (clear offsets for X,Y & Z axes in coordinate
system 1)
669 ----
Funny, though, I didn't get a hit on lines 657 and 668 in this file
grep'ping on 'G10 L2'. Aha! We know what that means. Sure enough, there
are multiple nonbreaking spaces in line 657 and in line 668. The
multiple occurrences account for the repetition in error messages,
although there isn't a one-to-one match with the
"MalformedUTF8-sequence" messages, presumably due to the way the parser
eats its input.
I edited the file to replace those nonbreaking spaces (vim command :as
reports they are ASCII decimal 160 or hex a0; in UTF-8 they would be
\xc2\xa0) with spaces (ASCII decimal 32 or hex 20) and rebuilt the docs.
Voilà. The make process now chews through all the English-language pdfs
but then breaks on the first French-language document,
Master_Getting_Started_fr.pdf, emitting similar errors. This is true on
Ubuntu Raring, Debian Wheezy, and Debian Jessie.
There are lots more nonbreaking spaces in the documentation source files
(even a few in gcode.txt) which do not cause heartburn for our
toolchain. That says to me it is the occurrence of the nonbreaking
spaces within the particular asciidoc construct used to create example
lines which creates the problem. This should be a sufficient clue for
the proverbial interested student to explore the config and style files
used to build the documentation. Why is it the newer versions of the
tools in the chain which break? Don't know. I've could make an educated
guess but then I'd feel obligated to diddle.
I'm not going to clean up the documentation source files but really, no
"extended ASCII" characters should exist in them, even if they slip
through. Use the necessary markup.
There may remain problems with other language character sets, of course,
but presumably those would be UTF-8 problems more amenable to solution
through the normal forums devoted to the documentation tools.
Regards,
Kent
PS - For the cognoscenti, here are relevant software versions in the
order Precise / Raring / Wheezy / Jessie
asciidoc: 8.6.6 / 8.6.7 / 8.6.7 / 8.6.7
dblatex: 0.3.2-2 / 0.3.4-3 / 0.3.4-2 / 0.3.4-3
pdflatex: 3.1415926-1.40.10-2.2 / 3.1415926 -2.4-1.40.13 /
3.1415926-2.4-1.40.13 / 3.1415926-2.4-1.40.13
(Donald Knuth said the version numbers of his TeX software should/would
asymptotically approach pi. Once a mathematician, always a
mathematician, especially when joking.)
------------------------------------------------------------------------------
October Webinars: Code for Performance
Free Intel webinars can help you accelerate application performance.
Explore tips for MPI, OpenMP, advanced profiling, and more. Get the most from
the latest Intel processors and coprocessors. See abstracts and register >
http://pubads.g.doubleclick.net/gampad/clk?id=60135991&iu=/4140/ostg.clktrk
_______________________________________________
Emc-developers mailing list
Emc-developers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/emc-developers
