714065 - TB: Add table of contents / jump list to Keyboard Shortcuts documentation (expose sorting/grouping/subsections)

Status: RESOLVED FIXED

(Thunderbird :: Help Documentation, defect)

Description

[Thomas D. (:thomas8)]

+++ This bug was initially created as a clone of Bug #714044 +++

STR

- look at Keyboard Shortcuts list (1), current version at time of posting (2)
- try to figure out where to look for your shortcut without reading the whole document and the whole list

Actual result / Current documentation:

- need to scroll all the way down to the end of the long list to understand the sort order / grouping / subsections of keyboard shortcuts ("Message functions", "Newsgroup Messages", etc.) 

Expected result / Improved documentation:

1a) Add linkified TOC somewhere above the list of keyboard shortcuts

Message functions
Newsgroup Messages 
Moving around Thunderbird
Writing messages
See Also

1b) Alternatively, this could be a jumplist with a dropdown, e.g.

List of Keyboard Shortcuts for [Select Topic... |v]
Then, from the dropdown, you get the list of 1a.
Selecting an entry will take you to that section (or something more sophisticated).

2) Given previous section titles...:

About keyboard shortcuts
Shortcut keys and operating systems
Customizing keyboard shortcuts

...it's not very consistent to just continue with

Message functions

Message functions what? Actually, what we mean is "Keyboard Shortcuts for Message functions". Perhaps there's a missing section headline, something like "List of keyboard shortcuts" (see 1b above).

3) Consider including section titles of 2) into a TOC at the top, so we'd have:

About keyboard shortcuts
Shortcut keys and operating systems
Customizing keyboard shortcuts
List of Keyboard Shortcuts

Or combinations of 1, 2, and 3.
Comments welcome.

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts
(2) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5138

Comment 1

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #0)
> 1a) Add linkified TOC somewhere above the list of keyboard shortcuts

The problem with just adding __TOC__ to create a dynamic TOC from existing headlines is that it creates a *huge* TOC which cannot be positioned or otherwise tamed in any way. And native HTML doesn't seem to be trivial within a wiki doc, either. Ideas?

Comment 2

[Thomas D. (:thomas8)]

Fixed with my major revision 5658 (see bug 721666).

> (In reply to Thomas D. from comment #0)
> > 1a) Add linkified TOC somewhere above the list of keyboard shortcuts
> The problem with just adding __TOC__ to create a dynamic TOC from existing
> headlines is that it creates a *huge* TOC which cannot be positioned or
> otherwise tamed in any way. And native HTML doesn't seem to be trivial
> within a wiki doc, either. Ideas?

The trick is to create your own TOC using the [[#anchor|link text]] wiki link syntax. Which will even allow for creating a horizontal TOC / linklist, which is less intrusive and less space-consuming than a vertical TOC (which will also be printed!). I added a condensed vertical TOC/linklist at the top of the article:

[[#w_about-keyboard-shortcuts|About keyboard shortcuts]] &nbsp;&bull;&nbsp; [[#w_shortcut-keys-and-operating-systems|Shortcut keys and operating systems]] &nbsp;&bull;&nbsp; [[#w_customizing-keyboard-shortcuts|Customizing keyboard shortcuts]]<br>[[#w_list-of-keyboard-shortcuts|List of keyboard shortcuts]] &nbsp;&bull;&nbsp; [[#w_see-also|See also]] 

Which will be rendered as:

_About keyboard shortcuts_  •  _Shortcut keys and operating systems_  •  _Customizing keyboard shortcuts_
_List of keyboard shortcuts  •  See also_

(I used the named html entity &bull; to create bullets within the horizontal TOC)

Of course, the same trick also works for manually creating condensed vertical TOCs:

View Keyboard Shortcuts for:
* [[#w_message-functions|Message functions]]
* [[#w_search-and-filter-functions|Search and filter functions]]
* [[#w_moving-around-thunderbird|Moving around Thunderbird]]
* [[#w_writing-messages|Writing messages]]
* [[#w_address-book|Address Book]]

(Note that headlines like =My headline= will automatically get an ID like "w_my-headline" which you can then use as an anchor for your links; don't forget test them out)

In the same manner, I also added some arrows for navigation within the long list of keyboard shortcuts, using html entities for arrows:

[[#w_message-functions|&nbsp;&nbsp;&lArr;&nbsp;&nbsp;]] | [[#w_list-of-keyboard-shortcuts|&nbsp;&nbsp;&uArr;&nbsp;&nbsp;]] | [[#w_moving-around-thunderbird|&nbsp;&nbsp;&rArr;&nbsp;&nbsp;]]

Which will be rendered as:

<= | ^ | =>

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5658(In reply to Thomas D. from comment #1)

Comment 3

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #2)
> Fixed with my major revision 5658 (see bug 721666).
> 
> > (In reply to Thomas D. from comment #0)
> > > 1a) Add linkified TOC somewhere above the list of keyboard shortcuts
> The trick is to create your own TOC using the [[#anchor|link text]]
> Of course, the same trick also works for manually creating condensed
> vertical TOCs:
> 
> View Keyboard Shortcuts for:
> * [[#w_message-functions|Message functions]]
> * [[#w_search-and-filter-functions|Search and filter functions]]
> * [[#w_moving-around-thunderbird|Moving around Thunderbird]]
> * [[#w_writing-messages|Writing messages]]
> * [[#w_address-book|Address Book]]

Which will be rendered nice and neatly as:

o _Message functions_
o _Search and filter functions_
o _Moving around Thunderbird_
o _Writing messages_
o _Address Book_ 

> In the same manner, I also added some arrows for navigation within the long
> list of keyboard shortcuts, using html entities for arrows:
> 
> [[#w_message-functions|  ⇐  ]] |
> [[#w_list-of-keyboard-shortcuts|  ⇑  ]] |
> [[#w_moving-around-thunderbird|  ⇒  ]]
> 
> Which will be rendered as:
 
  ⇐   |   ⇑   |   ⇒   

> (1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/
> 5658(In reply to Thomas D. from comment #1)

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5658