New docs: Go or no-go?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

New docs: Go or no-go?

Boost - Build mailing list
I think I've fixed all the problems I can fix in the new style docs <https://grafikrobot.github.io/b2doc/> for b2:

* Fully updated with develop docs.
* Works offline as well as it does online.
* All the cross-links work.
* Marked up all the code to be syntax colored.

Big question is now.. Go with this or no? Note, that this would be a change for some future release not the current Boost 1.67 cycle.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
On 2/26/18 1:44 PM, Rene Rivera via Boost-build wrote:

> I think I've fixed all the problems I can fix in the new style docs
> <https://grafikrobot.github.io/b2doc/> for b2:
>
> * Fully updated with develop docs.
> * Works offline as well as it does online.
> * All the cross-links work.
> * Marked up all the code to be syntax colored.
>
> Big question is now.. Go with this or no? Note, that this would be a
> change for some future release not the current Boost 1.67 cycle.
>
> --
> -- Rene Rivera
> -- Grafik - Don't Assume Anything
> -- Robot Dreams - http://robot-dreams.net <http://robot-dreams.net/>
>
> _______________________________________________
> Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
>

My question is: Are these new docs or is a reformatting of the original
documentation using a new system?

Robert Ramey


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list


On Feb 26, 2018 4:52 PM, "Robert Ramey via Boost-build" <[hidden email]> wrote:
On 2/26/18 1:44 PM, Rene Rivera via Boost-build wrote:
I think I've fixed all the problems I can fix in the new style docs <https://grafikrobot.github.io/b2doc/> for b2:

* Fully updated with develop docs.
* Works offline as well as it does online.
* All the cross-links work.
* Marked up all the code to be syntax colored.

Big question is now.. Go with this or no? Note, that this would be a change for some future release not the current Boost 1.67 cycle.

My question is: Are these new docs or is a reformatting of the original documentation using a new system?

The latter for now. The goal is for new content to come from here.

Rene.


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
Hi Rene,

Am Montag, 26. Februar 2018, 22:44:02 CET schrieb Rene Rivera via Boost-build:
> I think I've fixed all the problems I can fix in the new style docs <
> https://grafikrobot.github.io/b2doc/> for b2:

Much better than the old ones.

> Big question is now.. Go with this or no? Note, that this would be a change
> for some future release not the current Boost 1.67 cycle.

Definitely a "go". +1 from here.

Yours,

Jürgen
--
* Dipl.-Math. Jürgen Hunold  !
* voice: ++49 4257 300       ! Fährstraße 1
* fax  : ++49 4257 300       ! 31609 Balge/Sebbenhausen
* [hidden email]             ! Germany
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build

signature.asc (201 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 2/26/18 1:44 PM, Rene Rivera via Boost-build wrote:

> I think I've fixed all the problems I can fix in the new style docs
> <https://grafikrobot.github.io/b2doc/> for b2:
>
> * Fully updated with develop docs.
> * Works offline as well as it does online.
> * All the cross-links work.
> * Marked up all the code to be syntax colored.
>
> Big question is now.. Go with this or no? Note, that this would be a
> change for some future release not the current Boost 1.67 cycle.

Hmmm - why are you asking us here?  So far Boost hasn't really
prescribed what documentation should be used. So I don't know what you
need from us.  I suppose you're just asking for our opinion.

So here's mine.

Moving away from the boost book system is a very bad idea.  That system
has some problems, but we would be much better off fixing those problems
then abandoning that for the other ones.  The advantages of the boost
book system are:

a) It leverages on the docbook concept of separating documentation
content from formatting.

b) This means that once documentation has been prepared, it can be
rendered in a variety of formats: ebook, pdf, html, and ... others which
may come up in the future.

c) This (mostly) reduces the scale of the library developer's task
relieving him of the burden of maintaining some format/rendering.

d) It promotes the maintenance of a consistent view of boost
documentation.  It does this to the point that libraries can be rendered
individually or as one larger "boost encyclopedia".

e) It would facilitate the automatic creation of a boost "documentation
browser" among other things.  Again, rather than each library author
making his own documenation table of contents "browser" it would permit
tools like this to be inherited by all libraries with no effort expended
by library authors.

f) It decouples documentation editing.  There are multiple tools
available for editing boostbook including quikbook written by eric
neibler, xmlMind which I have been promoting, emacs macros and
commercial packages as well.

g) the boost book system is "open" to add on tools and we've made a few
that still work.

I'll concede there are some downsides to boostbook:

a) the b2 build procedure has been "fragile".  But in my view that
applies to everything related to b2. But b2 has been "good enough" for
lots of boost stuff so I would imagine that this is fixable.

b) the xml syntax is noxious.  I've mentioned ways to deal with this.

c) The docbook tool chain is very kludgy

But moving to something else is just going to substitute a new set of
problems for the current ones, and inhibit progress toward a
collaborative solution.

Robert Ramey






_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
On Tue, Feb 27, 2018 at 12:38 PM, Robert Ramey via Boost-build <[hidden email]> wrote:
On 2/26/18 1:44 PM, Rene Rivera via Boost-build wrote:
I think I've fixed all the problems I can fix in the new style docs <https://grafikrobot.github.io/b2doc/> for b2:

* Fully updated with develop docs.
* Works offline as well as it does online.
* All the cross-links work.
* Marked up all the code to be syntax colored.

Big question is now.. Go with this or no? Note, that this would be a change for some future release not the current Boost 1.67 cycle.

Hmmm - why are you asking us here?  So far Boost hasn't really prescribed what documentation should be used. So I don't know what you need from us.  I suppose you're just asking for our opinion.

I'm asking here as this is where Boost Build users and developers are. And, yes, what I'm asking for is general measure of "does the content look correct?" and a final "is it ok to move to asciidoctor?"

So here's mine.

Moving away from the boost book system is a very bad idea.

B2 has essentially never used Boost Book (except for the small piece of quickbook for jam docs). So we're not really moving away from Boost Book. What I'm hoping to move away from is direct DocBook XML sources.
 
  That system has some problems, but we would be much better off fixing those problems then abandoning that for the other ones.  The advantages of the boost book system are:

a) It leverages on the docbook concept of separating documentation content from formatting.

b) This means that once documentation has been prepared, it can be rendered in a variety of formats: ebook, pdf, html, and ... others which may come up in the future.

c) This (mostly) reduces the scale of the library developer's task relieving him of the burden of maintaining some format/rendering.

d) It promotes the maintenance of a consistent view of boost documentation.  It does this to the point that libraries can be rendered individually or as one larger "boost encyclopedia".

e) It would facilitate the automatic creation of a boost "documentation browser" among other things.  Again, rather than each library author making his own documenation table of contents "browser" it would permit tools like this to be inherited by all libraries with no effort expended by library authors.

f) It decouples documentation editing.  There are multiple tools available for editing boostbook including quikbook written by eric neibler, xmlMind which I have been promoting, emacs macros and commercial packages as well.

g) the boost book system is "open" to add on tools and we've made a few that still work. 

I'll concede there are some downsides to boostbook:

a) the b2 build procedure has been "fragile".  But in my view that applies to everything related to b2. But b2 has been "good enough" for lots of boost stuff so I would imagine that this is fixable.

b) the xml syntax is noxious.  I've mentioned ways to deal with this.

c) The docbook tool chain is very kludgy

But moving to something else is just going to substitute a new set of problems for the current ones, and inhibit progress toward a collaborative solution.

Yes, you've mentioned all that before :-) And I concur that all of those are good points. But perhaps you failed to notice previously where I mentioned, and illustrated, taking this same documentation and feeding it into our DocBook processing chain <https://rawgit.com/grafikrobot/b2doc/90a793a12c675059e32ad4b4c77b7d84c2f1ab54/index.html>.

On another point though.. Part of the documentation change is to prepare for making B2 truly independent of Boost.

--
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net


_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
On 2/27/18 11:23 AM, Rene Rivera via Boost-build wrote:
> On Tue, Feb 27, 2018 at 12:38 PM, Robert Ramey via Boost-build

> Yes, you've mentioned all that before :-) And I concur that all of those
> are good points. But perhaps you failed to notice previously where I
> mentioned, and illustrated, taking this same documentation and feeding
> it into our DocBook processing chain
> <https://rawgit.com/grafikrobot/b2doc/90a793a12c675059e32ad4b4c77b7d84c2f1ab54/index.html 
> <https://rawgit.com/grafikrobot/b2doc/90a793a12c675059e32ad4b4c77b7d84c2f1ab54/index.html>>.

OK - I either forgot this or never got it.  In any case, this seems
pretty good to me.  That is, it leaves boostbook/docbook but users
you're own choice for addressing the XML preparation.  No problem with that.

Other recent documenation efforts, (Hana, MP11) seem to avoid
boostbook/docbook all together.  I think this is a very bad trend.

> On another point though.. Part of the documentation change is to prepare
> for making B2 truly independent of Boost.

This will likely be the best thing for B2 and likely would have been
very valuable to B2 in the past.  A tool which stands on it's own with
it's own fan base is inherently much stronger than something which
depends upon something else.

>
> --
> -- Rene Rivera
> -- Grafik - Don't Assume Anything
> -- Robot Dreams - http://robot-dreams.net <http://robot-dreams.net/>
>
>
>
> _______________________________________________
> Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
>

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
On 02/26/2018 10:44 PM, Rene Rivera via Boost-build wrote:

> I think I've fixed all the problems I can fix in the new style docs
> <https://grafikrobot.github.io/b2doc/> for b2:
>
> * Fully updated with develop docs.
> * Works offline as well as it does online.
> * All the cross-links work.
> * Marked up all the code to be syntax colored.
>
> Big question is now.. Go with this or no? Note, that this would be a
> change for some future release not the current Boost 1.67 cycle.

I definitely prefer the new style docs. The navigation bar is very
convenient, and I also prefer the layout.

Best regards,

Wieger (a long-term and happy Boost.Build user)
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
In reply to this post by Boost - Build mailing list


On 27/02/2018 19:38, Robert Ramey via Boost-build wrote:

> On 2/26/18 1:44 PM, Rene Rivera via Boost-build wrote:
>> I think I've fixed all the problems I can fix in the new style docs
>> <https://grafikrobot.github.io/b2doc/> for b2:
>>
>> * Fully updated with develop docs.
>> * Works offline as well as it does online.
>> * All the cross-links work.
>> * Marked up all the code to be syntax colored.
>>
>> Big question is now.. Go with this or no? Note, that this would be a
>> change for some future release not the current Boost 1.67 cycle.
>
> Hmmm - why are you asking us here?  So far Boost hasn't really
> prescribed what documentation should be used. So I don't know what you
> need from us.  I suppose you're just asking for our opinion.
>
> So here's mine.
>
> Moving away from the boost book system is a very bad idea.  That
> system has some problems, but we would be much better off fixing those
> problems then abandoning that for the other ones.  The advantages of
> the boost book system are:
>
> a) It leverages on the docbook concept of separating documentation
> content from formatting.
>
> b) This means that once documentation has been prepared, it can be
> rendered in a variety of formats: ebook, pdf, html, and ... others
> which may come up in the future.
>
> c) This (mostly) reduces the scale of the library developer's task
> relieving him of the burden of maintaining some format/rendering.
>
> d) It promotes the maintenance of a consistent view of boost
> documentation.  It does this to the point that libraries can be
> rendered individually or as one larger "boost encyclopedia".
>
> e) It would facilitate the automatic creation of a boost
> "documentation browser" among other things.  Again, rather than each
> library author making his own documenation table of contents "browser"
> it would permit tools like this to be inherited by all libraries with
> no effort expended by library authors.
>
> f) It decouples documentation editing.  There are multiple tools
> available for editing boostbook including quikbook written by eric
> neibler, xmlMind which I have been promoting, emacs macros and
> commercial packages as well.
>
> g) the boost book system is "open" to add on tools and we've made a
> few that still work.
>
> I'll concede there are some downsides to boostbook:
>
> a) the b2 build procedure has been "fragile".  But in my view that
> applies to everything related to b2. But b2 has been "good enough" for
> lots of boost stuff so I would imagine that this is fixable.
>
> b) the xml syntax is noxious.  I've mentioned ways to deal with this.
>
> c) The docbook tool chain is very kludgy

Kludgy enough that I've never been able to generate the doc on my
development machine. I stopped trying a couple of years ago. Now I need
to go back to it, can't even remember where to start.
So it is kind of difficult to appreciate points a-g (which could be
valid and seems pretty important).

>
> But moving to something else is just going to substitute a new set of
> problems for the current ones, and inhibit progress toward a
> collaborative solution.
Well, if the new problems are not boost-only non C++ problems, that
would already be an improvement.
Are they ?

>
> Robert Ramey
>
>
>
>
>
>
> _______________________________________________
> Unsubscribe & other changes:
> https://lists.boost.org/mailman/listinfo.cgi/boost-build

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
On 2/27/18 2:10 PM, Alain Miniussi via Boost-build wrote:

> Kludgy enough that I've never been able to generate the doc on my
> development machine. I stopped trying a couple of years ago. Now I need
> to go back to it, can't even remember where to start.

I faced the same problem. My solution was to just figure it out from
scratch.  I created some simple shell scripts do do the job and have
been quite pleased with it.  I noted down how I did it in the boost
library incubator website and used it to make the safe numerics library
documention.  This is done using boostbook but without b2.

> So it is kind of difficult to appreciate points a-g (which could be
> valid and seems pretty important).

Exactly true. Faced with this problem, I worked around it as described
above.

>> But moving to something else is just going to substitute a new set of
>> problems for the current ones, and inhibit progress toward a
>> collaborative solution.

> Well, if the new problems are not boost-only non C++ problems, that
> would already be an improvement.

> Are they ?

LOL - since I bit the bullet and made it work, I haven't had to actually
confront the problems with the alternative.  But I did look at
alternatives and my main concern was they they don't decouple content
from the formatting so it's hard to make a tweak and have the effect
ripple through.

The main problem was editing the DocBook / BoostBook "source" text.  For
me this was addressed by using XMLMind.  Apparently Rene has a different
solution.  And for other boosters, quickbook seems to do the trick.


>>
>> Robert Ramey
>>
>>
>>
>>
>>
>>
>> _______________________________________________
>> Unsubscribe & other changes:
>> https://lists.boost.org/mailman/listinfo.cgi/boost-build
>
> _______________________________________________
> Unsubscribe & other changes:
> https://lists.boost.org/mailman/listinfo.cgi/boost-build

_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
Reply | Threaded
Open this post in threaded view
|

Re: New docs: Go or no-go?

Boost - Build mailing list
In reply to this post by Boost - Build mailing list
Boost - Build mailing list wrote
> I think I've fixed all the problems I can fix in the new style docs <
> https://grafikrobot.github.io/b2doc/> for b2:
>
> * Fully updated with develop docs.
> * Works offline as well as it does online.
> * All the cross-links work.
> * Marked up all the code to be syntax colored.
>
> Big question is now.. Go with this or no?

Rene,

TL;TR: Yes, go with this.

First, thank you for the efforts.

1. https://github.com/grafikrobot/b2doc contains only final HTML.

Since this is "reformatting of the original documentation using a new
system",
I guess you translated the original XML files to .adoc files.
Are you going to replace the XML-s with .adoc files in BB repo?

For some people familiar with Markdown, reStructuredText like myself
it could make it easier to contribute if there are .adoc files as source
files.

2. Search is a must-have feature

I hope users will no longer have to web-search for:
unit-test site:http://www.boost.org/build/

3. Have you considered Sphinx and reStructuredText?

If you have, what made you go for the AsciiDoc?

Sphinx is already used by Boost.HOF, Boost.Python
and it is being seriously considered for Boost.GIL.
If Sphinx becomes an accepted alternative, just after the native
Boost docs toolchain (aka forest of boostbook/docbook/quickbook)
then I think it may make sense to Sphinx-ify Boost.Build too.


Best regards,
--
Mateusz Loskot, http://mateusz.loskot.net







-----
--
Mateusz Loskot, http://mateusz.loskot.net
--
Sent from: http://boost.2283326.n4.nabble.com/Boost-Build-f2685023.html
_______________________________________________
Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build