Re: [Boost-build] New docs: Go or no-go?

Subject: Re: [Boost-build] New docs: Go or no-go?
From: mloskot (mateusz_at_[hidden])
Date: 2018-03-30 11:15:45

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