Do we need BoostBook?

newer
Is Boost.Asio ported for Windows...

Vladimir Prus

5 Dec 2014 5 Dec '14

10:31 p.m.

Hi, I've noticed that Boost.Build documentation, created with BoostBook, explicitly sets a small, and IMO unreadable, font, so I went to fix that, and some other things, as shown at: http://goo.gl/VWYh2P However, after a few easy tweaks, I'm stuck at the fact that BoostBook/DocBook produces fairly old-fashioned HTML. For example, the Boost logo at top is actually a table, and the "tip" block is also a table, which makes tweaking the layout with CSS quite a bit more complex. Also, some of the conceptually trivial things, like putting some front matter in index.html, appear to require XSLT customization. As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway? Thoughts? -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

Show replies by date

Robert Ramey

5 Dec 5 Dec

11:41 p.m.

Vladimir Prus-3 wrote

...

As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Thoughts?

Usage of BoostBook/DocBook isn't required by Boost. Library writers are free to use any system they want to produce HTML documentation. Maybe the question you might want to ask is ... Should QuickBook be altered to produce html directly? Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669823.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

Vladimir Prus

6 Dec 6 Dec

6:54 a.m.

On 12/06/2014 02:41 AM, Robert Ramey wrote:

...

Vladimir Prus-3 wrote

...
As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Thoughts?

Usage of BoostBook/DocBook isn't required by Boost. Library writers are free to use any system they want to produce HTML documentation.

Maybe the question you might want to ask is ... Should QuickBook be altered to produce html directly?

QuickBook, likewise, is not required. So the question I really want to ask is what people's opinion about best documentation solution in 2014. It's intentionally open-ended. -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

Robert Ramey

7:43 a.m.

Vladimir Prus-3 wrote

...

...
Maybe the question you might want to ask is ... Should QuickBook be altered to produce html directly?

QuickBook, likewise, is not required. So the question I really want to ask is what people's opinion about best documentation solution in 2014. It's intentionally open-ended.

FWIW the serialization library is still raw html. I did it that way before any tools were around and I've never been motivated convert it to something else. I always disliked XML mainly due to its verbosity and I didn't like it's complexity either. In the course of writing up my take on this subject for the incubator I only required that a submitted library have some sort of online browsable documentation in html. http://rrsd.com/blincubator.com/requirements_documentation/ I also spent some time looking at all the alternatives for making documentation and posted my conclusions here: http://rrsd.com/blincubator.com/tools_documentation/ Naturally preferences are going to differ on this and if you would like to advice library authors to use raw html, you could post your own comments on that page. My preferred solution has failed to catch on - oh well. In any case, I think we want to stick the current and historical policy of letting each author handle it his preferred way. We could never agree on how to do this and I don't think it's worth trying to. On the other hand, I'm VERY convinced that we should be making much more of an effort to demand better documentation content for boost libraries. Of course that's a different topic. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669826.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

Rob Stewart

1:22 p.m.

On December 6, 2014 2:43:34 AM EST, Robert Ramey wrote:

...

Vladimir Prus-3 wrote

...
So the question I really want to ask is what people's opinion about best documentation solution in 2014. It's intentionally open-ended.

[snip]

...

I think we want to stick the current and historical policy of letting each author handle it his preferred way. We could never agree on how to do this and I don't think it's worth trying to.

I don't really care how a Boost author implements their documentation, but a consistent look and feel is desirable. If the style ever changes I'd expect those not using QuickBook/DocBook to make the necessary adjustments to match. That may be sufficient reason for most to choose the Boost tool chain. ___ Rob (Sent from my portable computation engine)

Michael Caisse

6:34 p.m.

On 12/05/2014 11:43 PM, Robert Ramey wrote:

...

FWIW the serialization library is still raw html. I did it that way before any tools were around and I've never been motivated convert it to something else.

<snip>

...

My preferred solution has failed to catch on - oh well.

FWIW, and I believe this has been mentioned many times before, I doubt that the Boost.Serialization method will catch on. It is very hard to help people on IRC (for example) with Serialization questions. The documentation's frame-driven menu system makes it very difficult to paste a URL. The address bar in the browser just continues to point at index.html. It is a real pain! -- Michael Caisse ciere consulting ciere.com

Robert Ramey

7:33 p.m.

Michael Caisse-3 wrote

...

FWIW, and I believe this has been mentioned many times before, I doubt that the Boost.Serialization method will catch on. It is very hard to help people on IRC (for example) with Serialization questions. The documentation's frame-driven menu system makes it very difficult to paste a URL. The address bar in the browser just continues to point at index.html.

It is a real pain!

Hmmm - I never thought these downsides outweighed the benefit from the easy navigation. I almost never get any complaint about this. Boost streams uses a similar idea but I believe it implements differently. Does this have the same problem? So I like the ease of navigation, but I don't like the fact URL in the navigation bar doesn't point to the page one is looking at. At one point I did look into the possibility of creating a "Boost Documentation Navigator" which would be automatically created from the BoostBook documentation. It looked feasible but too much work. The whole issue of library documentation is a sore spot for me. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669855.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

Vladimir Prus

8 Dec 8 Dec

7:54 a.m.

On 12/06/2014 10:33 PM, Robert Ramey wrote:

...

Michael Caisse-3 wrote

...
FWIW, and I believe this has been mentioned many times before, I doubt that the Boost.Serialization method will catch on. It is very hard to help people on IRC (for example) with Serialization questions. The documentation's frame-driven menu system makes it very difficult to paste a URL. The address bar in the browser just continues to point at index.html.

It is a real pain!

Hmmm - I never thought these downsides outweighed the benefit from the easy navigation. I almost never get any complaint about this. Boost streams uses a similar idea but I believe it implements differently. Does this have the same problem?

Yes. I think any solution with frames will have the same problem. You can possibly redo it without frames, using divs instead, but then you'd have to remember the tree state between different pages. Or, you can do an actual webapp :-/ -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

Robert Ramey

3:32 p.m.

Vladimir Prus-3 wrote

...

Yes. I think any solution with frames will have the same problem. You can possibly redo it without frames, using divs instead, but then you'd have to remember the tree state between different pages. Or, you can do an actual webapp :-/

As I said, I'm aware of the situation, I just never considered it a big enough issue to justify giving up the navigator - which I personally find very convenient. I believe it would be possible to create an xslt transform which would take all or any of the output produced by BoostBook/DocBook and generate a "Boost document navigator" which would be in a separate, floating window so that the selected documentation page would display it's own url. This would features. a) Be very convenient to use to navigate boost documentation - at least the BoostBook/DocBook ones. b) Be "free" in that it wouldn't require any re-work of any documentation already in BoostBook/DocBook (and of course QuickBook) by library authors. c) Work on both local copies of the documentation as weil as the remote versions at boost.org. c) Require creation of the XSLT transform. According to the hype this is easy. In practice it's a PITA. Maybe we could convince some GSOC candidate to take on this relatively small self contained project. The funny thing there is that the creation and positive reception of of such a facility would would answer your original question in the affirmative - which I guess isn't what you originally had in mind. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669917.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

John Maddock

4:12 p.m.

...

I believe it would be possible to create an xslt transform which would take all or any of the output produced by BoostBook/DocBook and generate a "Boost document navigator" which would be in a separate, floating window so that the selected documentation page would display it's own url. This would features.

I'm pretty sure I mentioned this already, but the docbook XSL stylesheets pretty much have the code to do this already, it's just not present in the "vanilla" HTML output. The Docbook to eclipse stylesheets for example do this to produce a short XML outline file that eclipse can use. Sadly I *really* don't understand XSLT or I would try and hack this myself :-( John.

Daniel James

4 p.m.

On 8 December 2014 at 07:54, Vladimir Prus wrote:

...

Yes. I think any solution with frames will have the same problem. You can possibly redo it without frames, using divs instead, but then you'd have to remember the tree state between different pages. Or, you can do an actual webapp :-/

You might want to look at docbook's webhelp output. I don't know much about it, but it might be along the lines of what you're looking for. It seems to have been developed for Saxon, so might not work with xsltproc. They don't seem to promote it much either, which isn't encouraging.

Robert Ramey

6:40 p.m.

Daniel James-3 wrote

...

On 8 December 2014 at 07:54, Vladimir Prus <

...

vladimir@

...

> wrote:

...
Yes. I think any solution with frames will have the same problem. You can possibly redo it without frames, using divs instead, but then you'd have to remember the tree state between different pages. Or, you can do an actual webapp :-/

You might want to look at docbook's webhelp output. I don't know much about it, but it might be along the lines of what you're looking for. It seems to have been developed for Saxon, so might not work with xsltproc. They don't seem to promote it much either, which isn't encouraging.

I tried it but wasn't satisfied - now I don't remember why. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669927.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

legalize+jeeves＠mail.xmission.com

9 Dec 9 Dec

4:18 a.m.

[Please do not mail me a copy of your followup] Robert Ramey spake the secret code <1417851814952-4669826.post@n4.nabble.com> thusly:

...

I also spent some time looking at all the alternatives for making documentation and posted my conclusions here: http://rrsd.com/blincubator.com/tools_documentation/

I didn't find QuickBook to be any particular burden to learn. If I were writing a few pages of term paper, I wouldn't mind using a WYSIWYG editor like Word, but for technical documentation I find it to be absolutely awful. Unfortunately, like the choice of the "best editor", I think every author has their favorites for writing technical documentation. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com

Paul A. Bristow

6 Dec 6 Dec

4:57 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: 06 December 2014 06:54 To: boost@lists.boost.org Subject: Re: [boost] Do we need BoostBook?

On 12/06/2014 02:41 AM, Robert Ramey wrote:

...
Vladimir Prus-3 wrote

...
As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Thoughts?

The current toolchain from Quickbook via Boostbook and Doxygen may not be ideal (it's certainly tediously slow for large libraries like Boost.Math) but it's the best we have unless someone is going to start from scratch and make something *much* better. Although not universally like, I believe the results can be better than other docs build systems. Many of those critical of the results (and tedium), are dealing with small libraries whose documentation is almost trivial in comparison with the bigger libraries. And the prospect of converting existing documentation to any new/other system isn't appealing :-( Indexes and googling often finds what you want to know, but when it fails, I find the PDF format *is* very useful - mainly because one can search the *whole* documentation. You can even read it in airline mode on your portable computing device ;-) So it's the devil we know and he's always better... Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

Michael Caisse

6:54 p.m.

On 12/05/2014 10:54 PM, Vladimir Prus wrote:

...

On 12/06/2014 02:41 AM, Robert Ramey wrote:

...

...
Maybe the question you might want to ask is ... Should QuickBook be altered to produce html directly?

QuickBook, likewise, is not required. So the question I really want to ask is what people's opinion about best documentation solution in 2014. It's intentionally open-ended.

QuickBook is not required, but I find it to be an easy tool to write and maintain docs. The setup of the tool chain has become much easier over the years. Yanking in snippets from source code that is part of the build/test cycle is critical to me. In addition to Boost libraries that I work on, I use QuickBook for our internal and some client documentation. I have considered using Sphinx because of the good reviews from other Boosters; however, nearly all of my C++ projects are already using Boost so brining in a Python tool seems like just-one-more-step. michael -- Michael Caisse ciere consulting ciere.com

Daniel Pfeifer

7 Dec 7 Dec

12:47 a.m.

On Sat, Dec 6, 2014 at 7:54 AM, Vladimir Prus wrote:

...

On 12/06/2014 02:41 AM, Robert Ramey wrote:

...
Vladimir Prus-3 wrote

...
As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Thoughts?

Usage of BoostBook/DocBook isn't required by Boost. Library writers are free to use any system they want to produce HTML documentation.

Maybe the question you might want to ask is ... Should QuickBook be altered to produce html directly?

QuickBook, likewise, is not required. So the question I really want to ask is what people's opinion about best documentation solution in 2014. It's intentionally open-ended.

I held back that comment because I avoided to sound heretic, but since you started the topic: Today, I would pick Sphinx as a documentation system. While I prefer Asciidoc over ReStructuredText as markup, Sphinx wins hands down because of https://readthedocs.org/. I think the whole documentation of Boost should be hosted by ReadTheDocs. By doing so, the documentation will be built remotely as HTML, PDF and Epub for all releases, triggered by a push to git. It looks nice on the desktop, on paper, and on phones. Printing is not such an issue any longer. My issue is that the current Boost documentation is unreadable on handheld devices!

Paul A. Bristow

1:05 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel Pfeifer Sent: 07 December 2014 00:48 To: Boost Developers List Subject: Re: [boost] Do we need BoostBook?

On Sat, Dec 6, 2014 at 7:54 AM, Vladimir Prus wrote:

...
On 12/06/2014 02:41 AM, Robert Ramey wrote:

...
Vladimir Prus-3 wrote

...
As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Thoughts?

Usage of BoostBook/DocBook isn't required by Boost. Library writers are free to use any system they want to produce HTML documentation.

Maybe the question you might want to ask is ... Should QuickBook be altered to produce html directly?

QuickBook, likewise, is not required. So the question I really want to ask is what people's opinion about best documentation solution in 2014. It's intentionally open-ended.

...

I held back that comment because I avoided to sound heretic, but since you started the topic:

Today, I would pick Sphinx as a documentation system. While I prefer Asciidoc over ReStructuredText as markup, Sphinx wins hands down because of https://readthedocs.org/.

I think the whole documentation of Boost should be hosted by ReadTheDocs. By doing so, the documentation will be built remotely as HTML, PDF and Epub for all releases, triggered by a push to git. It looks nice on the desktop, on paper, and on phones.

OK - is that an offer to show how a Boost library in Quickbook can be re-factored in this system? I presume we can have *Live* Code snippets, indexing, Doxygen, graphics, equations, etc. Do we have a body of people with experience using Sphinx? Looks fine but new to me :-(

...

Printing is not such an issue any longer.

It's still nice to be able to print a single page? (especially from ones handheld device to a nearby cloud printer).

...

My issue is that the current Boost documentation is unreadable on handheld devices!

I dispute this - I've just tried Boost.Math both HTML and PDF on a Moto G and while I wouldn't want to read too much, and navigation isn't wonderful, you can get to a page and read it to check on a detail, and view the pictures. I've also read the html and pdf version on an iPad and it is possible. Are you considering the *size* of the documentation? All the examples I've scanned in https://readthedocs.org/ seem fairly small compared to many Boost libraries. I think the issue of size is a reason for disagreements about the best choice of documentation preparation systems. Above a few pages (when you can scan the whole lot), finding what you want to know becomes a serious problem - and one that we (including Google) haven't really cracked yet. So we need to give users all the help we can with hyperlinking and indexing. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

Vladimir Prus

3:33 p.m.

On 12/07/2014 03:47 AM, Daniel Pfeifer wrote:

...

Printing is not such an issue any longer. My issue is that the current Boost documentation is unreadable on handheld devices!

Is this important use case? As far as Boost.Build docs go, 96% of visits are from desktop browser. I don't know whether it's because people are generally not likely to use Boost docs on a tablet, or because the docs are not readable on a tablet. If we think tablet use case is important, a single line in the generated HTML will improve matters considerably (the meta viewport tag). -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

pfultz2

8 Dec 8 Dec

3:12 p.m.

...

QuickBook, likewise, is not required. So the question I really want to ask is what people's opinion about best documentation solution in 2014. It's intentionally open-ended.

I use mkdocs for smaller libraries. It works nicely. I just write the documentation in markdown. However, for a larger project, I think I would use sphinx or perhaps cldocs. Paul -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669913.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

John Maddock

6 Dec 6 Dec

12:14 p.m.

...

Usage of BoostBook/DocBook isn't required by Boost. Library writers are free to use any system they want to produce HTML documentation.

Maybe the question you might want to ask is ... Should QuickBook be altered to produce html directly?

Just so you know... some of us have a good deal of docbook XML markup directly within our quickbook docs. Of course quickbook could be made to do both, and that has been talked about, but other than possibly faster builds, I'm not sure how much it gains you? John.

John Maddock

12:12 p.m.

...

I've noticed that Boost.Build documentation, created with BoostBook, explicitly sets a small, and IMO unreadable, font, so I went to fix that, and some other things, as shown at:

http://goo.gl/VWYh2P

The font and size is set with our stylesheets, nothing to do with Boostbook/docbook.

...

However, after a few easy tweaks, I'm stuck at the fact that BoostBook/DocBook produces fairly old-fashioned HTML. For example, the Boost logo at top is actually a table,

We're responsible for that too - it's part of our customisation layer - if it's old fashioned, it's because it was written a long time ago and no one has touched it since!

...

and the "tip" block is also a table, which makes tweaking the layout with CSS quite a bit more complex. Also, some of the conceptually trivial things, like putting some front matter in index.html, appear to require XSLT customization.

I think that's this XSL param: http://docbook.sourceforge.net/release/xsl/current/doc/html/chunk.first.sect... When "false" the first section ends up in the index page (right after the index), or maybe you meant something else?

...

As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Personally I like the PDF's *of individual libraries* not the whole thing - they're easier to search and often to navigate than the HTML. BTW printing HTML looses a lot of the structural information that docbook contains, for example you don't get the document outline in the left pane. Of course if I'm online I tend to google rather than open up the local docs, but that doesn't always work. John.

Vladimir Prus

8 Dec 8 Dec

7:47 a.m.

John, On 12/06/2014 03:12 PM, John Maddock wrote:

...

...
I've noticed that Boost.Build documentation, created with BoostBook, explicitly sets a small, and IMO unreadable, font, so I went to fix that, and some other things, as shown at:

http://goo.gl/VWYh2P

The font and size is set with our stylesheets, nothing to do with Boostbook/docbook.

Right, and I had no problem changing that - and it's live at, for example: if anybody wants to comment on the style itself.

...

...
However, after a few easy tweaks, I'm stuck at the fact that BoostBook/DocBook produces fairly old-fashioned HTML. For example, the Boost logo at top is actually a table,

We're responsible for that too - it's part of our customisation layer - if it's old fashioned, it's because it was written a long time ago and no one has touched it since!

Are you sure? It appears to be admon.xsl:graphical.admonition template in base Docbook XSLT layer, with BoostBook doing minor tweaks only. Anyway, I could switch to non-graphical admonitions to get HTML structure I could style, also live at above URL.

...

...
and the "tip" block is also a table, which makes tweaking the layout with CSS quite a bit more complex. Also, some of the conceptually trivial things, like putting some front matter in index.html, appear to require XSLT customization.

I think that's this XSL param: http://docbook.sourceforge.net/release/xsl/current/doc/html/chunk.first.sect...

When "false" the first section ends up in the index page (right after the index), or maybe you meant something else?

Thanks, I did not know about this option, and it's an improvement from my point of view, and I've enabled it for Boost.Build. The original question was about adding some front-matter that would not be present in TOC, and I've ended up abusing the 'dedication' element for it.

...

...
As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Personally I like the PDF's *of individual libraries* not the whole thing - they're easier to search and often to navigate than the HTML. BTW printing HTML looses a lot of the structural information that docbook contains, for example you don't get the document outline in the left pane.

Fair enough. On the other hand, HTML produced by BoostBook/DocBook is not quite perfect either and aging, and nobody's working on improving it. -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

John Maddock

9:04 a.m.

...

...
We're responsible for that too - it's part of our customisation layer - if it's old fashioned, it's because it was written a long time ago and no one has touched it since!

Are you sure? It appears to be admon.xsl:graphical.admonition template in base Docbook XSLT layer, with BoostBook doing minor tweaks only. Anyway, I could switch to non-graphical admonitions to get HTML structure I could style, also live at above URL.

OK, my mistake, yes admonishments get transformed into tables, if this is a problem I suggest you raise it with the Docbook guys - they've been quite helpful to us in the past as I recall.

...

...
Personally I like the PDF's *of individual libraries* not the whole thing - they're easier to search and often to navigate than the HTML. BTW printing HTML looses a lot of the structural information that docbook contains, for example you don't get the document outline in the left pane.

Fair enough. On the other hand, HTML produced by BoostBook/DocBook is not quite perfect either and aging, and nobody's working on improving it.

Are you sure? It's always seemed to me that docbook (and associated stylesheets) is rather well maintained, albeit they're under-resourced (like everyone!) John.

Vladimir Prus

10:05 a.m.

On 12/08/2014 12:04 PM, John Maddock wrote:

...

...
...
We're responsible for that too - it's part of our customisation layer - if it's old fashioned, it's because it was written a long time ago and no one has touched it since!

Are you sure? It appears to be admon.xsl:graphical.admonition template in base Docbook XSLT layer, with BoostBook doing minor tweaks only. Anyway, I could switch to non-graphical admonitions to get HTML structure I could style, also live at above URL.

OK, my mistake, yes admonishments get transformed into tables, if this is a problem I suggest you raise it with the Docbook guys - they've been quite helpful to us in the past as I recall.

I'm fine with non-graphical admonishments (which are divs).

...

...
...
Personally I like the PDF's *of individual libraries* not the whole thing - they're easier to search and often to navigate than the HTML. BTW printing HTML looses a lot of the structural information that docbook contains, for example you don't get the document outline in the left pane.

Fair enough. On the other hand, HTML produced by BoostBook/DocBook is not quite perfect either and aging, and nobody's working on improving it.

Are you sure? It's always seemed to me that docbook (and associated stylesheets) is rather well maintained, albeit they're under-resourced (like everyone!)

It's subjective, so no, I'm not sure. But the fact that it uses tables everywhere, is not mobile-friendly, and does not have modern navigation, speaks so. -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

Paul A. Bristow

10:34 a.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: 08 December 2014 10:06 To: boost@lists.boost.org Subject: Re: [boost] Do we need BoostBook?

On 12/08/2014 12:04 PM, John Maddock wrote:

...
...
...
We're responsible for that too - it's part of our customisation layer - if it's old fashioned, it's because it was written a long time ago and no one has touched it since!

Are you sure? It appears to be admon.xsl:graphical.admonition template in base Docbook XSLT layer, with BoostBook doing minor tweaks only. Anyway, I could switch to non-graphical admonitions to get HTML structure I could style, also live at above URL.

OK, my mistake, yes admonishments get transformed into tables, if this is a problem I suggest you raise it with the Docbook guys - they've been quite helpful to us in the past as I recall.

I'm fine with non-graphical admonishments (which are divs).

...
...
...
Personally I like the PDF's *of individual libraries* not the whole thing - they're easier to search and often to navigate than the HTML. BTW printing HTML looses a lot of the structural information that docbook contains, for example you don't get the document outline in the left pane.

Fair enough. On the other hand, HTML produced by BoostBook/DocBook is not quite perfect either and aging, and nobody's working on improving it.

Are you sure? It's always seemed to me that docbook (and associated stylesheets) is rather well maintained, albeit they're under-resourced (like everyone!)

It's subjective, so no, I'm not sure. But the fact that it uses tables everywhere, is not mobile-friendly, and does not have modern navigation, speaks so.

It's possible, but I'm not sure that anyone would *want* to do more than look up the odd factette on a mobile. But it's certainly possible and if we can make is better, we should do it. Would anyone want Boost docs on a tablet as bedtime reading? (except in case of serious insomnia ;-) So I don't think that being tablet friendly is *terribly* important - hyperlinking, search and indexing and completeness are much more important design objectives and we are not doing too badly on these.

...

If we think tablet use case is important, a single line in the generated HTML will improve matters considerably (the meta viewport tag).

Provided this has no cost to the desktop user, perhaps we should try to add this? Paul PS I note that the PDF reader in Windows 8.1 is so dumbed down that it makes navigation of documents more than a few pages long almost impossible. This makes reading, say, Boost.Math an unpleasant experience, even with the side pages on.

Pete bartlett

2:54 p.m.

...

On 8 Dec 2014, at 10:34, Paul A. Bristow wrote:

...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: 08 December 2014 10:06 To: boost@lists.boost.org Subject: Re: [boost] Do we need BoostBook?

On 12/08/2014 12:04 PM, John Maddock wrote:

...
...
...
We're responsible for that too - it's part of our customisation layer - if it's old fashioned, it's because it was written a long time ago and no one has touched it since!

Are you sure? It appears to be admon.xsl:graphical.admonition template in base Docbook XSLT layer, with BoostBook doing minor tweaks only. Anyway, I could switch to non-graphical admonitions to get HTML structure I could style, also live at above URL.

OK, my mistake, yes admonishments get transformed into tables, if this is a problem I suggest you raise it with the Docbook guys - they've been quite helpful to us in the past as I recall.

I'm fine with non-graphical admonishments (which are divs).

...
...
...
Personally I like the PDF's *of individual libraries* not the whole thing - they're easier to search and often to navigate than the HTML. BTW printing HTML looses a lot of the structural information that docbook contains, for example you don't get the document outline in the left pane.

Fair enough. On the other hand, HTML produced by BoostBook/DocBook is not quite perfect either and aging, and nobody's working on improving it.

Are you sure? It's always seemed to me that docbook (and associated stylesheets) is rather well maintained, albeit they're under-resourced (like everyone!)

It's subjective, so no, I'm not sure. But the fact that it uses tables everywhere, is not mobile-friendly, and does not have modern navigation, speaks so.

It's possible, but I'm not sure that anyone would *want* to do more than look up the odd factette on a mobile. But it's certainly possible and if we can make is better, we should do it.

Would anyone want Boost docs on a tablet as bedtime reading? (except in case of serious insomnia ;-)

So I don't think that being tablet friendly is *terribly* important - hyperlinking, search and indexing and completeness are much more important design objectives and we are not doing too badly on these.

As you write from a Lakeland farm, I suspect we have quite different commutes... I read the mailing list on a phone on a train and it is common to end up on a Boost doc page from the ML. If improvements are being made I would very much welcome enhanced support for tiny devices.

Paul A. Bristow

3:11 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Pete bartlett Sent: 08 December 2014 14:54 To: boost@lists.boost.org Subject: Re: [boost] Do we need BoostBook?

...
...
It's subjective, so no, I'm not sure. But the fact that it uses tables everywhere, is not mobile-friendly, and does not have modern navigation, speaks so.

It's possible, but I'm not sure that anyone would *want* to do more than look up the odd factette on a mobile. But it's certainly possible and if we can make is better, we should do it.

Would anyone want Boost docs on a tablet as bedtime reading? (except in case of serious insomnia ;-)

So I don't think that being tablet friendly is *terribly* important - hyperlinking, search and indexing and completeness are much more important design objectives and we are not doing too badly on these.

As you write from a Lakeland farm, I suspect we have quite different commutes...

Touche !

...

I read the mailing list on a phone on a train and it is common to end up on a Boost doc page from the ML. If improvements are being made I would very much welcome enhanced support for tiny devices.

I'm all in favour of making Boost docs work better on mobile computing devices - just as long as it isn't a pessimisation for desktop use. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

Vladimir Prus

5:34 p.m.

On 12/08/2014 06:11 PM, Paul A. Bristow wrote:

...

...
I read the mailing list on a phone on a train and it is common to end up on a Boost doc

...
page from the ML. If improvements are being made I would very much welcome enhanced support for tiny devices. I'm all in favour of making Boost docs work better on mobile computing devices - just as long as it isn't a pessimisation for desktop use.

Okay, here's a pull request: https://github.com/boostorg/boostbook/pull/7 And as before, the live preview: http://www.boost.org/build/doc/html/bbv2/tutorial/libs.html This looks fairly well on a Nexus 7 - which is probably the smallest one can reasonably assume to look at technical documentation. Some code examples overflow, which possibly can be fixed by reducing margins a bit more, but generally it's fine. -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

Robert Ramey

6:46 p.m.

Looks easier to read - any chance you could leave out the max-width 60 em from the CSS? Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669928.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

Vladimir Prus

7:04 p.m.

On 12/08/2014 09:46 PM, Robert Ramey wrote:

...

Looks easier to read - any chance you could leave out the max-width 60 em from the CSS?

This is Boost.Build docs for now, and there, I'd prefer to leave it. The default behaviour of 100% of page width makes for overly long lines, IMO. Do you find the current line length to be too short? -- Vladimir Prus CodeSourcery / Mentor Embedded http://vladimirprus.com

Robert Ramey

9:03 p.m.

Vladimir Prus-3 wrote

...

On 12/08/2014 09:46 PM, Robert Ramey wrote:

...
Looks easier to read - any chance you could leave out the max-width 60 em from the CSS?

This is Boost.Build docs for now, and there, I'd prefer to leave it.

It seems the boost library documentation uses the full width. So I was surprised to see this.

...

The default behaviour of 100% of page width makes for overly long lines, IMO.

But one can always adjust the with of the window. On a table I guess you can't but it's not too wide anyway.

...

Do you find the current line length to be too short?

Actually not. I just like being in control. I generally don't prefer software which tries to do what I want (pick a reasonable maximum width) rather than what I say (fit text window however I set it). I concede its a matter of taste/preference which can never be resolved - but can provoke a huge amount of discussion. (remember world wide discussion of proper placement of "{" and "}" in the late seventies?). Since I mostly use my local copy of the boost documentation I can easily tweak my local css. So I'm not inclined to make a federal case about it. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669942.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

Paul A. Bristow

7:17 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: 08 December 2014 17:35 To: boost@lists.boost.org Subject: Re: [boost] Do we need BoostBook?

On 12/08/2014 06:11 PM, Paul A. Bristow wrote:

...
...
I read the mailing list on a phone on a train and it is common to end up on a Boost doc

...
page from the ML. If improvements are being made I would very much welcome enhanced support for tiny devices. I'm all in favour of making Boost docs work better on mobile computing devices - just as long as it isn't a pessimisation for desktop use.

Okay, here's a pull request: https://github.com/boostorg/boostbook/pull/7 And as before, the live preview:

http://www.boost.org/build/doc/html/bbv2/tutorial/libs.html

This looks fairly well on a Nexus 7 - which is probably the smallest one can reasonably assume to look at technical documentation. Some code examples overflow, which possibly can be fixed by reducing margins a bit more, but generally it's fine.

Works me on smaller budget Moto G - though I wouldn't want to read too much. Need to scroll right on the lines of code example lines of course. FWIW Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

Mathias Gaunard

7 Dec 7 Dec

12:52 p.m.

On 05/12/2014 23:31, Vladimir Prus wrote:

...

As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Thoughts?

I personally think it's a great toolchain and I also use it in other, non-Boost projects. Boostbook is just an extension of Docbook able to deal with C++ programs. Docbook is one of the most well-known single-source authoring solutions for technical documentation. What would you suggest instead? The only compelling alternative I can think of is reSt/Sphinx.

Robert Ramey

5:58 p.m.

Mathias Gaunard-2 wrote

...

On 05/12/2014 23:31, Vladimir Prus wrote:

...
As heretic as it sounds, do we get any benefits from BoostBook? It's a complex vocabulary, with complex toolchain, and while PDF generation sounded nice 10 years ago, printing HTML into PDF is a viable option these days - and nobody would want to print entire Boost documentation anyway?

Thoughts?

I personally think it's a great toolchain and I also use it in other, non-Boost projects.

...

Boostbook is just an extension of Docbook able to deal with C++ programs. Docbook is one of the most well-known single-source authoring solutions for technical documentation.

...

What would you suggest instead? The only compelling alternative I can think of is reSt/Sphinx.

Personally I'm wary of jumping on the latest/greatest idea for things like this. I'll admit that part of it is just being old. But another part is that many of these things are faddish ideas which may or may not last. I've seen lots of stuff come on big then fade away (java anyone?). I always hated XML because of it's ridiculous verbosity, ambiguity (should data be attributes or tags?), Funky add-ons (DTD ....), etc. If the world was mine, we'd still be using nroff with every more refined macro packages to generate html. This could have done all that the more recent methods do - but without every one adding in his own language. Anyway, the world is not mine (so you can all relax), and we're stuck with that we currently have - which is good enough and not worth spending huge amount of effort to get refined the way we would like it. Robert Ramey -- View this message in context: http://boost.2283326.n4.nabble.com/Do-we-need-BoostBook-tp4669821p4669868.ht... Sent from the Boost - Dev mailing list archive at Nabble.com.

3624

Age (days ago)

3628

Last active (days ago)

List overview

Download

33 comments

12 participants

participants (12)

Daniel James
Daniel Pfeifer
John Maddock
legalize+jeeves＠mail.xmission.com
Mathias Gaunard
Michael Caisse
Paul A. Bristow
Pete bartlett
pfultz2
Rob Stewart
Robert Ramey
Vladimir Prus