Hi,
Would it be possible to turn the ANSI/ASCII tables in the CHM help file into actual proper HTML tables? i.e. <table>...</table>. Currently with the way they're laid out, they're out-of-order and it's nearly impossible for a screen reader user like myself to utilize them.
Also, I found a tiny typo in the help, I think it's probably just worth putting it here: In the PoFMT command line options, there's an extra r before the description of /o:
Quote/O
rSpecifies the name of the output file.
Thanks!
Hi Quin,
Could you be more specific? If you access the help file clicking on ANSI or ASCII tables then choose view source it shows <table ..<tr>.<td..</td>...</tr>... </table>
so it conforms, as it must, to the .chm format and is 'proper html'. It is displayed in the most common orientation found for this type of table.
Perhaps using the source you can change it, then it can be tested to be compatible with .chm (I can help with the testing). If tests ok it could then be sent to Pelle to see if he could include it as a replacement or additional page with that format.
My guess is you want 0 - 63 across the top with 8 horizontal rows (2 rows each group)
John Z
I have fixed the typo. Thanks!
Quote from: John Z on April 07, 2025, 02:36:08 PMHi Quin,
Could you be more specific? If you access the help file clicking on ANSI or ASCII tables then choose view source it shows <table ..<tr>.<td..</td>...</tr>... </table> so it conforms, as it must, to the .chm format and is 'proper html'. It is displayed in the most common orientation found for this type of table.
Perhaps using the source you can change it, then it can be tested to be compatible with .chm (I can help with the testing). If tests ok it could then be sent to Pelle to see if he could include it as a replacement or additional page with that format.
My guess is you want 0 - 63 across the top with 8 horizontal rows (2 rows each group)
John Z
Hi,
Sorry for not being more specific. You're right that it is indeed an HTML table. However, there is no <thead> tag, so screen readers are entirely missing what the columns are, and as such don't actually render it as a table.
Quote from: Pelle on April 09, 2025, 08:32:55 AMI have fixed the typo. Thanks!
Awesome, thanks Pelle! I found another one too, in the Translation phases section of the C language documentation, proceeds has an extra e in it, and is written as "The translation proceedes".
Hi Quin,
Quote from: Quin on April 26, 2025, 12:48:01 AMHowever, there is no <thead> tag, so screen readers are entirely missing what the columns are, and as such don't actually render it as a table.
Can your screen reader successfully read the attached file? If so I'll try it in a .chm file.
If it works I'll modify the other table and submit to Pelle for consideration.
It needs testing as I am not well versed in HTML :) but have done many .chm help files.
John Z
Quote from: Quin on April 26, 2025, 12:48:56 AMAwesome, thanks Pelle! I found another one too, in the Translation phases section of the C language documentation, proceeds has an extra e in it, and is written as "The translation proceedes".
English is not my native language, and there are currently three e in that word, but I guess what you say is that "The translation proceedes in the following ..." should really be "The translation proceeds in the following ...". Correct?
It is actually a tricky case. 'proceeds' in English actually means 'funds received' from a transaction.
In this case it is (improperly) trying to imply or mean 'continues', or 'goes on', most might understand the intent.
The correct (imo) sentence should be:
"The translation will proceed in the following ...".
or to remove any ambiguity
"The translation continues in the following ...".
John Z
OK, thanks. I will proceed then with "The translation continues ..." ::)
Quote from: John Z on April 26, 2025, 12:18:31 PMHi Quin,
Quote from: Quin on April 26, 2025, 12:48:01 AMHowever, there is no <thead> tag, so screen readers are entirely missing what the columns are, and as such don't actually render it as a table.
Can your screen reader successfully read the attached file? If so I'll try it in a .chm file.
If it works I'll modify the other table and submit to Pelle for consideration.
It needs testing as I am not well versed in HTML :) but have done many .chm help files.
John Z
Hi,
Yes, this reads great! Something like this for the tables in the help file would be fantastic!
Quote from: Pelle on April 26, 2025, 06:10:00 PMOK, thanks. I will proceed then with "The translation continues ..." ::)
Sounds perfect to me! :)
Hi,
This suggestion about the tables extends to far more than just the Ascii table. I see tables that aren't properly screen reader navigable in the integer constants and PoInst format of script files sections just at a quick glance. I'm assuming it's pretty much all <table> elements in the HTML.
Thanks!
Quote from: Quin on April 28, 2025, 02:50:09 AMHi,
This suggestion about the tables extends to far more than just the Ascii table. I see tables that aren't properly screen reader navigable in the integer constants and PoInst format of script files sections just at a quick glance. I'm assuming it's pretty much all <table> elements in the HTML.
Thanks!
Hi Quin:
Yes, the problem is in the <td> ... </td> instead of <th> ... </th> tags used for the header row in each of the tables. Instead of, for example,
<tr>
<td class="h">Option</td>
<td class="h">Description</td>
</tr>
the following should be used
<tr>
<th class="h">Option</th>
<th class="h">Description</th>
</tr>
A good reference for these specific accessibility concerns is this link:
https://www.w3.org/WAI/tutorials/tables/one-header/ (https://www.w3.org/WAI/tutorials/tables/one-header/)
part of the Web Accessibility Initiative of W3C, website at
https://www.w3.org/WAI/ (https://www.w3.org/WAI/)
Here is a link to a page that describes how a screen reader navigates a table.
https://tink.uk/how-screen-readers-navigate-data-tables/ (https://tink.uk/how-screen-readers-navigate-data-tables/)
Quote from: Robert on April 28, 2025, 08:03:02 AMQuote from: Quin on April 28, 2025, 02:50:09 AMHi,
This suggestion about the tables extends to far more than just the Ascii table. I see tables that aren't properly screen reader navigable in the integer constants and PoInst format of script files sections just at a quick glance. I'm assuming it's pretty much all <table> elements in the HTML.
Thanks!
Hi Quin:
Yes, the problem is in the <td> ... </td> instead of <th> ... </th> tags used for the header row in each of the tables. Instead of, for example,
<tr>
<td class="h">Option</td>
<td class="h">Description</td>
</tr>
the following should be used
<tr>
<th class="h">Option</th>
<th class="h">Description</th>
</tr>
A good reference for these specific accessibility concerns is this link:
https://www.w3.org/WAI/tutorials/tables/one-header/ (https://www.w3.org/WAI/tutorials/tables/one-header/)
part of the Web Accessibility Initiative of W3C, website at
https://www.w3.org/WAI/ (https://www.w3.org/WAI/)
Here is a link to a page that describes how a screen reader navigates a table.
https://tink.uk/how-screen-readers-navigate-data-tables/ (https://tink.uk/how-screen-readers-navigate-data-tables/)
You're awesome Robert, you somehow have more resources for this than I, the actual blind developer! :D
Hey Pelle,
Found a couple other small typos for you:
This is from the root of the Pomake docs. I think the word should be supports, with an s at the end. Original:
QuoteThe IDE only support a subset of the POMAKE syntax, for example no preprocessor directives.
New:
QuoteThe IDE only supports a subset of the POMAKE syntax, for example no preprocessor directives.
In the project files reference section of the PoMake documentation, "than" is written as "that" in this sentence.
QuoteA long line may span more that one physical line in the file by immediately preceding the newline character with a backslash (like a C source file).
Should be:
QuoteA long line may span more than one physical line in the file by immediately preceding the newline character with a backslash (like a C source file).
Finally, in the PoCert documentation, certificate is missing an e at the end in this sentence. Original:
QuoteUseful in combination with POSIGN, for example to create a certificat for testing.
New:
QuoteUseful in combination with POSIGN, for example to create a certificate for testing.
Thanks!
Quote from: Robert on April 28, 2025, 08:03:02 AMYes, the problem is in the <td> ... </td> instead of <th> ... </th> tags used for the header row in each of the tables.
Looks like around 700 tables that needs manual editing. I can only say: maybe.
Quote from: Quin on April 28, 2025, 10:49:49 AMFound a couple other small typos for you:
OK, I will try to fix them.
Quote from: Pelle on April 28, 2025, 11:26:18 AMLooks like around 700 tables that needs manual editing. I can only say: maybe.
Whoa, that's a lot of tables! Thanks for your willingness to consider fixing them Pelle, just keep in mind not all has to be done in one go :) even tiny improvements are appreciated much by us screen reader users :). I understand Pelles C is a labor of love and not of profits so doing manual work like this is probably low on the priority list :D
Hi Quin,
Quote from: Quin on April 27, 2025, 11:47:51 PMHi,
Yes, this reads great! Something like this for the tables in the help file would be fantastic!
Here is the 'real' test, Both tables modified and inserted into a .CHM file. Please test to be sure these work for you. If they work, I'll post the revised table files for Pelle to consider using. If he agrees and has the time, he is very busy getting another release candidate ready, they might be in the next release.
It is posted as a 7z file because in some cases download .chm files are prevented or require unblocking. Also note that .chm files do not work well if on a network drive, local drive only.
John Z
I just read the prior postings on this - looks like there may be an easier way. td vs th but I don't know that all tables have a header row, these two did not afaik....
Well please test anyway just so I know.
Hi John,
yep, these read perfectly as well! :)
Thanks for all your work!
Hi Quin,
Please test this help file. It uses the alternative suggestion replacing all 'td' with 'th'.
If this does work for the reader is probably is easier to do than adding a <thead> </thead> section.
John Z
Hi John,
Yes, this is recognized as a table, but it's not perfect. The table headers are recognized as the top item in the header, and my screen reader announces these when I switch columns. SO, for example, in the ascii table, the column label for column 9, no matter what row I land on, is "128". I think this is why the <thead> elements are so useful. I understand that adding the <thead> elements is a huge undertaking though, and would be more than happy to have the tables looking like this in the next version of the help file, and have the <thead> elements added more slowly over time, if Pelle desires.
Hi Quin,
The two tables I've used for testing had no column titles/headers at all, so the for the first test I added them, then for the second test I just used what was there.
I looked in the help file further and see many tables do have headers even though they are not defined as such. So I'll do one more test on one of those that already has a header but is not using <th .
If global replaces works well on it then it might still be possible to use search & replace en mass, and not a big edit job adding <thead> </thead>.
Will post for testing when done,
John Z
Hi Quin,
Next test help file attached. I do notice visually that changing all <td to <th results in all bold text. So that is a drawback.
There are two version of two different files. _top means only the top <td changed to <th and in both of these files the top was actually a header for the rest. Entries with _all used a global search and replace.
I found 662 tables in 473 files approximately. Unfortunately it appears the best way will be to edit each individually. Global search and replace isn't going to give great results for everyone.
John Z
Hi John Z,
Thanks for your work! Both versions read the exact same to my screen reader in terms of the columns :)
The one thing I noticed though is that the Associativity column only has a value in the first row for every section, not every row. Is this intentional?
Hi Pelle,
Got a few more typos for you:
In the CC reference: "Pelles compiler driver coordinate the execution of" should be: "Pelles compiler driver coordinates the execution of".
In the C Constant expressions section: "Such a constant expression evaluate to one of the following" should be: "Such a constant expression evaluates to one of the following".
In the C declarations section: "A declaration declare at least a declarator, a tag, or the members of an enumeration." should be": "A declaration declares at least a declarator, a tag, or the members of an enumeration."
Thanks!
Quote from: Quin on April 30, 2025, 05:12:54 PMHi Pelle,
Got a few more typos for you:
Hi Quin,
OK, I will fix them. Thanks.
Quote from: Quin on April 30, 2025, 04:48:52 PMThe one thing I noticed though is that the Associativity column only has a value in the first row for every section, not every row. Is this intentional?
Yes that is how the table appears, in a given section where the Associativity is the same it is only listed on the first entry of the table section.
John Z
Quote from: John Z on May 01, 2025, 02:32:59 PMQuote from: Quin on April 30, 2025, 04:48:52 PMThe one thing I noticed though is that the Associativity column only has a value in the first row for every section, not every row. Is this intentional?
Yes that is how the table appears, in a given section where the Associativity is the same it is only listed on the first entry of the table section.
John Z
Ah I see, thanks for the clarification!
Hi Pelle,
Thanks for your improvements in V13 RC3, although I am sad to inform you that it didn't quite do what I wanted. It seems you did something slightly different from John Z, and now "ASCII Character Table" is reported as the column header for every row.
I also found two more typos:
Under the description heading for PoFMT's /s option, formatting is missing a T: "The /S option specifies the formating style." should be: "The /S option specifies the formatting style."
In the Pomake dependnencies documentation, the word "build" is written as "built". "The name of one or more targets, separated by spaces or tabs. The name can be a pseudotarget or a file to built." should be "The name of one or more targets, separated by spaces or tabs. The name can be a pseudotarget or a file to build."
Thanks!
EDIT:
It actually did improve a looot of the tables. For example, I had no idea that all the macros declared in something like <cpufeat.h> were supposed to be in a table; my screen reader simply didn't render them.
So Pelle, you actually did make a lot of improvements. Just the ASCII and ANSI tables, as well as any table with the same static text as its entire column row, are the only ones currently in need of fixing :)
NVDA screen reader is free for downloading.
https://www.nvaccess.org/download/ (https://www.nvaccess.org/download/)
Hello Quin,
Quote from: Quin on May 06, 2025, 07:52:37 PMI also found two more typos:
OK. Thanks.
Quote from: Quin on May 06, 2025, 07:52:37 PMSo Pelle, you actually did make a lot of improvements. Just the ASCII and ANSI tables, as well as any table with the same static text as its entire column row, are the only ones currently in need of fixing :)
The ASCII and ANSI tables are just listing all the numeric values with it's corresponding character. Not terribly interesting. Trying to make these tables more friendly to screen readers will likely make them unreadable to everyone.
Do you actually have an example of a "table with the same static text as its entire column row" ?
Hi Pelle,
Yes, the ascii table is the example :)
The column text for every single column in that table is "ASCII Character Table", same as the heading right above it.
These aren't needed column headers, so you can safely remove them. I'm not sure if it'll break screen readers being able to navigate the table, though.
if it helps here are the two I modified.
John Z
Yup, and John Z's versions read how I expect them to :)
Quote from: John Z on May 07, 2025, 05:15:58 PMif it helps here are the two I modified.
Sorry, this looks worse to me (not being blind).
Except for any typos, I'm very much done with this topic for now...
Quote from: Pelle on May 08, 2025, 02:15:09 PMExcept for any typos, I'm very much done with this topic for now...
Understood -
Well that is my fault. I was just testing how to make the change not thinking about a final look.
I'm sure your help file is still more usable for the screen reader now than before.
John Z
Quote from: John Z on May 08, 2025, 05:28:22 PMQuote from: Pelle on May 08, 2025, 02:15:09 PMExcept for any typos, I'm very much done with this topic for now...
Understood -
Well that is my fault. I was just testing how to make the change not thinking about a final look.
I'm sure your help file is still more usable for the screen reader now than before.
John Z
Oh it definitely is, and that is certainly much appreciated.
I wonder if we could achieve the wanted look with CSS? I know nothing about how it looks though so...
Hi Quin,
Yes Pelle already uses CSS for his help file. I did not include it when creating the test file for the headers.
John Z
Quote from: John Z on May 09, 2025, 11:33:03 AMHi Quin,
Yes Pelle already uses CSS for his help file. I did not include it when creating the test file for the headers.
John Z
Hi,
No, what I meant was I wonder if we can add the columns like you had, and then use CSS to style them.
Hi Quin:
The Pelles Help file already uses CSS to style the tables, including the headers.
Missing components, regarding navigation with a screen reader, are the
<thead> ... </thead>demarcation tags enclosing the headers and the
<tbody> ... </tbody>demarcation tags on the rest of the table.
I suspect that a regex search and replace utility like DnGrep
https://dngrep.github.io/ (https://dngrep.github.io/)
could add the missing components.
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/thead (https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/thead)
https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tbody (https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/tbody)