Re: [Boost-docs] [quickbook] Code block level element

Subject: Re: [Boost-docs] [quickbook] Code block level element
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2010-09-16 16:29:26

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-
> bounces_at_[hidden]] On Behalf Of Steven Watanabe
> Sent: Thursday, September 16, 2010 5:10 PM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] [quickbook] Code block level element
> 
> AMDG
> 
> Edward Diener wrote:
> > I am trying to learn quickbook, so here is my first question. For the
> > 'Code' block level element is says:
> >
> > 'Preformatted code starts with a space or a tab.'
> >
> > Does this mean that 'Code' must actually start with a space or a tab ?
> > The examples in the documentation do not show it that way. So that:
> >
> >  #include <iostream>
> >
> > int main()
> > {
> >     // Sample code
> >     std::cout << "Hello, World\n";
> >     return 0;
> > }
> >
> > is a 'Code' block level element and:
> >
> > #include <iostream>
> >
> > int main()
> > {
> >     // Sample code
> >     std::cout << "Hello, World\n";
> >     return 0;
> > }
> >
> > is not a 'Code' block level element ?
> >
> > Also how does one specify the end of the 'Code' block level element ?
> 
> The whole block should be indented.
> 
>     #include <iostream>
> 
>     int main()
>     {
>         // Sample code
>         std::cout << "Hello, World\n";
>         return 0;
>     }

But see also the Phrase level way of marking code - inline, using the ` tick
(confusingly not the ' tick!)

and the `` ...``  way of marking code blocks too.

And it may seem like trouble at first to use the 'include source code
system' and put your Quickbook as comments in the actual source code, but it
will pay off in the end because the two can't get out of step so easily.
And put you sample output in another included block too.

This will all seem a struggle until you get going - but the results will be
worth it for your readers.

(And don't forget you can use Doxygen to provide a reference section too.  I
found it easier to get Doxygen working first before trying to add to
Quickbook).

Have fun!

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]