I'd like to request linkable anchor tags or unique IDs to be used in the sub-sections of documentation pages.
I always feel a little silly linking to any huge page the specific thing I'm referencing might be on.
I don't know how the web and CHM manuals are created, but if it's in your hands, at least do something like adding auto-incrementing numeric IDs to sub-sections, tables and table rows.
This can be bandaid-fixed after the fact with some neat parsing, and going forward, by assigning meaningful IDs before publishing.
Ew, screenshots
Not searchable, not updating. But good to showcase snapshots of what might become outdated later
But in case we want to link to what ever the current documentation says: "Give me a string representation, if need be, of a doc page and I'll give you an annotated/linkable page."
- Ghandi, probably, if he had a parser and coding knowledge
Assuming no DOM IDs can be allocated upon design time:
if (Can accommodations be made to facilitate this?){
Great, do it!
}
else if (No? Reeeally? Are you sure?){ // Also applies to inserting IDs for existing documentation after the fact
// Yes, we're using proprietary 3rd party tools that don't allow for specification of DOM Element IDs
Use parser to insert IDs. Pass resulting pages through this function.
Alright, it's not all sunshine and roses. Some issues are:
- Creation of meaningful IDs
-> for $("h1, h2, h3, [...]"): use contents to create ID
-> for $("tr"): use $(":scope>td:first-child").text() to create ID
-> use
as a compromise between validity and uniqueness
- uniqueness of IDs
-> effin' append a counter id necessary, like "uh_oh_I_already_exist_3"
- Persistence throughout different doc page versions
-> Toughest problem; if push comes to shove, implement something like scroll fallbacks client-side, going through formerly used IDs for anchors
} else{
// alright, you got us. We could totally do it, but we have more important things to do
Fair.
Let the me or the community in general do it! Maybe put some of the relevant code on public gitHub?
}
Of course this is very low priority; again just me throwing my two cents into the wishing well
We don't generate the HTML/CSS; the documentation tool does that.
If you need your quote of the documentation to be searchable, copy & paste the text of the relevant sentence/paragraph. That's better than a blind link that people have to click to see the context.
The forum threads themselves will/should have enough text talking about the excerpt for people to find them via searching, so this feels like a very hypothetical issue, and using a screenshot or text excerpt with a link to the full page is going to be fine in almost all cases.
