The fix for bug 708060 is buggy: in particular, it doesn't always rewrite the links to images properly, so in the static docs for the online version some images don't show up. Luckily I noticed this for the 1.5 doc set and patched it for those static docs, but this ought to be fixed.
Created attachment 603115 [details] [diff] [review] Make sure all img links are rewritten; test for it; make sure tags are escaped in quoted code It seems as if Python's HTMLParser doesn't find IMG tags that are self-closed: <img alt="my picture" src="path/to/my-picture"/> ...which is what the Markdown parser will emit when presented with syntax like: ![my picture](path/to/my-picture) (Perhaps I have the wrong DOCTYPE for that to work?) So when building static docs using cfx sdocs, those IMG links didn't get rewritten, and the images were then not found. A corresponding omission from the tests meant this wasn't easily discovered. I've extended the test to cover those cases (and stolen part of the test_licenses test to make the output more helpful). I've also had to escape some "<" characters in IMG elements that were in quoted example code, so HTMLParser didn't find and rewrite those. Escaping just the IMG link in these cases didn't always work - the escaped character didn't get displayed. It seems as if I needed to escape all the preceding "<" characters to get it to work, although I don't understand why, which makes me uncomfortable with this fix...
Hm, that escaping-<-but-not-> bit does seem fishy.. is there a better way to do that? E.g. since normally HTML inside Markdown is supposed to be copied verbatim to the output HTML, and in this case we want it to appear escaped inside a <pre> block or something, maybe there's some better way to mark this HTML block? Markdown has a literal-code syntax, right?, like prefixing each line with four spaces or something? It'd be nice if we could use the markdown syntax for the IMG tags, instead of needing to jump straight to full HTML. I think I need to study the markdown translator a bit more.
So, the problem with IMG links is solved: it was because my link-rewriting code wasn't paying attention to self-closing tags. Fixing that is simple, and means that Markdown IMG elements: ![my picture](path/to/my-picture) ...work fine. The other problem is not solved. It seems to come from the interaction between the SyntaxHighlighter and Python's HTMLParser. As this link: http://alexgorbatchev.com/SyntaxHighlighter/manual/installation.html explains, there are a couple of ways of using SyntaxHighlighter: 1) wrap the code inside <pre class="brush: whatever"></pre> 2) wrap the code inside a CDATA segment. For HTML code I was using approach (2) (I think because I had problems with approach 1, but can't remember). But, Python's HTMLParser doesn't support CDATA - correctly, because CDATA is an XML thing, not an HTML thing: http://bugs.python.org/issue7114. So weird things happen. So I've tried approach (1), but have found problems with that too. According to the SyntaxHighlighter's instructions, with approach (1) I have to escape all angled brackets. But when I do this, HTMLParser seems to strip out the escaped characters completely. So given markup like this: <pre> <html> </html> </pre> ...the contents of that <pre> block as given by HTMLParser.handle_data() is: html /html Sigh. I've attached a very simple Python script to show what I mean.
Created attachment 604250 [details] [diff] [review] Another attempt OK, this patch uses the <pre class="brush: html"> approach to SyntaxHighlighter integration, escapes all "<" and ">" characters, and overrides HTMLParser.handle_entityref so as to preserve the escaping. I still don't like it very much - the handle_entityref stuff seems pretty hacky to me - but at least I have some idea what it's doing now, and it seems to work.
Comment on attachment 604250 [details] [diff] [review] Another attempt Yeah, I guess anytime you have HTML-inside-HTML you're going to run into some form of this problem. Come to think of it, some docs systems handle this by having file-interpolation/inclusion directives, where you have some markup that says "please include the contents of file X, in format Y, right here". That solves the language-A-in-language-B problem (i.e. having HTML inside your Markdown file and confusing your editor), and gives the translator enough information to know that the second file is supposed to be syntax-highlighted instead of interpreted directly. But anyways, this one looks good.
Attachment #604250 - Flags: review?(warner-bugzilla) → review+
Commit pushed to master at https://github.com/mozilla/addon-sdk https://github.com/mozilla/addon-sdk/commit/efd86a991e67eab310de0b88a308e3468b85e154 Bug 733098 - static-docs paths are broken for some images; r=@warner
Status: NEW → RESOLVED
Last Resolved: 7 years ago
Resolution: --- → FIXED
Commit pushed to stabilization at https://github.com/mozilla/addon-sdk https://github.com/mozilla/addon-sdk/commit/7384d0e0209c4e781daf669dc3f029d0919e6102 Bug 733098 - static-docs paths are broken for some images; r=@warner (cherry picked from commit efd86a991e67eab310de0b88a308e3468b85e154)
You need to log in before you can comment on or make changes to this bug.