mathworks / mathworks/docmaker
Misleading error message for improper MATLAB code sections
Nobody has claimed this yet.
- Dominant language
- MATLAB
- Stars
- 9
- Forks
- 3
- Avg merge
- 13d 10h
- Merged PRs (30d)
- 2
Description
If you don't close a MATLAB code section properly, e.g. this: bug.md, where I have copy-pasted the matlab flag at the end of the section, you get this message when executing docerrun.
Warning: Error: Invalid text character. Check for unsupported symbol, invisible
character, or pasting of non-ASCII characters.
> In docerrun>runDiv (line 159)
In docerrun>run (line 109)
In docerrun (line 44)
```If you don't close a MATLAB code section properly, e.g. this: [bug.md](https://github.com/-/project/14868/uploads/36f0ed842b4138a86fb03ac4f38cc795/bug.md), where I have copy-pasted the matlab flag at the end of the section, you get this message when executing docerrun.
Warning: Error: Invalid text character. Check for unsupported symbol, invisible
character, or pasting of non-ASCII characters.
> In docerrun>runDiv (line 159)
In docerrun>run (line 109)
In docerrun (line 44)
This lead me hunting for non-ASCII characters, until I eventually spotted the syntax error.
MATLAB treats the bad close as part of the expression to be evaluated. That is what leads to the error message.
>> ```matlab
```matlab
↑
Error: Invalid text character. Check for unsupported symbol, invisible character, or
pasting of non-ASCII characters.
GitHub automatically closes the unclosed Markdown to yield valid HTML. That is beyond my control. I don't want to get into client-side parsing of Markdown to double check.
Given the resulting HTML, the error message is reasonable, if not particularly clear.
The best I could do would be to augment MATLAB errors with identifier MATLAB:m_illegal_character in docerrun. This supposes that a common type of error is to incorrectly close a code block; I'm not sure that it is.
There's a related discussion at: https://talk.commonmark.org/t/insist-that-code-fenced-blocks-are-properly-closed/232/2
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the malformed MATLAB code section with docerrun, then inspect the reported entry points docerrun>runDiv (line 159), docerrun>run (line 109), and docerrun (line 44). Determine whether MATLAB:m_illegal_character can be identified reliably and whether the resulting message should distinguish an improperly closed code section. Done requires an agreed error-handling change and coverage for this input.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- matlab
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100