search

StefanSalewski / NimProgrammingBook

Computer Programming with the Nim Programming Language -- A gentle Introduction
259 stars 19 forks source link

executable examples #18

Open hommelix opened 2 years ago

hommelix commented 2 years ago

Just a suggestion Stefan: In asciidoc there is an include directive. So instead of writing the nim source code in the book, write them in a subfolder and include them in the document. This will enable to include the result in the same way, so that the examples can be run and refreshed before generating the final book.

I've seen this approach in a book "Managing Projects with GNU Make" by Robert Mecklemburg, published by O'Reilly (ISBN 978-0-596-00610-5 if you are interested by this book). It is possible to use the same idea as in this book and build a Makefile that compile the examples, run the examples and save their output to .result files and then generate the final .html, .epub, .pdf book format.

Jerome

hommelix commented 2 years ago

Hi Stefan, I've made a Makefile in my repo of the book. You can have a look and tell me if you like me to create a pull request. Jerome

StefanSalewski commented 2 years ago

there is an include directive.

Yes I know. I was going to use that one for my GTK book, but "include" does not work for the direct GitHub display, so I am currently not using it.

For the Nim book, I intentionally decided to insert the example code directly: Examples are mostly very short, and writing the text is easier when I have the code in the same file. Otherwise I would have to open the code file additional in a different editor window. Actually some example built on each other, in the text I sometimes copy a code segment, and insert and modify it. The disadvantage is obviously, that I can not run the code to test it, and readers who want to run it have to copy the code from the text. Actually I regard bugs in the code as not too serious, the code is to teach, not to present perfect code. Bugs can be even a challenge for the reader. Some examples are intentionally fully untested, and some examples have tiny mistakes, to which I pointed the reader to fix them.

The whole story may change when the book is really ready, and I may even created a paper printed version. For that I will extract all the code in separate files, so that I can run and test them. At least for Nim 2.0 this will be necessary, as Nim 2.0 may make too many examples to fail. You may know that we have a Nim package which works like a simplified version of asciidoctor, which can run code examples in the text file. I can not remember the package name, and I guess that it can not yet replace asciidoctor.

I will look at your epub makefile soon...

hommelix commented 2 years ago

Hi Stefan, The epub publication is from @symgryph See his pull request

Indeed the error in the Nim examples pushed me to test some of them. I personally think that the examples should work and be right. If some examples are wrong, then the reader will ask himself if the content of the book is wrong as well and if it is worth the time to continue reading... So more readers will read and use the book if the examples are right.

I don't mind typing the code myself, the examples are short. I always type the examples myself as to practice.

I don't think there is much advantage to have the github page visualization, as you are already hosting the html output on your website. For local editing, after make all you can just refresh the html page opened in a web browser.

Jerome

StefanSalewski commented 2 years ago

advantage to have the github page visualization,

Yes, my initial comment was not fully correct. Actually it is the GTK Readme, not the GTK book. The README has not a separate HTML page, so I could not use include for the examples. The README is where the full asciidoctor story started, in 2015, when I was learning asciidoctor.

For the bugs in my book, they have actually some purpose: Whenever someone complaints about a bug, I know that I have one more reader. All other metrics work not that well. The 127 github stars have no real meaning. Download statistics of the HTML files does not help that much too, as people may just download, but do not read. I have the feeling that my books comes some years to late. In 2017 we had some interested unskilled beginners, who asked if Nim can be used as first language for them. And some people recommended to better use C or Python for starting, as we had not that much learning resources for Nim. That time Nim was advertised as a better and faster Python, so a lot people tried Nim, but vanished soon. Currently, not that many people are coming new to Nim, there are reasons for that. My initial hope was that selling maybe 50 pieces of the electronic version of the book per year would be possible, for maybe three years. But I have some doubts now. And selling only a few dozen pieces totally makes no sense. I could do Google advertising, that may increase interest, but I guess costs would be more than the income from selling.

And for the bugs -- the final code will be nearly bug free, this happens automatically, as people report bugs, and as I will finally compile and run all the code. More problematic are grammar bugs. I have used languagetool, and had some help by two proof readers. But English grammar is still hard for a non native speaker like me. Maybe when the book is complete, I will consider hiring a professional proof reader, but I guess that will be expensive.

Have you seen already the CSV parsing example I pushed yesterday? The ARC performance issue is really funny, I wonder if really the splitlines() iterator with its unnecessary allocations is the reason. I had a forum discussion with myself already...

symgryph commented 2 years ago

There are several options: I use pandoc, which is a nice one, or there is the one that I used which just turned your website into an epub: https://github.com/danburzo/percollate percolate.