Re: [Boost-build] New doc format.

Subject: Re: [Boost-build] New doc format.
From: Robert Ramey (ramey_at_[hidden])
Date: 2018-01-20 21:16:17

On 1/20/18 12:43 PM, Rene Rivera via Boost-build wrote:
> On Sat, Jan 20, 2018 at 11:44 AM, Robert Ramey via Boost-build 
> <boost-build_at_[hidden] <mailto:boost-build_at_[hidden]>> wrote:
> 
>     On 1/20/18 9:03 AM, Rene Rivera via Boost-build wrote:
> 
>          Â  Â  I'm very happy with the boost book approach.
> 
> 
>         What aspect(s) of it are you happy with?
> 
> 
>     a) I like the fact that it separates the content from the
>     presentation so that one can edit the content once and generate as
>     needed renderings in html, singlepage html, pdf, epub or perhaps
>     something else.
> 
> 
> Right.. We also get that with asciidoctor.

Hmmm - I'm not seeing PDF, epub etc.

> 
>     b) I find boost book very easy to edit.  Combined with a) above it
>     lets me edit boost book without much regard for the final rendering
>     which is addresses separately.
> 
> 
> I don't find boost book (aka docbook) easy to edit.

LOL - because you're doing it wrong.

> 
>     c) I can tweak the formating of the final rendering via some xmlt.
>     Granted xml transform is a kludgy system, but I does actually work
>     and generally their is very little of this work to do.
> 
> The kind of tweaking possible in the final rendering with asciidoc would 
> vary depending on the process and output type. For HTML most likely it 
> would be CSS (or alternative). For docbook output you would be able to 
> use XSLT or whatever XML transforms or styling the eventual target 
> output lets you use. No idea for PDF, and other formats though.
> 
>     The fly in the ointment is the actual editing of boost book.  But I
>     have found this nicely addressed by XMLmind personal edition which
>     can be downloaded for free
>     http://www.xmlmind.com/xmleditor/license_xxe_perso.html
>     <http://www.xmlmind.com/xmleditor/license_xxe_perso.html> also see
>     http://www.xmlmind.com/xmleditor/boostbook.shtml
>     <http://www.xmlmind.com/xmleditor/boostbook.shtml>
> 
> 
> That is a gigantic fly.. more like a Lucanus maculifemoratus. For Boost 
> Build with it's current 100 individual contributors it would be 
> impractical to ask them to deal with XML or any particular XML editing 
> software. 

Currenty Boost Book is edited any number of ways.  Quickbook seems to be 
the most popular within boost. I'm sure someone has used emacs and 
someone else has used some other method. Every boost library author 
chooses his own method.  I tried a variety of available methods and 
concluded that XMLMind was the best one.  It doesn't require that any 
one agree with.  The common factor here is Boost Book which, up until 
now at least, Most of us seem to be using.

>It also has the drawback that we are not able to embed the 
> documentation in source files.

Hmmm - I looked at the asciidoc documentation and didn't find a way to 
do this.  But I'll take your word for it that it's doable.  I don't know 
what the source code looks like afterward.

The question of inserting markup into source code is problematic for me. 
On one hand I appreciate the fact that it helps keep the reference 
documentation in sync with the code - ala literate programming.  But on 
the other hand it has some issues

a) It couples the source code with the documentation system. When one 
wants to use another system as either a replacement or alternative, it 
requires mucking with source code.

b) It produces reference documentation which apes the source code and 
all it's flaws.  The documentation doesn't now drive improvements in the 
source code.

c) It gives the impression that documentation is just parroting the code 
and doesn't have a convenient place for the most important parts of the 
documentation, motivation, introduction, examples, rationale, etc. etc.

d) So it produces the illusion that the software is documented so the 
programmer can move on.  It's a fatal flaw.

>     FWIW - I've never thought that the documentation for B2 was bad - as
>     far as it goes.  I've felt that:
> 
>     a) it can be added to and kept more up to date.
> 
> 
> That particular one is key, as the reason it's not kept more up to date 
> is that it's written in docbook. 

Right.  But docbook isn't the problem.  It's the editing of docbook 
which is the problem.

> Which very few of us are comfortable 
> editing. 

I 100% agree that editing docbook with a text editor is a non-starter.

> And which deviates from what the source code actually does 
> because it's separate from that code.
> 
>     b) it's hard to write.  There are two ways of looking at this.
> 
>     1) Work harder at writing it.
>     2) Think about why it's hard to write.
> 
>     I think the correct approach is 2).  When something is really hard
>     to describe, maybe it's a sign that the thing we're trying to
>     describe needs to be considered.  Often times it's easier to fix the
>     tool/library so it makes more sense that to try to describe
>     something that is actually more complex than it needs to be. 
>     Sources of problems are implicit behavior, side effects, global
>     settings/variables, non-obvious inherited behavior, etc.
> 
> Right.. Those need more work. That's a long term goal. And one that will 
> take time and multiple people to make a dent in it.

If you want b2 to be a thing, it should be a shorter term goal.

Robert Ramey

PS - there IS one thing that might be worthy of discussion.  That is 
BoostBook vs DocBook.  BoostBook adds a bunch of very specific C++ tags 
which are processed into DocBook tags via an XSLT transform.  But as it 
turns out, very few if any BoostBook tags are actually used in boost 
documentation.  So things wouldn't change much if the BoostBook layer 
were dropped and one wrote (via whatever editor he wanted) and worked 
with DocBook directly.  (Quickbook might require an update though). 
This is not a big deal, it would just make the processing a little simpler.

PPS

In looking for a simpler setup, the biggest source of complexity was 
trying to use B2 to process the documentation.  I ended up making a 
couple of small batch files - 4 lines each to do the job.  Doing inside 
of B2 didn't add anything.

RR