Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added EPUB version with Table of Contents #17

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

symgryph
Copy link

@symgryph symgryph commented Mar 7, 2022

I use an ebook reader, and noticed that there was no epub verison. Hopefully this will be useful to you. Great book!

symgryph added 2 commits March 6, 2022 23:07

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
Basically the web version with TOC converted from Calibre + TOC

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
New NIM Programming book epub with TOC
@StefanSalewski
Copy link
Owner

Thanks.

I just did a lot of more grammar fixes -- the languagetool app found a lot of missing commas and some more grammar and typing errors. EPub and PDF versions are indeed planned -- for PDF I have no good feeling, as I really would not like that people print out the book and waste a lot of paper and ink for that. But before I can work on PDF and EPub I have to learn more about AsciiDoctor, I guess I will have to ask in the AsciiDoctor forum or mailing list or whatever they have. I have collected a few dozen of questions in the last two years, and delayed asking until the book is in a not too bad shape. I think I may start asking now indeed.

I am still unsure if I will ever start to selling the book, as the number of potentially interested readers is so small still. Selling online versions with only a few dozen buyers makes no reals sense. A few people asked even for a printed version, I don't know why they want it, and my current feeling is that the initial costs for creating a printed books are just too large.

At least the books has its own Internet presence now:

nimprogramming.org
nimprogramming.com
nim-programming.org
nim-programming.com
nimprogrammingbook.com

@StefanSalewski
Copy link
Owner

And maybe you can tell us some more why you like a EPub version.

Are you using the EPub on a pure reader like Amazons kindle, or on a tablet? I would guess that most tablets can display the HTML version? Or is the problem the missing online connection? I think at least Firefox provides a "Download" mode for HTML, so that we can read it later without internet connection.

The problem with pure readers is, that we can not try out the examples. Which is true for printed books too. But well, if all of my explanations are really good, trying out examples may be not really needed. And are readers mostly black and white still, or do they support colors? I think I should care for that fact for the EPub version.

I still wonder what the best shipping format for developing countries like Africa, India, and that is.

@symgryph
Copy link
Author

symgryph commented Mar 7, 2022 via email

@symgryph
Copy link
Author

symgryph commented Mar 7, 2022 via email

@hommelix
Copy link

hommelix commented Mar 24, 2022

I like an EPUB version to be able to read on a e-reader. I don't have a web browser on my e-reader, but a collection of computer related EPUB ebooks. Yes the code examples are all black & white on the e-reader. But I like the e-reader to read on the go (public transport) or in the evening. So this is a nice idea to provide this format.

Jerome

@StefanSalewski
Copy link
Owner

I played with an epub version already following this doc:

https://docs.asciidoctor.org/epub3-converter/latest/

But I was not happy with the results. Actually, I have currently some trouble displaying epub documents at all. Many years ago, there was a nice FireFox plugin available to display epub, and I think with that I was able to load an epub which was displayed fine, similar to the HTML version. But latest Firefox seems to have only a restricted built in epub reader. Maybe I should try to read epubs with my smartphone -- I do not have a tablet or kindle available currently.

So yes, I will try to make epubs available somehow, but I may have to delay that until the book is ready. But at least at the end of the year we should get something. Maybe I have to use a tool for conversion, I read something about a tool called callibre.

@hommelix hommelix mentioned this pull request Mar 26, 2022
@SebastianMpl
Copy link

Stefan, just to let you know - for quite some time I've been using epub version made myself in calibre from your html version. Using calibre this way makes nice epub file with quite nice ToC out of the box. Its looks the best on smartphone, but in my inkbook classic 2 ereader (in both cases using Moon Reader) as for it's b/w display there are some issues with code examples (some elements are barely visible).
I decided recently to play with Markdown so I took your adoc file and changed or removed some parts of adoc syntax (mainly = to # for headings and # # to ** ** for bold).
I haven't tried to create a ToC.
I found that Moon Reader application can render md files, so I don't need to struggle with epub.
Source code looks awesome - black and white but all indentation is preserved.
Maybe it could be the answer for your plans for format for developing countries.
Markdown can be readable even as simple text.
For example I can open it in VIm in split screen with terminal to play with on the next screen.
As for selling this book the best would be probably leanpub.
Some time ago that was a book Programming Algorithms about algorithms in Common Lisp; it was available at leanpub from no cost to probably some dollars. Then the author announced that new version will be available in Apress where it's available to buy in multiple formats.
Maybe you could consider doing a similar thing?
Thank you for your work.

@archnim
Copy link

archnim commented Apr 13, 2022

Hello world. bookdown seems better suited for a multi-format eBook. But you have already done so much in asciidoc.

@StefanSalewski
Copy link
Owner

Hello world. bookdown seems better suited for a multi-format eBook. But you have already done so much in asciidoc.

Sorry, have not seen your remark before. I was not aware of this bookdown format. Does it support Nim syntax highlighting? Have you yourself published books with it? I choosed AsciiDoctor two years ago, as I had the impression that it was the most powerful tool after LaTeX. I wrote my thesis in LaTeX, but as books are these days mostly written for electronic publishing, LaTeX may be not the best choice today. But indeed I am not too happy with AsciiDoctor. I have a few dozen of open questions collected in the last two years, and have not started to ask yet. The AsciiDoctor team has changed their forum recently, I think it is called Tulip now. A really strange tool. And most questions seems to be answered by the main author only -- I hesitate to pullute him with up to 100 questions.

So when you are sure that bookdown is really a better alternative, I would consider switching. I have used semantic markup in the adoc source file, so a conversion should be not that difficult.

@archnim
Copy link

archnim commented Apr 17, 2022

Bookdown is based on markdown. Since MD is a universal you can easily switch to another tool. But the language that it supports for highlighting is R.

@blueglyph
Copy link

blueglyph commented Feb 18, 2023

AsciiDoctor has its pros and cons. On the pro side, it's used by publishers like O'Reilly and it has many features. There's a good plugin for Jetbrains tools.

The "forums" are Zulip, I see it more and more often used by projects; Rust uses it too. It's a chat interface with features that makes it easy to use for solving problems and non-"live" discussions. Maybe an acquired taste? 😉

I made a PDF to see how it looked, out of curiosity. It's mostly fine but some tables don't look so great. I know it's not the original purpose and you meant to possibly look that later; perhaps if I have the time and get more proficient with AsciiDoc I could see if there's a way to make it better in PDF. But I'm concerned it may break the look in HTML, so maybe it needs its own stylesheet.

Great work, by the way.

@StefanSalewski
Copy link
Owner

@blueglyph

I made a PDF to see how it looked,

I have already learned that Asciidoctor is using Zulip now. Actually I had a few dozens questions regarding Asciidoctor during the last 3 years, but I hesitated to bother them. I had the feeling that most questions are only answered by the main author, which must be a big burden for them.

For PDF, EPub and other formats: I really think that HTML is the best. We have colors for HTML, and Firefox tools like textmarker (highlighter) should work fine. PDF and EPub needs some tuning. PDF is for printing, but I think there is really no reason why someone should print it. Printing may be useful when you have a complicated paper, which you read again and again to understand it, spending an hour or more with a single page. But not for such a simple book, where you read a page in a few minutes. Epub -- well seems to be black/white only, and when you use your Reader, you can not test Nim example code on that device. I think when the book is really completed, and we have more then a few dozen readers, we may create PDF and EPub. But both is not that urgent currently. Firefox may support PDF printing, and should have an offline mode, so you can read the HTML without Internet connection.

@blueglyph
Copy link

I have already learned that Asciidoctor is using Zulip now. Actually I had a few dozens questions regarding Asciidoctor during the last 3 years, but I hesitated to bother them. I had the feeling that most questions are only answered by the main author, which must be a big burden for them.

I felt exactly the same about it! He doesn't seem to mind though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants