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

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

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