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

Subject: Re: [Boost-docs] [quickbook] Code block level element
From: Edward Diener (eldiener_at_[hidden])
Date: 2010-09-16 17:32:45

On 9/16/2010 12:29 PM, Paul A. Bristow wrote:
>
>
>> -----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.

I am aware of those others. Thanks !

>
> 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.

I am not sure what you mean by the 'include source code system'. To 
which markup are you referring ? The [import somefile] for using code 
snippet markups ?

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

Understood.

>
> (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).

I intend to use doxygen comments and then the [xinclude somefile.xml] to 
bring them in as the reference section.

>
> Have fun!

I am sure I will thanks to Quickbook. Docbook/Boostbook is too 
troublesome a learning curve to want to tackle right now !