mathworks / mathworks/docmaker

Misleading error message for improper MATLAB code sections

Open
#13 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.