respec
respec copied to clipboard
w3c
add self-link to tables
As can be seen in the comment thread linked below, it would be nice that the tables that now have numbers, could also have a link in the caption (Table 1: My Table) where Table 1 is a link itself to the table.
Answers to the questions asked:
1.) It is a new feature in my opinion
2.) I think that it should be enabled by default for all table (like for examples). However, I think that might result in too much change and would change the tables in all w3c specs. As a fallback, I think that the setting should be a global one in the respec config. I think that if some tables do not have this and some do, it would be weird.
3.) the setting can be just "linkedTables":true . I do not have a strong preference on this.
Would you mind opening a bug in ReSpec, including me, and asking: 1.) If this is a feature that should be added, 2.) If a global setting is ideal, and 3.) What that setting should look like?
BTW the code that generates links to figures and tables is here: https://github.com/w3c/respec/blob/main/src/core/anchor-expander.js#L76 and here: https://github.com/w3c/respec/blob/main/src/core/anchor-expander.js#L100
We'll likely share code with that.
Originally posted by @ProgramMax in https://github.com/w3c/wot-thing-description/issues/1256#issuecomment-1210963070
Some relevant code: https://github.com/w3c/respec/blob/471d6f5b20aab17e0b9db969418ef53f4b568d4c/src/core/id-headers.js#L48-L53
I am happy to work on this. But before I do, I want insight from the ReSpec maintainers to say this is indeed the correct path forward.
Currently, the table captions (including "Table ##") are not links. The first post here suggests figure captions are links. But I am not seeing that. Am I missing something?
The first post here suggests figure captions are links. But I am not seeing that. Am I missing something?
Sorry about this, I wanted to say examples. I will edit the first comment to reflect this
Ah. Okay, I do indeed see that example titles are links.
In that case, if we linkify the table captions, we should probably also linkify figure captions.
They aren't links as of now. The feature request suggests we make them (self) links.
I'm not in favor of adding a new config option for that. Maybe a class attribute would be better (as we've a .nolinks already). We should use styles similar to what we've for headings though.
Though, I wonder if a self-link on table captions could be too many links on page. We've section#list-of-tables where tables are linked, maybe that should be enough?
Each section self-links. But the section title itself is not a link. Instead, the section is preceded by §, the section symbol. This symbol is the self link.
Stylistically, this is in contrast to how examples self-link.
I do not know of a common symbol used for figures, examples, and tables. I am not a designer so take my design opinion with a grain of salt. But I think the entire title being a self link is a bit off. I feel like self-linking via some symbol would be cleaner.
Perhaps we could reuse the §? It conflates the meaning of section. But it maintains the idea of a self-link symbol.
What do other specs do?
I follow the C++ spec. I checked to see what they do. The spec itself does not self-link like this. However, there is a site that maintains a more web-friendly version: https://eel.is/c++draft/lex.ccon#tab:lex.ccon.literal You can see they self-link via the number part of "Table ##". But then they also include a self-link of the form "[tab:section name.table name]". Figures are the same but with "fig": https://eel.is/c++draft/class.mi#fig:class.nonvirt
I have seen the usage of § in other places so using this consistently would be a good and consistent design choice in my opinion
I agree. The design of ReSpec's section self-linking with the § is pleasant. I am in favor of mimicking that style.
To respond to the points @sidvishnoi made: We have a list of figures and a list of tables. But no list of examples, right? Coincidentally, figures and tables do not self-link but examples do.
I think we should be consistent across tables, figures, and examples.
I don't lean one way or another on how we become consistent. Maybe none of them should self-link and there should be a list of examples added. I am okay with that. But it sounds like @egekorkan prefers we instead self-link. (We should still add a list of examples if we choose the self-link route, I think.)
@egekorkan Could you elaborate on why you want self-linking, if you do? Is it for consistency?
So my use case is to allow linking to "stuff" in the specs. For example, I want to create an issue saying that this example/figure/table is wrong. When we do it without link, we have to say 2nd table in section 3.1.2. We can instead say table 32 but without a link, that number isn't reliable over long periods. The specs change and it's not uncommon to see issues that are open for a couple of years and link to various examples/figures/tables.
Another direction could be that respec does some checks when the document is loaded and gives warnings when an example/figure/table doesn't have an id (or anything that cab help for creating a link)
That makes sense to me. Even with a list of tables providing a link and an id on the table, that puts an awkward burden on the person trying to link. It would be much easier for everyone if there was some form of self-linking.
@sidvishnoi You mentioned concern of generating too many links. Do you think the convenience of self-linking outweighs the link count?
I think we should go ahead with self links on all tables with captions (numbered or not). If someone complains about too many links, we can consider adding some config options (opt-in or opt-out; per spec).
Although, § should probably be used only for sections (as it is "section sign"). Maybe we can use # or ¶ for other permalinks. Not really sure.