Improve readability and glancability of docs in README.txt

[claremacrae]

Expected Behavior

That it's easy to search text, and see the whole structure, of the docs on the front page:

https://github.com/boost-experimental/ut

Actual Behavior

• Most sections on the front page are collapsed, and some require two levels of expansion of triangles to see the content
• Searching in the browser (Ctrl+F) doesn't find text in collapsed sections
• I've seen someone who is more familiar with UT than me still click on 2 or 3 triangles before finding the code example they wanted to show me

Specifications

• Testing in both Firefox and Chrome (Windows 10)

Suggestions

• Perhaps provide a button at the top that opens all the triangles all the way down
• Or just remove the triangles and collapsing altogether

[krzysztof-jusiak]

Thanks, @claremacrae for pointing that out.

Fixed by c74fb33

[claremacrae]

Thanks @krzysztof-jusiak - having seen the result, I think it would really benefit from a table of contents now, ideally including levels 1 and 2, so users can quickly see the structure, and still jump to bits they are interested in.

[claremacrae]

I don't really understand the intention of 02ca5a4 - but it seems to have reverted the fix for this issue - almost all the sections are closed again, as far as I can see, so I think this issue should be re-opened.

[claremacrae]

Here are some examples of tables of contents in Markdown pages - so the full text is searchable on the page, and users can quickly see the structure and type of content, and also jump to a particular section very quickly:

• https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md
• https://github.com/approvals/ApprovalTests.cpp#top

[claremacrae]

I don't really understand the intention of 02ca5a4

Ah right, now I understand - it has almost reverted to the original behaviour, but it has opened the sections that have sub-sections...

So users can see the sub-section titles, but the original issue of not being able to search the whole page (unless you expand every single section and sub-section) has returned.

[claremacrae]

What's the benefit of the expanding sections?

Could they be replaced with a traditional <h1>, <h2> etc, with a <ul> for Table of Contents at the top?

[krzysztof-jusiak]

Thanks for your input @claremacrae.

Yeah, I'm still experimenting with it with the following goals in mind 🤔

• Easy to search (basically one page, it's usually more difficult to find things where they are spread around multiple Markdown files)
• Easy to navigate (:new: top menu)
• Easy to hide details (sections)

I pushed a change to expand all sections (they can still be collapsed) and added a top menu.

[claremacrae]

I pushed a change to expand all sections (they can still be collapsed) and added a top menu.

I like it!!!