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

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Soul Studios (matt_at_[hidden])
Date: 2016-01-04 22:42:19

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

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.

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

On 5/01/2016 5:11 a.m., Robert Ramey wrote:
> On 1/4/16 5:04 AM, Stefan Seefeld wrote:
>> On 04.01.2016 01:35, Robert Ramey wrote:
>>> On 1/3/16 4:02 PM, Stefan Seefeld wrote:
>>>> I know this isn't what Boost itself is using right now. Hopefully, once
>>>> the above is completed, Boost may switch to free itself from having to
>>>> maintain yet another home-grown tool / language.
>>>
>>> what does thie mean exactly?
>>
>> It means that - ideally - the document schema (and tools) now known as
>> "BoostBook" should become part of DocBook,
>
> You mean you're going to enhance DocBook so that it incorporates tags
> from BoostBook?  I don't think you mean that.
>
> Or do you mean that you're going to remove the BoostBook tags and use
> only tags from DocBook5?  I could see this, but I'm not sure how much
> work it would take to convert all the existing BoostBook xml. (maybe it
> would be easy with the right xslt magic?).
>
> But doesn't quickbook generate BoostBook xml?  So you'd have to re-write
> that too?
>
>> freeing Boost developers to
>> focus their attention on library design rather than support tools. And
>> it means that - again, ideally - more people will be able to benefit
>> from all of that work, not just Boost developers.
>
> I should say that using XMLMind to edit BoostBook XML has worked very
> well for me.  It's WYSIWYG so you can see what you're doing, It works
> with the BoostBook DTD and supports inclusion of images and code so I
> have no need to use more than that one tool. That is, no doxygen,
> quickbook, and ? I also created some documentation templates so that a
> large part of creating standards conforming documentation is almost a
> matter of form-filling.  Nothing
> is perfect of course, but for me it has made documentation preparation
> and maintenance (especially) a relatively easy task which contributes to
> the development process rather than bogging it down.  It's explained in
> the www.blincubator.com and it's used to create and maintain the
> documentation for the safe numerics library.
>
>> Technically it means that Boost documentation will be able to depend on
>> DocBook 5, rather than remaining stuck with an old DocBook 4 version
>> against which the BoostBook DTD was developed.
>
> And how will that be better.  I'm not against it, I just don't want to
> go through turmoil without ending up with something better.
>
> To me, the main problem with boost documentation is that most boost
> authors (and developers in general) don't know how to write it.  And it
> seems they don't know this.  To most is just an afterthought and a chore
> rather than a design activity. Of course the kludgy tools don't help
> here.  I would like to see more effort addressed to this area,  I've
> layed out my ideas in the incubator in requirements and simple tools.  I
> know I continually harp on this and I'm sorry I do this.  But I see this
> as a big bottle neck in the development of quality software.
>
> Robert Ramey
>
> _______________________________________________
> Boost-docs mailing list
> Boost-docs_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-docs
>