Repository navigation
wolfSSL manual: fix PDF build failing on backslashes in API comments - #297
Merged
Merged
Conversation
New Doxygen comments in wolfssl (asn_public.h and ssl.h, for X509_NAME_oneline) contain the text "\xHH". pandoc passes anything that looks like a TeX command through as raw LaTeX, so xelatex stopped with "Undefined control sequence" and the PDF build failed. In pdf-prep, double any backslash followed by a letter in the API reference pages, outside fenced code blocks and inline code, so it is printed literally. This covers the case generally instead of adding another one-off rule like the existing \par one. The HTML build is not affected.
Member
Author
|
@claude review |
Move the escape step into pdf-escape-backslashes.pl and address review feedback on the inline perl rule: - Keep existing Markdown escapes whole, including an already escaped "\\". The old rule doubled the second backslash of "\\x", leaving a raw "\x" for LaTeX again. - Recognise ~~~ fences as well as ``` and only close a fence with the same character and at least the same length. - Treat inline code spans by delimiter length, including spans that continue onto the next line of a paragraph. None of these cases occur in the current API output, where the only escaped text is still the three "\xHH" occurrences.
dgarske
approved these changes
Nov 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

The "wolfssl pdf" step of Docs Build Test is failing on master (for example https://github.com/wolfSSL/documentation/actions/runs/43304393323/job/131483694984):
The text comes from new Doxygen comments in wolfssl (
doc/dox_comments/header_files/asn_public.handssl.h, added with theX509_NAME_onelineescaping change, wolfssl 16ffaad4fe). The build clones wolfssl master, Doxygen writes"\\xHH"out as\xHH, and pandoc passes anything that looks like a TeX command through as raw LaTeX, so xelatex stops. It is not specific to any docs change; every PDF build fails until this is handled.Fix
pdf-prepnow doubles any backslash followed by a letter in the API reference pages (group*,*8h*), outside fenced code blocks and inline code, so pandoc prints it literally. This handles the case generally rather than adding another one-off rule next to the existing\parone. Markdown escapes such as\_or\*and code are left alone. The HTML build is not affected.Testing
builderimage) against current master of both repositories.make pdfandmake htmlboth succeed; the PDF build reports no undefined control sequences or references.\xHHoccurrences, which pandoc now renders as\textbackslash xHH.