Feature Request: Expandable code regions

Open
#10 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
cpp
Domain
documentation

Research direction

Start by tracing how examples imported with import are processed and how the BoostBook backend renders code samples. Check whether the documentation output can support JavaScript-driven expansion, then define markup for hidden and expanded regions. Done means imported code examples can show expandable regions with the requested default visibility behavior.

Written by the indexing model from the issue text.

Description

I would like to be able to specify expandable code regions in the examples imported using import. Having that in the inline code sample would be nice, too, but not my concern right now.

The primary use case is to be able to include #includes in the code samples, hidden by default, so that users are able to view them by clicking on some marker. So, for example, by default the code sample would look like this:

+ #include ...

  void foo()
  {
    // example code here
  }

And after clicking on the "+" it would expand to:

- #include <foo>
  #include <bar>

  void foo()
  {
    // example code here
  }

I realize this would probably require some JavaScript and I have no idea if the BoostBook backend allows this at all, but the feature would be very useful in Boost.Log docs. In Boost.Log, users are asking to see the includes, but the amount of includes sometimes come close in size to the code sample itself, so I'd rather not show them by default.

There may be other cases for this feature as well, such as showing evolution of some code across several code samples, where the pieces of code added previously are shown hidden by default, expandable on click, and the new code is displayed. I'm not sure if there are cases when I'd want an expandable region shown by default, but it would probably be a good idea to have that option. I.e. the markup should probably allow a way to specify if the region has to be hidden or expanded by default.

Dominant language
C++
Stars
15
Forks
34
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from boostorg/quickbook

All issues in boostorg/quickbook

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.