Experimental Physics and
Industrial Control System

Hi,

 

Notice: this is about documentation…the boring stuff. You have been warned.

I noticed just today that my recent builds on readthedocs.org had failed, and to my horror already weeks ago. I had not even noticed because the docs seemed to have appeared on the docs.epics-controls.org website. But something was still wrong.

 

I started to look at what had happened. I could track down the commit tha caused the build failures to begin but was puzzled because the commit seemed rather innocent.

 

Finally I was able to track the reason to pdflatex producing too many errors because it could not handle “ligatures” in the UTF-8 files.

Ligatures???

 

With some googling I learned that ligatures in this context are replacements of character sequences with codes in UTF text. New to me but maybe this was blatant ignorance.

They had appeared in the rst files when I converted some html (from App Dev guide) to rst, with pandoc.  I did not notice the escape sequences in the editor as it rendered them transparently like normal text.

I started to fix those but still got a lot of failures.

 

What I learned then was that the build system tries to autocorrect these failures and the build goes through until the number of errors is exceeded. Earlier I had just looked that the build was successful but did not go to look at the details and thus did notice that the errors had been accumulating, and the innocent-looking commit just caused enough new errors that the build failed.

 

Finally I got all the ligatures rooted out and the build succeeded. But as I by now had learned to look at the full build log, I noticed that there were also a bunch of other problems that I had not noticed. For instance, sometimes the auto-fix resulted in text being dropped out and I had not even noticed those before.

 

Also, to fix the ligature issue I had to use another editor instead of my “human-stupidifier” editor that just was hiding the problem and had no tools to fix it.

 

I learned these three things:

-pay attention to the warnings, even those that look benign (I should have known this already)

-“nice” modern tools can be deceptive (I should have known this as well…)

-I know one new meaning for “ligature”.

 

Timo