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 17:48:33

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-
> bounces_at_[hidden]] On Behalf Of Edward Diener
> Sent: Thursday, September 16, 2010 6:33 PM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] [quickbook] Code block level element
> 
> 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
>
> > 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
> ?
 Yes.

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

I also believe that Doxygen comments are very useful additional
documentation - they can list the classes, functions etc *with
descriptions*.  So it's not an either/or situation but *both*.

So that standalone Doxygen docs are also useful, even if the main docs are
written in Quickbook.
For example, in getting to grips with Boost.Units, I used both side by side.

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

And don't forget that you can later produce nice pdfs easily - once you have
endured the significant hassle of getting the tool chain setup.
Copying others jamfiles is the best advice.

(The pdf format is also useful to readers (as well as html) - you can search
the whole document with Adobe Reader - a sort of substitute for an index).

Good luck.

Paul

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