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

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2016-01-05 11:14:19

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Stefan Seefeld
> Sent: 04 January 2016 22:54
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] [boost-docs] Query regarding boostbook and documentation
> 
> On 04.01.2016 11:11, 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.
> 
> Why not ? (To be perfectly clear, I'm not proposing to augment the DocBook 5 "core" vocabulary
with
> the BoostBook tags. But since DocBook 5 already uses namespaces, it's easy to simply put this new
> vocabulary into its own namespace, as a "DocBook 5 profile" (or "extension"). And in fact, that's
> exactly what the previous GSoC work did.
> 
> >
> > 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?).
> 
> Yes, some conversion stylesheets will definitely help with the transition. But we aren't there
yet, so
> it's a bit premature to think about the details (other than the process in general).
> 
> >
> > But doesn't quickbook generate BoostBook xml?  So you'd have to
> > re-write that too?
> 
> Yes, QuickBook would need to adjust. But given the (expected) one-to-one mapping from BoostBook
> to whatever the DocBook 5 extensions will be called, I don't think this is going to be a big deal.
> 
> >
> >> 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.
> 
> Yes, I second that. XMLMind's XXE is a wonderful tool that has saved me a lot of time authoring
> DocBook content. The best I have seen, actually.
> 
> >
> >> 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.
> 
> It may not be better for you, if you are already familiar with the existing tools. But it will be
better for
> someone who
> 
> a) doesn't know BoostBook yet and has to learn yet another tool
> b) doesn't know Boost at all but would like to use this on entirely different projects, without
wanting
> to install Boost first.
> c) uses DocBook 5 and doesn't want to move back to DocBook 4
> d) wants to use standard tools and languages that are maintained by a wider audience.
> 
> >
> > 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.
> 
> I agree. Putting BoostBook "into the open" may actually help with this, too, as it frees you (and
other
> Boost developers) from having to maintain your home-grown tools.

IMO, any new documentation toolchain needs to provide a way of using documentation provided as
comments in the C++ code itself, probably using the syntax of Doyxgen comments that are now
processed by Clang and Microsoft compilers - this syntax (not necessarily the Doxygen tool itself)
is being pretty much standard.

The current method doing this is a bit clunky and slow to build, but it does allow the document
writer to provide hyperlinks to these bits of vital information about parameter, template
parameters, functions, returns, exceptions etc...

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
[phone]