Generating Boost documentation with pandoc

older
[outcome] Added LEWG expected<T,...

Vinícius dos Santos Oliveira

22 Jul 2016 22 Jul '16

1:40 p.m.

Has anyone tried to generate Boost-styled documentation using pandoc? I never fully liked PDF documentation because I never actually print documentation. However, a few weeks ago I got an ebook reader and I've been fascinated by the ePUB format. I'm using it to read even the IETF's RFCs and it's very pleasant. I'm using ePUB to read files even on my usual laptop. Anyway, I was wondering how nice would be to have an ePUB file containing the whole Boost documentation. pandoc has docbook support as one of its input formats and is capable of generating great ePUB output. -- Vinícius dos Santos Oliveira https://vinipsmaker.github.io/

Show replies by date

Paul A. Bristow

22 Jul 22 Jul

3:31 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Vinícius dos Santos Oliveira Sent: 22 July 2016 14:40 To: Boost Subject: [boost] Generating Boost documentation with pandoc

Has anyone tried to generate Boost-styled documentation using pandoc?

I never fully liked PDF documentation because I never actually print documentation. However, a few weeks ago I got an ebook reader and I've been fascinated by the ePUB format. I'm using it to read even the IETF's RFCs and it's very pleasant. I'm using ePUB to read files even on my usual laptop.

Why are you not reading the PDF version on your laptop already? (I always check that PDF does work on a phone too - but is a bit small to read for long. Certainly OK on a tablet). (A BIG virtue is that you can use the PDF Reader to *search ALL* of the document, not just one HTML page.)

...

Anyway, I was wondering how nice would be to have an ePUB file containing the whole Boost documentation.

How nicer than the PDF versions?

...

pandoc has docbook support as one of its input formats and is capable of generating great ePUB output.

Or perhaps we could probably very easily convert from PDF to ePUB using this http://www.pdf-epub-converter.com/pdf-to-epub-converter.html But are there other people who would like this format? Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

Robert Ramey

4:31 p.m.

On 7/22/16 8:31 AM, Paul A. Bristow wrote:

...

...
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Vinícius dos Santos Oliveira Sent: 22 July 2016 14:40 To: Boost Subject: [boost] Generating Boost documentation with pandoc

Has anyone tried to generate Boost-styled documentation using pandoc?

probably a simpler and more effective technique would be to alter the script which uses xsltproc to produce a pdf to produce an epub. Included with the boost distribution are the xsl files to produce and epub so it shouldn't be a big issue. I have to agree that using an epub reader to view documentation would be attractive. I've been using iBooks to look at some of the stuff I'm generating and I seeing this a very helpful. Executive summary: Boost Book is converted by xsltproc to generate pdf. Try enhancing it to generated epub as well. Robert Ramey

Stefan Seefeld

4:39 p.m.

On 22.07.2016 12:31, Robert Ramey wrote:

...

Executive summary: Boost Book is converted by xsltproc to generate pdf. Try enhancing it to generated epub as well.

Yes, the pipeline is BoostBook -> DocBook -> [HTML, PDF, etc.], so generating EPub should be a matter of tuning the last step in that workflow. (As I mentioned earlier, I still have plans to move a substantial chunk of BoostBook into DocBook itself, to make it available to users outside Boost and to reduce the maintenance cost for the Boost community. But that will take time...) Stefan -- ...ich hab' noch einen Koffer in Berlin...

Vinícius dos Santos Oliveira

5:12 p.m.

2016-07-22 13:39 GMT-03:00 Stefan Seefeld :

...

On 22.07.2016 12:31, Robert Ramey wrote:

...
Executive summary: Boost Book is converted by xsltproc to generate pdf. Try enhancing it to generated epub as well.

Yes, the pipeline is BoostBook -> DocBook -> [HTML, PDF, etc.], so generating EPub should be a matter of tuning the last step in that workflow.

It's great to know that. Thank's for the useful reply. I'll look into that into the future. -- Vinícius dos Santos Oliveira https://vinipsmaker.github.io/

Robert Ramey

6:16 p.m.

On 7/22/16 9:39 AM, Stefan Seefeld wrote:

...

On 22.07.2016 12:31, Robert Ramey wrote:

...
Executive summary: Boost Book is converted by xsltproc to generate pdf. Try enhancing it to generated epub as well.

Yes, the pipeline is BoostBook -> DocBook -> [HTML, PDF, etc.], so generating EPub should be a matter of tuning the last step in that workflow. (As I mentioned earlier, I still have plans to move a substantial chunk

...

of BoostBook into DocBook itself, to make it available to users outside Boost and to reduce the maintenance cost for the Boost community. But that will take time...)

I'm really not getting this idea at all. What does this mean? Going back an re-editing all the xml based on BoostBook? I can't see the point of that as we already have an xsltproc script which does BoostBook -> DocBook. Maybe I just didn't understand what you mean. Robert Ramey

Stefan Seefeld

6:25 p.m.

On 22.07.2016 14:16, Robert Ramey wrote:

...

On 7/22/16 9:39 AM, Stefan Seefeld wrote:

...
On 22.07.2016 12:31, Robert Ramey wrote:

...
Executive summary: Boost Book is converted by xsltproc to generate pdf. Try enhancing it to generated epub as well.

Yes, the pipeline is BoostBook -> DocBook -> [HTML, PDF, etc.], so generating EPub should be a matter of tuning the last step in that workflow. (As I mentioned earlier, I still have plans to move a substantial chunk

...
of BoostBook into DocBook itself, to make it available to users outside Boost and to reduce the maintenance cost for the Boost community. But that will take time...)

I'm really not getting this idea at all. What does this mean? Going back an re-editing all the xml based on BoostBook? I can't see the point of that as we already have an xsltproc script which does BoostBook -> DocBook.

Maybe I just didn't understand what you mean.

BoostBook was invented inside Boost, but to a large extend is useful outside of Boost. So a few years ago we started an effort to "standardize" it, i.e. merge it (and by "it" I mean the schema as well as the stylesheets) into the DocBook project itself. (Note that some of the BoostBook are actually too specific for a wider audience, but the parts that aren't should eventually be available as part of DocBook. Stefan -- ...ich hab' noch einen Koffer in Berlin...

Robert Ramey

7:45 p.m.

On 7/22/16 11:25 AM, Stefan Seefeld wrote:

...

BoostBook was invented inside Boost, but to a large extend is useful outside of Boost. So a few years ago we started an effort to "standardize" it, i.e. merge it (and by "it" I mean the schema as well as the stylesheets) into the DocBook project itself. (Note that some of the BoostBook are actually too specific for a wider audience, but the parts that aren't should eventually be available as part of DocBook.

OK - so this is a DocBook project rather than a Boost project. But the version of DocBook that boost uses is DocBook 4 and uses a DTD schema. The more current version of DocBook is 5.0. DocBook 5.1 is specified but the last complete reference is DocBook 5.0. And interest in DocBook has seemed to have waned. Of course it's not going to disappear as a lot of stuff is made for it. And, though I hate XML, it does a good job of factoring out the meaning of the document elements from that of the formating. I think it was a good choice for BoostBook to be a specialized version of DocBook which includes transforms from BoostBook to DocBook. I think that enhancing the BoostBook tool chain might be a worthwhile and doable task. a) add enhancement to produce epub. I think this wouldn't be too hard and would be useful. b) Consider translating BoostBook to DocBook 5.0. Again, I think this might be worthwhile and it might easily doable. c) Consider dropping BoostBook entirely and using DocBook 5 directly. I wonder if the special tags for BoostBook are all that useful. The work is done so it's not a big issue. I've made some documentation in boost book and some in DocBook 5 and I don't see a huge difference from the author's point of view. Using DocBook direclty, would make the tool chain smaller and simpler. Of course such a task would of necessity require an update of quickbook ....

...

Stefan

Stefan Seefeld

7:58 p.m.

On 22.07.2016 15:45, Robert Ramey wrote:

...

On 7/22/16 11:25 AM, Stefan Seefeld wrote:

...
BoostBook was invented inside Boost, but to a large extend is useful outside of Boost. So a few years ago we started an effort to "standardize" it, i.e. merge it (and by "it" I mean the schema as well as the stylesheets) into the DocBook project itself. (Note that some of the BoostBook are actually too specific for a wider audience, but the parts that aren't should eventually be available as part of DocBook.

OK - so this is a DocBook project rather than a Boost project.

But the version of DocBook that boost uses is DocBook 4 and uses a DTD schema. The more current version of DocBook is 5.0. DocBook 5.1 is specified but the last complete reference is DocBook 5.0. And interest in DocBook has seemed to have waned. Of course it's not going to disappear as a lot of stuff is made for it. And, though I hate XML, it does a good job of factoring out the meaning of the document elements from that of the formating. I think it was a good choice for BoostBook to be a specialized version of DocBook which includes transforms from BoostBook to DocBook.

I'm not entirely sure I see the point you are trying to make. (I should clarify: the "standardization" effort I'm talking about means to take the 95% of BoostBook that are generic and produce an RNG grammar from it that extends the DocBook 5.x RNG grammar.)

...

I think that enhancing the BoostBook tool chain might be a worthwhile and doable task.

By "toolchain" I assume you are referring both to the actual tools (xsltproc, dblatex, fop, etc.), plus the stylesheets. Note that the tools are all standard tools anyhow, only a few stylesheets (those that translate BoostBook to DocBook) are not (yet).

...

a) add enhancement to produce epub. I think this wouldn't be too hard and would be useful.

That shouldn't require any changes to the "toolchain". Just changes to the build system.

...

b) Consider translating BoostBook to DocBook 5.0. Again, I think this might be worthwhile and it might easily doable.

This has been done years ago, on a DocBook branch (that was a GSoC project I mentored). I'm looking into pushing this into master, so it can be distributed with DocBook itself (as an extension grammar).

...

c) Consider dropping BoostBook entirely and using DocBook 5 directly. I wonder if the special tags for BoostBook are all that useful. The work is done so it's not a big issue. I've made some documentation in boost book and some in DocBook 5 and I don't see a huge difference from the author's point of view. Using DocBook direclty, would make the tool chain smaller and simpler. Of course such a task would of necessity require an update of quickbook ....

I'm all for using "standard" tools. But I do see quite some benefit from using the enhanced vocabulary provided by BoostBook, which is why I have been championing the inclusion of it into DocBook proper. On the other hand, if we are talking about an intermediate format only (which is generated from quickbook), all this is moot. All that counts is the initial "source" and the final output. But that would just push the problem around: you then have all the maintenance headaches as part of quickbook... Stefan -- ...ich hab' noch einen Koffer in Berlin...

Robert Ramey

8:27 p.m.

On 7/22/16 12:58 PM, Stefan Seefeld wrote:

...

On 22.07.2016 15:45, Robert Ramey wrote:

...
On 7/22/16 11:25 AM, Stefan Seefeld wrote:

...
BoostBook was invented inside Boost, but to a large extend is useful outside of Boost. So a few years ago we started an effort to "standardize" it, i.e. merge it (and by "it" I mean the schema as well as the stylesheets) into the DocBook project itself. (Note that some of the BoostBook are actually too specific for a wider audience, but the parts that aren't should eventually be available as part of DocBook.

OK - so this is a DocBook project rather than a Boost project.

But the version of DocBook that boost uses is DocBook 4 and uses a DTD schema. The more current version of DocBook is 5.0. DocBook 5.1 is specified but the last complete reference is DocBook 5.0. And interest in DocBook has seemed to have waned. Of course it's not going to disappear as a lot of stuff is made for it. And, though I hate XML, it does a good job of factoring out the meaning of the document elements from that of the formating. I think it was a good choice for BoostBook to be a specialized version of DocBook which includes transforms from BoostBook to DocBook.

I'm not entirely sure I see the point you are trying to make. (I should clarify: the "standardization" effort I'm talking about means to take the 95% of BoostBook that are generic and produce an RNG grammar from it that extends the DocBook 5.x RNG grammar.)

My point is .. I'm just wondering about the value of such an effort. I think it's great that you want to make something better, I'm just suggesting you consider the best return on your efforts. I don't see how enhancing DocBook would have anything to do with boost.

...

...
I think that enhancing the BoostBook tool chain might be a worthwhile and doable task.

By "toolchain" I assume you are referring both to the actual tools (xsltproc, dblatex, fop, etc.), plus the stylesheets. Note that the tools are all standard tools anyhow, only a few stylesheets (those that translate BoostBook to DocBook) are not (yet).

right.

...

...
a) add enhancement to produce epub. I think this wouldn't be too hard and would be useful.

That shouldn't require any changes to the "toolchain". Just changes to the build system.

right. but someone still has to do it, test it, take responsibility for keeping it working, explain it, etc. I think this would be a very worthwhile project that I'm encouraging you to undertake. I think it would have a significant positive impact on boost you'd get a lot of satisfaction from making a success of such an effort. If I understand correctly, creating epub output would skip over entirely the whole FOP rendering which complicates the process and seems to have some issues of it's own. To make this effort successful, one would likely have to enhance the description of how to do.

...

...
b) Consider translating BoostBook to DocBook 5.0. Again, I think this might be worthwhile and it might easily doable.

This has been done years ago, on a DocBook branch (that was a GSoC project I mentored).

Hmmm - interesting, I never knew about this.

...

I'm looking into pushing this into master, so it can be distributed with DocBook itself (as an extension grammar).

I'm not sure what this means, but sounds worth considering. Robert Ramey

Stefan Seefeld

9:05 p.m.

On 22.07.2016 16:27, Robert Ramey wrote:

...

On 7/22/16 12:58 PM, Stefan Seefeld wrote:

...
On 22.07.2016 15:45, Robert Ramey wrote:

...
On 7/22/16 11:25 AM, Stefan Seefeld wrote:

...
BoostBook was invented inside Boost, but to a large extend is useful outside of Boost. So a few years ago we started an effort to "standardize" it, i.e. merge it (and by "it" I mean the schema as well as the stylesheets) into the DocBook project itself. (Note that some of the BoostBook are actually too specific for a wider audience, but the parts that aren't should eventually be available as part of DocBook.

OK - so this is a DocBook project rather than a Boost project.

But the version of DocBook that boost uses is DocBook 4 and uses a DTD schema. The more current version of DocBook is 5.0. DocBook 5.1 is specified but the last complete reference is DocBook 5.0. And interest in DocBook has seemed to have waned. Of course it's not going to disappear as a lot of stuff is made for it. And, though I hate XML, it does a good job of factoring out the meaning of the document elements from that of the formating. I think it was a good choice for BoostBook to be a specialized version of DocBook which includes transforms from BoostBook to DocBook.

I'm not entirely sure I see the point you are trying to make. (I should clarify: the "standardization" effort I'm talking about means to take the 95% of BoostBook that are generic and produce an RNG grammar from it that extends the DocBook 5.x RNG grammar.)

My point is .. I'm just wondering about the value of such an effort. I think it's great that you want to make something better, I'm just suggesting you consider the best return on your efforts. I don't see how enhancing DocBook would have anything to do with boost.

Who said it did ? There is a world outside Boost, didn't you notice ? ;-) Stefan -- ...ich hab' noch einen Koffer in Berlin...

Vinícius dos Santos Oliveira

8 Jan 8 Jan

4:38 a.m.

2016-07-22 13:39 GMT-03:00 Stefan Seefeld :

...

Yes, the pipeline is BoostBook -> DocBook -> [HTML, PDF, etc.], so generating EPub should be a matter of tuning the last step in that workflow.

I have no idea how to do that. I don't even remember how I wrote the Bjam config. Learning advanced C++ programming or low-level POSIX tricks is less complicated because (1) it's exciting, (2) there is a lot of documentation as it's not just a Boost specific project and (3) it's worth as you'll use outside of Boost projects too. Sorry about my not very constructive comment. I thought it'd contribute to understand how outsiders of Boost tooling see Boost tooling. Gonna use asciidoc to write my next documentation so I can still have DocBook (not sure why it's so important) and have free ePUB support. asciidoc or any other simple markup language that does the job. Thanks for the support anyway. -- Vinícius dos Santos Oliveira https://vinipsmaker.github.io/

Stefan Seefeld

4:07 p.m.

On 07.01.2017 23:38, Vinícius dos Santos Oliveira wrote:

...

2016-07-22 13:39 GMT-03:00 Stefan Seefeld :

...
Yes, the pipeline is BoostBook -> DocBook -> [HTML, PDF, etc.], so generating EPub should be a matter of tuning the last step in that workflow.

I have no idea how to do that. I don't even remember how I wrote the Bjam config.

Learning advanced C++ programming or low-level POSIX tricks is less complicated because (1) it's exciting, (2) there is a lot of documentation as it's not just a Boost specific project and (3) it's worth as you'll use outside of Boost projects too.

I hear you.

...

Sorry about my not very constructive comment. I thought it'd contribute to understand how outsiders of Boost tooling see Boost tooling.

Thanks, yes, getting user feedback is valuable. At least some of the developers are aware what an impedance these in-house tools really have become.

...

Gonna use asciidoc to write my next documentation so I can still have DocBook (not sure why it's so important) and have free ePUB support. asciidoc or any other simple markup language that does the job.

(I'm actually pondering to move the Boost.Python docs from QuickBook to good old ReST, so I could manage all its documentation with the sphinx tool (used by most projects in the Python community). It may lack some features, but the fact that it is well-known by many people outweighs that by far. Boost still has a long way to go to get out of the NotInventedHere mood... Best, Stefan -- ...ich hab' noch einen Koffer in Berlin...

Paul Fultz II

10:53 p.m.

...

...
Gonna use asciidoc to write my next documentation so I can still have DocBook (not sure why it's so important) and have free ePUB support. asciidoc or any other simple markup language that does the job.

(I'm actually pondering to move the Boost.Python docs from QuickBook to good old ReST, so I could manage all its documentation with the sphinx tool (used by most projects in the Python community). It may lack some features, but the fact that it is well-known by many people outweighs that by far.

Actually, I built a boost theme for sphinx here: https://github.com/pfultz2/sphinx-boost The theme can be installed with pip as well with `pip install sphinx-boost`. I actually use this to generate the documentation for the Fit library. This works quite nicely, and can integrate with other sphinx-based services like ReadTheDocs.org, which will generate up to date boost-style documentation on every push from github. Paul

Vinícius dos Santos Oliveira

16 Jan 16 Jan

8:39 a.m.

2017-01-08 13:07 GMT-03:00 Stefan Seefeld :

...

...
Gonna use asciidoc to write my next documentation so I can still have DocBook (not sure why it's so important) and have free ePUB support. asciidoc or any other simple markup language that does the job.

(I'm actually pondering to move the Boost.Python docs from QuickBook to good old ReST, so I could manage all its documentation with the sphinx tool (used by most projects in the Python community). It may lack some features, but the fact that it is well-known by many people outweighs that by far. Boost still has a long way to go to get out of the NotInventedHere mood...

I converted mine to asciidoc already: https://github.com/BoostGSoC14/boost.http/commit/c535bf73cab03b60b285df7e7bf... It'll be interesting to see you converting document to reStructuredText and compare results/share experiences. My experience is that it was pretty easy to convert to asciidoc, as all DocBook semantic was there already (like warning, tip and so on blocks). -- Vinícius dos Santos Oliveira https://vinipsmaker.github.io/

Stefan Seefeld

12:13 p.m.

On 16.01.2017 03:39, Vinícius dos Santos Oliveira wrote:

...

2017-01-08 13:07 GMT-03:00 Stefan Seefeld :

...
...
Gonna use asciidoc to write my next documentation so I can still have DocBook (not sure why it's so important) and have free ePUB support. asciidoc or any other simple markup language that does the job. (I'm actually pondering to move the Boost.Python docs from QuickBook to good old ReST, so I could manage all its documentation with the sphinx tool (used by most projects in the Python community). It may lack some features, but the fact that it is well-known by many people outweighs that by far. Boost still has a long way to go to get out of the NotInventedHere mood...

I converted mine to asciidoc already: https://github.com/BoostGSoC14/boost.http/commit/c535bf73cab03b60b285df7e7bf...

It'll be interesting to see you converting document to reStructuredText and compare results/share experiences.

I put a lot of effort into converting the original HTML into QuickBook two years ago, but I expect the conversion from QuickBook to ReST to be almost trivial. For the new Boost.Python NumPy extension the documentation already was using sphinx / ReST, so all I needed to do is slightly adjust the template to match the Boost format (more or less: see http://boostorg.github.io/python/doc/html/numpy/index.html) What I like about sphinx is its support for superstructure, i.e. the simplicity to combine documents into larger documents (including websites), as well as its templating support (to customize styling). And of course, the tool is widely known and used (all the Python community is using it), so neither do I have to solve all the bugs myself, nor write documentation. :-) Stefan -- ...ich hab' noch einen Koffer in Berlin...

Paul A. Bristow

17 Jan 17 Jan

4:53 p.m.

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Vinícius dos Santos Oliveira Sent: 16 January 2017 08:40 To: Boost Subject: Re: [boost] Generating Boost documentation with pandoc

2017-01-08 13:07 GMT-03:00 Stefan Seefeld :

...
...
Gonna use asciidoc to write my next documentation so I can still have DocBook (not sure why it's so important) and have free ePUB support. asciidoc or any other simple markup language that does the job.

(I'm actually pondering to move the Boost.Python docs from QuickBook to good old ReST, so I could manage all its documentation with the sphinx tool (used by most projects in the Python community). It may lack some features, but the fact that it is well-known by many people outweighs that by far. Boost still has a long way to go to get out of the NotInventedHere mood...

Boost is also about DoingItBetter ;-) The complex Quickbook/Doxygen toolchain was devised to provide *better* C++ documents. As has been observed, what works for one language doesn't necessarily work for others. Some libraries are trivial in a documentation sense, others horrendously complicated and have hundreds of templates, functions, arguments, classes, macros and other variants. C++ needs a toolchain that fully understands C++, including templates, meta-things... in all their complexity. Doxygen-syntax or markup comments provide the only 'standard' way of starting to provide the human readable (and human written) within the C++ code. There are also different requirements for users and for maintainers (and developers as they work). None of the tools answers the "How do I FIND things problem" at all well. Indexes and TOCs are part of the answer (provided people know that they exist and then look at them). Few documentation examples *navigate* well, being thin on links (mainly because these are hard work for the author to create manually, as are useful indexes). Good Old ReST meets some needs, especially the simple, but not all. We still need to do Much Better! Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

Robert Ramey

22 Jul 22 Jul

6:20 p.m.

...

Executive summary: Boost Book is converted by xsltproc to generate pdf. Try enhancing it to generated epub as well.

and this in turn can be submitted to lulu.com to produce a Book to be sold on amazon, kindle, etc.

...

Robert Ramey

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Vinícius dos Santos Oliveira

5:10 p.m.

2016-07-22 12:31 GMT-03:00 Paul A. Bristow :

...

Why are you not reading the PDF version on your laptop already?

I used to have preference for PDF over other formats. That changed when I met ePUB. In Boost case, I like the HTML because it's easier to navigate among chapters and sections. (A BIG virtue is that you can use the PDF Reader to *search ALL* of the

...

document, not just one HTML page.)

This happens with ePUB too.

...

Anyway, I was wondering how nice would be to have an ePUB file containing

...
the whole Boost documentation.

How nicer than the PDF versions?

It allows text to reflow, which is great to adapt to my screen size (and not the other way around). Font size is nice, I have a single file containing the whole documentation. I'm using ePUB to read IETF's RFC now and navigation is way nicer. I still go to the txts when I really need to copy something (like a regex and stuff), but apart from that I'm fine.

...

...
pandoc has docbook support as one of its input formats and is capable of generating great ePUB output.

Or perhaps we could probably very easily convert from PDF to ePUB using this

http://www.pdf-epub-converter.com/pdf-to-epub-converter.html

But are there other people who would like this format?

This conversion would be way behind what I could call suboptimal. PDF is made for printing and it'd discard too much information that makes the ePUB great. Imagine converting PDF to HTML, that's what these conversion tools have to do. -- Vinícius dos Santos Oliveira https://vinipsmaker.github.io/

Rene Rivera

5:16 p.m.

On Fri, Jul 22, 2016 at 8:40 AM, Vinícius dos Santos Oliveira < vini.ipsmaker@gmail.com> wrote:

...

Anyway, I was wondering how nice would be to have an ePUB file containing the whole Boost documentation.

Interesting idea.. But I would find it way more useful to have the Boost documentation incorporated into http://devdocs.io. It has all the benefits of ePUB, in this use case, plus.. I can have a bunch of other docs at the same time. Including searching all of them at the same time. And I only need a web browser, no custom app. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Vinícius dos Santos Oliveira

5:21 p.m.

2016-07-22 14:16 GMT-03:00 Rene Rivera :

...

It has all the benefits of ePUB

How so? -- Vinícius dos Santos Oliveira https://vinipsmaker.github.io/

Rene Rivera

5:31 p.m.

On Fri, Jul 22, 2016 at 12:21 PM, Vinícius dos Santos Oliveira < vini.ipsmaker@gmail.com> wrote:

...

2016-07-22 14:16 GMT-03:00 Rene Rivera :

...
It has all the benefits of ePUB

How so?

* Reflowable document * HTML * Searchable * No DRM * SVG * Insert any other features of your web browser here. But I guess if your device doesn't have a good enough web browser you might not get the features. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Robert Ramey

6:18 p.m.

On 7/22/16 10:16 AM, Rene Rivera wrote:

...

On Fri, Jul 22, 2016 at 8:40 AM, Vinícius dos Santos Oliveira < vini.ipsmaker@gmail.com> wrote:

...
Anyway, I was wondering how nice would be to have an ePUB file containing the whole Boost documentation.

Interesting idea.. But I would find it way more useful to have the Boost documentation incorporated into http://devdocs.io.

Ouch not another nitch tool for boost. If someone want's to make and xslt script which will transform BoostBook into devdocs.io fine so long as it doesn't impact those of use which don't use it.

Rene Rivera

6:25 p.m.

On Fri, Jul 22, 2016 at 1:18 PM, Robert Ramey wrote:

...

On 7/22/16 10:16 AM, Rene Rivera wrote:

...
On Fri, Jul 22, 2016 at 8:40 AM, Vinícius dos Santos Oliveira < vini.ipsmaker@gmail.com> wrote:

Anyway, I was wondering how nice would be to have an ePUB file containing

...
the whole Boost documentation.

Interesting idea.. But I would find it way more useful to have the Boost documentation incorporated into http://devdocs.io.

Ouch not another nitch tool for boost.

If someone want's to make and xslt script which will transform BoostBook into devdocs.io fine so long as it doesn't impact those of use which don't use it.

Did not mean to imply anything about replacing what we have. Just that I'd rather spend effort on exactly that boostbook to devdocs.io than on epub. But that's just me ;-) -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Robert Ramey

17 Jan 17 Jan

6:06 p.m.

On 7/22/16 6:40 AM, Vinícius dos Santos Oliveira wrote:

...

Has anyone tried to generate Boost-styled documentation using pandoc?

I never fully liked PDF documentation because I never actually print documentation. However, a few weeks ago I got an ebook reader and I've been fascinated by the ePUB format. I'm using it to read even the IETF's RFCs and it's very pleasant. I'm using ePUB to read files even on my usual laptop.

Anyway, I was wondering how nice would be to have an ePUB file containing the whole Boost documentation.

I have created ePUB documents from boost book documentation. It requires more fussing around that one might hope. But it does work well in the end - without changing of any of the boost book files. BTW - I do this without using boost build - just calling a short shell script. It's very doubtful to me that pandoc can actually do this as well. I'm also somewhat doubtful that one could create an ePUB for all the boost libraries. I might be wrong as it has been claimed that this has been done for PDF. If it can be done for PDF it can likely be done for ePUB as well. But getting the details setup correctly can be very time consuming. Of course changing to some other system is not going to make that any easier. DocBook has been around for quite a while and is still widely used. It has worked well for Boost, and I think all libraries should use it.

...

pandoc has docbook support as one of its input formats and is capable of generating great ePUB output.

Hmmm - I'm skeptical but I'll look into this. The main concern I have is that getting the documentation exactly right will usually require some xslt transform along the way - I'll look to see how pandoc handles that. A big problem with ideas like this - switching to another documentation or build system is that they are simpler for smallish examples. But they often falter when applied to much more elaborate and complicated examples such as boost libraries. This is often not appreciated by those who haven't had to actually apply these ideas to these larger problems. Robert Ramey

John Maddock

7:35 p.m.

On 17/01/2017 18:06, Robert Ramey wrote:

...

On 7/22/16 6:40 AM, Vinícius dos Santos Oliveira wrote:

...
Has anyone tried to generate Boost-styled documentation using pandoc?

I never fully liked PDF documentation because I never actually print documentation. However, a few weeks ago I got an ebook reader and I've been fascinated by the ePUB format. I'm using it to read even the IETF's RFCs and it's very pleasant. I'm using ePUB to read files even on my usual laptop.

Anyway, I was wondering how nice would be to have an ePUB file containing the whole Boost documentation.

I have created ePUB documents from boost book documentation. It requires more fussing around that one might hope. But it does work well in the end - without changing of any of the boost book files.

BTW - I do this without using boost build - just calling a short shell script. It's very doubtful to me that pandoc can actually do this as well.

I'm also somewhat doubtful that one could create an ePUB for all the boost libraries. I might be wrong as it has been claimed that this has been done for PDF. If it can be done for PDF it can likely be done for ePUB as well.

I used to do it for the PDF files, and it's basically dead simple, and the scripts are still part of the distribution if someone would like to take it on. Given that Docbook now has direct support for ePub output, generating ePub should be as easy as generating html, at least in theory ;)

...

But getting the details setup correctly can be very time consuming. Of course changing to some other system is not going to make that any easier.

There are 2 difficulties, one is in setting up the docbook toolchain, then other is that if you want something other than html, then you're going to have to be prepared to do some serious proofreading and tweaking of your documentation. A trivial example, would be large tables that are fine on screen as HTML, but are way too large to fit on a printed page.

...

DocBook has been around for quite a while and is still widely used. It has worked well for Boost, and I think all libraries should use it.

+1, there is a lot to be said for consistency. I can't help feeling that too much has been made of Boost using "non standard" or home made tools for this - we don't - the canonical format is Docbook, how you get to that is up to you. You can author the XML yourself (not recommended frankly or all though it does work quite well for small documents), use a commercial editor, or yes use our quickbook tool, something I've always found to be completely reliable and trivial to use. And yes, I resisted it at first too ;) Just my 2c, John

Robert Ramey

8:46 p.m.

On 1/17/17 11:35 AM, John Maddock wrote:

...

Given that Docbook now has direct support for ePub output, generating ePub should be as easy as generating html, at least in theory ;)

...
But getting the details setup correctly can be very time consuming. Of course changing to some other system is not going to make that any easier.

There are 2 difficulties, one is in setting up the docbook toolchain, then other is that if you want something other than html, then you're going to have to be prepared to do some serious proofreading and tweaking of your documentation. A trivial example, would be large tables that are fine on screen as HTML, but are way too large to fit on a printed page.

Right. I think that these problems could diminished by not trying to make a giant "book" (PDF, ePUB, or whatever) from all the libraries but rather to to build each library independently. This would eliminate the requirement that everyone be exactly on the same page. Another unfortunate feature if the current system is that it depends up using b2 which is really overkill and a big pain for the casual user. (Actually any user). In the incubator I've shown how to create pdf and epub documentation for a particular library just using the tools out of the box and a couple of 1/2 line shell scripts. Promoting this way of building the docs would go a long way to quell the calls for mucking around with current system.

...

...
DocBook has been around for quite a while and is still widely used. It has worked well for Boost, and I think all libraries should use it. +1, there is a lot to be said for consistency.

Personally I'm not less concerned about consistency that others. My concern is simplicity. I investigated all the alternatives I could find in giving my advice to authors in the boost library incubator. Correct and complete documents are not trivial so the "lightweight" solutions didn't suit me. I came up with boost build but without b2.

...

I can't help feeling that too much has been made of Boost using "non standard" or home made tools for this - we don't - the canonical format is Docbook, how you get to that is up to you.

Right

...

You can author the XML yourself (not recommended frankly or all though it does work quite well for small documents), use a commercial editor, or yes use our quickbook tool, something I've always found to be completely reliable and trivial to use. And yes, I resisted it at first too ;)

I resisted it because I didn't want to become dependent on boost tools. b2 burned me. I turned to XMLMind which is great as far as I'm concerned. So my tool chain is: XMLMind - edit xml tools xslt and boostbook/docbook to produce html and ePUB fop - to produce pdf I'm pretty pleased and it works great outside of boost as well!

...

Just my 2c, John

+1c from me.

...

Robert Ramey

Vinícius dos Santos Oliveira

18 Jan 18 Jan

6:14 a.m.

2017-01-17 16:35 GMT-03:00 John Maddock :

...

I can't help feeling that too much has been made of Boost using "non standard" or home made tools for this - we don't - the canonical format is Docbook, how you get to that is up to you. You can author the XML yourself (not recommended frankly or all though it does work quite well for small documents), use a commercial editor, or yes use our quickbook tool, something I've always found to be completely reliable and trivial to use. And yes, I resisted it at first too ;)

asciidoc was designed to support the DocBook's semantics. I can generate this XML quite trivially. Questions: What do I do with this XML? Why is it so important (to Boost)? Maybe I can fight Boost.Jam again to process this file somehow. -- Vinícius dos Santos Oliveira https://vinipsmaker.github.io/

2869

Age (days ago)

3049

Last active (days ago)

List overview

Download

27 comments

7 participants

participants (7)

John Maddock
Paul A. Bristow
Paul Fultz II
Rene Rivera
Robert Ramey
Stefan Seefeld
Vinícius dos Santos Oliveira