Add algorithm chapter to this tutorial

[JohnCoconut]

Boost graph library has numerous algorithms. It would be great to include them in this tutorial.

However, adding algorithms to the tutorial may cause the it to grow out of hand. It may even exceed 1000 pages.Personally I feel a tutorial is connvinient around 400 pages.

[richelbilderbeek]

I share your ideas and concerns.

One thing I am considering is only using bundled vertices and edges, removing the chapters about custom vertex and edge types (and their combinations).

Do you think that would be a good idea?

Adding algorithms in a reader-friendly way would be great! I am concerned that we could disagree on how the tutorial writing style should be, resulting in friction. Because we will probably never meet in real life, I'd hate losing a valuable collaborator.

My suggestion would be is, that (1) you write the C++ algorithms, as you appear eager to do so, (2) I write the tutorial text to describe it. Additionally, (3) I check if you wrote proper tests for the C++ code, and (4) you check me if I properly describe how an algorithm works.

How do you suggest to tackle this problem?

[JohnCoconut]

@richelbilderbeek

One thing I am considering is only using bundled vertices and edges, removing the chapters about custom vertex and edge types (and their combinations).

That's what I hope too. BGL documentation recommend using bundled property and deprecate old property,but its example are still using the old property. I will be happy if we remove old fashioned all togehter.

My suggestion would be is, that (1) you write the C++ algorithms, as you appear eager to do so, (2) I write the tutorial text to describe it. Additionally, (3) I check if you wrote proper tests for the C++ code, and (4) you check me if I properly describe how an algorithm works.

That's a sound plan.

BGL algorithms require quite a bit of background knowledge, for example, property map and visitor concepts. These two points are briefly mentioned but not explained in detail in our tutorial. We need to cover this somewhere.

[richelbilderbeek]

Sounds like

1) I will remove the custom properties 2) I will start sketching where the text is going to go (and I will need you to check me)

I always considered publishing this tutorial as a book [*]. If our collaboration continues like this, you may consider being second author.

Thursday I will work on this.

[*] I do intend to always keep this GitHub open. The free, libre and online version should remain as great as it is. But I do enjoy holding a book myself.

[JohnCoconut]

I didn't expect that you wish to publish this tutorial as a book. I have never thought of writing a book myself in the past. I have a few questions.

1. What kind of book do you want it to be? Is there a book you like and you want to follow its style? Judging from the first chapter, you wish tutorial to be readable for beginners, highly verbose, repeative, and indexed beautifully. These are ideas and ideas are abstract. So having a example book is great, and we can always use it as a reference.

2. Where do you plan to publish this book? If you wish to publish it for youself to enjoy it like your own baby(not selling it xD), you can be totally be a dictator and do whatever you want with it. But if you want to put the book into the market, that's a totally different story.

Currently, there is one book from BGL authors, The Boost Graph Library: User Guide and Reference Manual. The book itself is great being a reference, but lack of details and examples to be introductory. Reviews on Amazon book page are quite "dipolar", some claimed it as "Milestone in Generic Programming", others hated it as much as "ABSOLUTE BIZARRE SUCKAGE". These reviews serves as a good guidance on how to write a good tecchnical book.

[richelbilderbeek]

I am unsure if I should have kept the idea of publishing for myself a little longer. For sure, it does not fit an Issue titled 'Add algorithm chapter to this tutorial'. But I do have concrete plans. I just happen to have an active collaborator now that forces me to make the tutorial even greater :+1:

In the introduction I talk about the BGL book (it's reference [8]) and what gap the tutorial tries to fill.

[richelbilderbeek]

I re-thought some ideas: I suggest not to add algorithms to this tutorial.

Instead, I suggest to put these in another tutorial, building upon this one.

This tutorial has the focus to be able to do the most basic thinks: counting nodes, adding vertices, file I/O, similar the things you do on a std::vector. I think it is a good idea to keep that focus.

I suggest to move the 'cooler' stuff (which I already marked with a black triangle) to a new tutorial, called for example. 'A Well-Traversed C++14 Boost Graph Tutorial' [*].

This plan would force me to have a condensed, focused tutorial, probably having to shave off many paragraphs and chapters. I have the idea you would enjoy working on the more advanced tutorial. I'd be happy to move the more complex paragraphs to that tutorial.

Do you feel this would be a good idea?

[*] I do not care about the name itself, but this example name does emphasize its relation to this tutorial and does suggest it works on algorithms)

[JohnCoconut]

not to add algorithms to this tutorial.

If algorithms are left out of this tutorial,

pros,

1. there will be space for old-style non-bundled properties.
2. no need to restructure of the whole book
3. the book won't be too big to be overwhelming

cons,

1. people need two books to study BGL

Personally I think it's fine to have two books. My question is how to bridge two of them. To utilize BGL algorithm, one have to understand property map, visitors, property writer. Where to place these, on the first book or second?

[richelbilderbeek]

Thanks for your ideas.

I think it is reasonable to have two books if one would be too big. It may be I shave off too much, that there will be room for the algorithms.

I think the property map and its friends will find their place naturally in the algorithm section/book.

I suggest

1. I shave off unnecessary chapters of the current tutorial
2. If and only if the tutorial is still too big, to create another GitHub, BoostGraphAlgorithmsTutorial (a working title) and set that one up, so we both can assess how well we like it

What are you thoughts on this proposal?

[JohnCoconut]

What about creating a second repo on algorithm first, and merge the two repo if you wish to in future?

Or is it too much of a touble working on two repos at the same time? Or it's quite troublesome to merge two repos? I haven't done such thing before, so I cannot estimate the complexity.

I shave off unnecessary chapters of the current tutorial

I haven't finshied reading the whole tutorial yet, so I am not exactly sure what to do with that. But I hope the tutorial has more introductory text to Graph concepts itself, like "Review of Elementary Graph Theory" section on BGL documentation. Otherwise, the book feels likes a "cookbook".

[richelbilderbeek]

What about creating a second repo on algorithm first, and merge the two repo if you wish to in future? That is exactly what I intend to do. I feel merging -if needed- will be easy enough,

I haven't finshied reading the whole tutorial yet, so I am not exactly sure what to do with that. But I hope the tutorial has more introductory text to Graph concepts itself, like "Review of Elementary Graph Theory" section on BGL documentation. Otherwise, the book feels likes a "cookbook".

In the current (and hopefully future) state, I introduce elementary graph concepts just before they are needed. As these graph concepts must have a logical order, this already helped shape the tutorial.

I shortly considered renaming the book to 'Boost Graph Cookbook' as it does show how to get things done. OTOH -unlike Cookbooks- I do enjoy the coherence of the current tutorial. Perhaps 'Boost Graph Building Blocks' or 'Simple Things You Want To Do With Boost Graph' are titles closer to the current state.

The problem child here are AFAICS the lacking algorithms sections, of which I have the idea you have plenty ideas how to introduce the Boost.Graph and graph theory. Perhaps I should suggest you to create a GitHub with that text and code. I'd be happy to cooperate and check that the two tutorials flow naturally from each other.

What do you think about this workflow?

[JohnCoconut]

I don't thik cookbook name is that bad. There is a cookbook on Boost.Asio library, Boost.Asio C++ Network Programming Cookbook from Packt Publications. Although somwhat outdated, it has a very good flow between concepts and examples.

I will create another tutorial focused on algorithm then. I have to clarify I am learning graph algorithm at the moment. I use boost graph library because it helps me to "visualize" how algorithm works exactly with its events and visitor concepts.

[richelbilderbeek]

What do you think about using these titles then?

• Boost.Graph Cookbook 1: Basics
• Boost.Graph Cookbook 2: Algorithms
• (or some similar names)

If we agree on the titles, I will start the transition of book 1 (as I take the lead here). And of course, I will link to book 2 (as you take the lead there).

Good idea?

[JohnCoconut]

Yeah. Let's go with the plan.

[richelbilderbeek]

Great. This will take some time, so I will not respond for some hours :muscle: