Re: [Boost-docs] Query regarding boostbook and documentation

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-05 00:38:17

On 1/4/16 2:42 PM, Soul Studios wrote:
> I appreciate all the interest in the topic, however none of these posts
> actually answer my questions.
> Robert, I would love to use XMLMind but the cost is prohibitive.

Note that www.blincubator.com has a link to a free personal version. 
This version is no longer supported but it still works fine.  It's not 
perfect, but quite good.

> But I
> agree with your overall perspective.
> I'm just trying to write documentation here. I don't know why the
> process has to be so inorganic, dismal. I also don't see the value in
> learning many, many other formats/utilities/build processes to sustain
> something which is merely in support of the core of what I am doing, ie.
> an actual library.

LOL - you're preaching to the choir here!!!  I have exactly the same 
problem - but It's not solved for me.  I can even do the editing of the 
same files on either a mac or pc.  The document is totally compatible 
with Boost look and feel - it uses boost tools to go from xml to html.
>
> A simple guide explaining what gets auto-gen'd and what the
> non-boostbook tags currently are, is all I need. Or failing that, a
> dtd/schema, some example xml, and a working guide to building quickbook.
> Google has not been reciprocative in this respect.

There is documentation on the boost book tags.  In addition to this 
there is the DocBook documentation.  But when I use XMLMind its a no 
brainer.  Each "level", section, paragraph, etc... the editor displays
the sub tags which are permitted by the DTD.  It's perfect for us.
Note that I also included a BoostBook add-in which means that the the
"smarts" including the boostbook tags.  So if you use this setup - 
you're already boostbook compatible.

> Maybe I'm just stupid, but after passing through the merry-go-round of
> pages directing me as to how to build various interdependent things,
> just to write docs,

Here is the place to start.

  http://www.boost.org/doc/libs/master/doc/html/boostbook.html

I don't know if you've found that.  It's not easy to find on the website.

But really the easiest way to to go through the simple tools section of 
the boost library inclubator. Then just copy all the stuff that's there 
into your project and use your own documentation.  If you walk through 
the steps and you get stuck, let me know and I'll update the 
explanation.  I want other people to try this.

>I eventually came to the conclusion that it was
> easier just to code xml by hand. I'd prefer not to do that, but it's
> indicative of how convoluted the scenario is for a newcomer.

actually once you code the xml, you're still not done.  You have to get 
the tools setup to transform it into html using in a way that is 
compatible with the other boost documentation.

I been exactly there.  Just walk in my footprints.

Robert Ramey