--- **[tickets:#444] Texinfo is unsuitable for PDF generation** **Status:** new **Milestone:** 0.10.0 **Created:** Mon Dec 02, 2024 02:54 PM UTC by rdiez **Last Updated:** Mon Dec 02, 2024 02:54 PM UTC **Owner:** nobody OpenOCD's manual, doc/openocd.texi, yields a number of "underfull" and "overfull" warnings when generating the manual as a PDF. I am guessing that most people here have probably become accustomed to ignoring such Texinfo warnings. However, these warnings shouldn't be ignored, as they indicate rendering problems. Sometimes, the word spacing is excessive and does not look good, other times long text lines are cut off, and a solid black square is generated as a visual indication. For example, look for "lappend post_init_commands" or "for several Xilinx FPGAs" in the current OpenOCD manual for 2 black square occurrences. The trouble is, fixing those warnings is very hard. Sometimes, simple workarounds do the trick, but some other times, it's next to impossible. It is not the first time I have a got at fixing such warnings: Documentation: Fix 2 warnings "Underfull \hbox (badness 10000)" https://review.openocd.org/c/openocd/+/8264 But this time around, I couldn't manage. So I asked in the OpenOCD mailing list about it: Underfull warnings from openocd.texi 2024-06-01 20:46:09 https://sourceforge.net/p/openocd/mailman/openocd-devel/thread/19873a0f-4c6e-4484-8dc1-80656c5e4dda%40yahoo.de/#msg58778698 In the meantime, I have learned a little more about Texinfo, I have wrestled more with it, and I have asked questions in the Texinfo mailing list: Underfull and Overfull warnings for URLs and commands Fri, 1 Nov 2024 10:38:17 +0100 https://lists.gnu.org/archive/html/help-texinfo/2024-11/msg00000.html Some of the very basic shortcomings I have seen in my brief encounter with Texinfo are: - There is not an easy way to set the page size (like A4, common in Europe). - There is not an easy way to set the page margins, and they tend to be very generous. - Most indentation offset are hard-coded and cannot be customized. The solutions I have seen are not systematic, but a number of workarounds, mostly trial and error. Some of the techniques offered are not intuive and often complex or arcane. There are even memes about those "underfull" and "overfull" warnings on the Internet. Therefore, I have come to the conclusion that Texinfo is unsuitable for generating PDF documents. I do not think most of us have the time or inclination to invest so much effort in a documentation markup language anyway. The trouble with markup languages is apparently the same as with build systems: none are any good. A few years ago, I tried to find the perfect one for myself, but most of them do not allow even something as basic as "keep these lines together in a page", that is, "prevent a line break at this position". They all seem geared towards online documentation, where the screen size is dynamic and there are no physical pages. Texinfo seems especially problematic, so I think it would be worth switching to a different markup language nevertheless. AsciiDoc seems like a good compromise, but there are so many alternatives, it's hard to get an overview. Does anybody have any experience or suggestion using any other documentation language? Even if OpenOCD remains with Texinfo, it would be interesting to know. --- Sent from sourceforge.net because openocd-devel@lists.sourceforge.net is subscribed to https://sourceforge.net/p/openocd/tickets/ To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/openocd/admin/tickets/options. Or, if this is a mailing list, you can unsubscribe from the mailing list.
