Re: [Boost-docs] direct support for toggle-able paragraphs/sections in quickbook

Subject: Re: [Boost-docs] direct support for toggle-able paragraphs/sections in quickbook
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2015-01-08 10:24:56


> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Gennadiy Rozental
> Sent: 07 January 2015 18:44
> To: boost-docs_at_[hidden]
> Subject: [Boost-docs] direct support for toggle-able paragraphs/sections in
> quickbook
>
> Hi,
>
> In number of cases it it very convenient to have a section o the doc page
> "hidden":
>
> * to hide "fine print" most users do not need
> * short vs detailed view
> * example and its output
>
> IOW, author expect most users will not need to see this extra information and
it will
> only distract them, but it still needs to be present in some form for
"advanced" user.
>
> Is there any way to add support for something like this into QB?

I don't understand a need for this.

If you use the existing Quickbook sections, then you can (and do) make the TOC
show

Using Boost.Test
    Advanced uses
        Very advanced Use

Using Boost.Test will show

Boost.test is doddle to use.

You can see more in the section Advanced uses or Very advanced Use

(<<< these should be a hyperlinks conveniently (for re-use) using a def
__advanced link. See
http://www.boost.org/doc/libs/1_57_0/doc/html/quickbook/syntax/phrase.html#quick
book.syntax.phrase.cond anchor links).

so the user can
    Advanced uses
        Very advanced Use

and the users can click on whichever they want.

I don't see why you want to 'hide' anything?

The total size of the document is irrelevant because the navigation is all done
using the hyperlinking, both within and without the document.

Even the PDF retains the hyperlinking.

Nobody is going to read it all from start to finish!

What You Don't Click On is What You Don't See?

Examples should use snippets of the code and hyperlinks to the full code
examples

"The full code is at [@../example/simple_tests.cpp]"

The output can also be pasted at the bottom of the .cpp and made into a snippet.

But you and Raffi are doing lots of these things already?

It looks pretty good 'as-is' - *dramatically* better than before.

Expose it to public view asap?

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
+44 (0) 1539 561830

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC