by misternugget on 9/4/18, 4:13 PM with 97 comments
by akavel on 9/5/18, 12:07 PM
"What kept me from [writing my own tool] was a calm voice in my head telling me that I’m here to write a book, not a preprocessor. [...] Now I have written two books and zero tools, which I consider a success."
by grecy on 9/5/18, 1:33 PM
1. Book is entirely written in LaTeX, every chapter in it's own file, master doc with everything combined. I really like having different gutters for left and right pages, ultimate control over formatting, fancy things like Lettrine, header layout and design etc. When I want to do something across the entire doc I write a new command and can use it anywhere.
I Create perfectly formatted print-ready pdf to go to printers directly from this.
2. Run LaTeX file through pandoc to create an ePub.
A little known trick that is now supported by pandoc is conditionals in the LaTeX doc, so when formatting gets hairy I declare commands like this in the master LaTeX document:
\iftoggle{ebook}{
\newcommand{\textbreak}{\newline\hrule\newline}
}{
\newcommand{\textbreak}{\begin{center}\LARGE{$\Psi\quad\Psi\quad\Psi$}\end{center}}
}
3. Un-pack the ePub and tune some of the html/css to my personal taste, then pack it back together. I run it through kindlegen to make sure it's valid, and I have an epub/mobi ready to upload to stores.
I like this workflow so much I'm using it again for my next book
by davedx on 9/5/18, 1:39 PM
I use Sublime Text, sometimes in distraction free mode, but usually not because I often want to Google sciencey things.
I have a single file called "story.txt" that has all the important notes - the names, ages and visual descriptions of the main characters, a detailed (historical) timeline, and chapter outlines I wrote before I started when I knew roughly what the overall plot was going to be. The chapter numbering has changed drastically but the overall outline has stayed pretty true to the original idea.
I really like this system. Keep it simple and focus on writing!
by miles_matthias on 9/5/18, 3:21 PM
The biggest challenge here, to me, isn't writing the book or figuring out what tools to use, but it's marketing. Email lists, FB ads, etc. are really what drive the success or failure of your book. Nathan Barry's writing on this in Authority is my bible for that.
Also, if we're talking tools, shout out to Leanpub. Love that platform, especially for developer books!
EDIT: Nathan Barry doesn't specifically talk about FB Ads, so in terms of a marketing bible, I guess courses and private FB groups have helped us the most. This guy is actually the main goto for fiction authors: https://selfpublishingformula.com/
by nickjj on 9/5/18, 11:50 AM
https://github.com/softcover/softcover
It was written by the same guy who created the original Rails tutorial. You'll be able to generate books that look and feel like this https://www.railstutorial.org/book.
I've released a couple of PDFs using it, and it's pretty decent to work with. There's room for improvement but I haven't come across anything better.
by Jeremysr on 9/5/18, 5:35 PM
For https://viewsourcecode.org/snaptoken/kilo/02.enteringRawMode... , the code is kept in a git repo where each commit is a step in the tutorial. This way steps can be modified, reordered, or split into more steps using git interactive rebase (git rebase -i).
I'm working on a tool which abstracts away git rebase, and gives you a nicer interface for manipulating the series of steps in your tutorial. For example, you can run `leg 3` to checkout step 3, make edits to it, and then run `leg amend` to apply the changes, resolving conflicts as the changes make their way through the rest of the tutorial's steps.
The tool is still in very early development, but here's a quick tutorial to get a better idea of how it works: https://github.com/snaptoken/leg/blob/master/TUTORIAL.md
Also, I'm playing around with a "literate diff" file format that might be of interest: https://github.com/snaptoken/tgc-tutorial/blob/master/doc/02...
by leephillips on 9/5/18, 5:41 PM
"But, most importantly, the code is also duplicated: one version lives in a Markdown file and one (or more) lives in the code folder that comes with the book. If I want to update a snippet of code presented in the book, I have to manually update every copy of it. Yes, cumbersome."
I had a similar problem in writing a book about gnuplot: keeping code samples, code in the text, and the generated plots synchronized. I decided doing it manually was too tedious and error-prone, so I wrote some Pandoc filters to do it for me: https://lee-phillips.org/panflute-gnuplot/
by funkaster on 9/5/18, 4:01 PM
Orgmode Babel: https://orgmode.org/worg/org-contrib/babel/
by bovermyer on 9/5/18, 12:10 PM
I should write a blog post like this. My use case is different, since I write role-playing game books.
by logfromblammo on 9/5/18, 2:54 PM
I made a blank epub template with 50 empty chapters in it, so when starting a new book, I copy that and write new IDs and strings to the metadata, and if I finish it, I delete the unused chapters and remove their entries from the metadata files. It's easier to delete empties than add new chapters, and doing the metadata by hand ensures there's no auto-generated cruft in my file.
For illustrations I use Paint or GIMP or Inkscape, but the template doesn't have more than just a cover image in it.
After testing various ebook readers, there's no way I would recommend xhtml+css zipped to epub for anything technical. The only reader that actually renders text they way I expect, right out of the box, is Edge. Epub is for novels, not textbooks, papers, or manuals.
by ryneandal on 9/5/18, 3:23 PM
by dorfsmay on 9/5/18, 2:01 PM
by _Nocturnal on 9/5/18, 6:25 PM
I have the entire book in a GitHub repository [2], including the export script [3], which may be of interest to those wishing to write a book a similar way.
(Pardon the new account, but my "normal" HN account is more closely tied to my IRL identity than my Nocturnal identity.)
[1]: https://nocturnal.gitbook.io/kitura-until-dawn/
[2]: https://github.com/NocturnalSolutions/KituraBook
[3]: https://github.com/NocturnalSolutions/KituraBook/blob/master...
by xrd on 9/6/18, 5:49 AM
The problem I found with it was that I would add the snippet, then later in the chapter, I would refactor the code to better fit the story, and that worked, as long as you only needed one copy of the file. But, it didn't work if you introduced a basic version of the code and then later elaborated and expanded that code and wanted it to reside in the same file. Additionally, you have to keep the code in the same repository, which I didn't want to do since I published companion repositories (which couldn't contain the sources for the book, obviously) and I didn't want to maintain and synchronize two copies of a file.
So I wrote a little preprocessor that ingested a subtle variation on the snippets O'Reilly pioneered. Normal snippets work. But also, you could specify a file and a SHA hash, and if it saw that, it would pull the file at the commit (just using git show). Then I could update the file inside the repository as the code progressed, and still have all the sample code. And my repository always had working code, no matter what branch or point in time I had checked out.
It's here: https://github.com/xrd/oreilly-snippets/blob/master/README.m...
by runemadsen on 9/5/18, 12:55 PM
by Koshkin on 9/5/18, 2:41 PM
by delinka on 9/5/18, 11:47 AM
Has anyone come up with a method for doing what I want? Maybe the ```lang code blocks in md could take parameters like repo, file, line range; then an update to pandoc would fix it all right up. Thoughts?
by aikah on 9/5/18, 12:01 PM
by codazoda on 9/5/18, 2:22 PM
by amrrs on 9/5/18, 12:35 PM
by munificent on 9/5/18, 5:51 PM
Personally, I'm too error-prone to pull that off. I change the code snippets frequently after chapters are done (often in response to bug reports from readers) and having to manually update the snippets in the text would drive me bonkers.
Also, I want to rigorously, automatically validate that the code in the book is correct and contains everything you need.
To do that, I wrote a Python script [2] that weaves the code and the Markdown together. In the Markdown files, you use a marker like (here in the chapter "Strings"):
^code memory-include-object (2 before, 2 after)
//> Strings memory-include-object
#include "object.h"
//< Strings memory-include-object
The build script reads the "^code" markers and finds the snippet of code in the sources that correspond to it, as well as any desired surrounding lines. But it can also do a lot of other useful things with the snippet markers:
* If some lines of code are marked as being part of a chapter, but that chapter doesn't have a "^code" marker to include them, it reports an error. This way I can't accidentally drop code on the floor.
* It can generate a separate copy of the entire codebase that only includes the snippets that are in a given chapter (and the preceding ones). In other words it can output "what does all the code look like by the time the reader reaches the end of chapter ___" for every chapter.
I output the code for each chapter and then compile that and run all of the tests. This way, I can ensure that by the end of each chapter, the program supports what it's supposed to support by then. I've found countless bugs doing this -- places where I inadvertently put code in a later chapter that is actually needed earlier.
However, this build script is not a generic "build a book" system. It's a bespoke program that only supports this one specific book. That helps keep the complexity down and makes it much easier to put little hacks in when I run into weird edge cases my specific book has. I think that's a reasonable trade-off to keep me producing a high-quality book without too much yak shaving.
One of the days, I'll write a full blog post going through this in more detail.
Of course, none of this is a criticism of Thorsten's system. The simple most important skill in writing a book is figuring how to get those pages done. It doesn't matter if that means waking up at three in the morning and writing on parchment with a red pencil. Whatever works for you, works.
[1]: http://www.craftinginterpreters.com/
[2]: https://github.com/munificent/craftinginterpreters/tree/mast...
by pjmlp on 9/5/18, 12:00 PM
Garmin's own programming language for device apps is called Monkey C.
https://developer.garmin.com/connect-iq/programmers-guide/mo...
by runningmike on 9/5/18, 3:05 PM
by gymshoes on 9/6/18, 7:16 AM
I think KDP allows setting different pricing for different countries.
by netvarun on 9/5/18, 7:04 PM
by tmaly on 9/5/18, 9:50 PM
I wonder how well this method would work for something like an illustrated children’s book?
by nwmcsween on 9/5/18, 5:03 PM
by jasode on 9/5/18, 11:56 AM
I understand the appeal of markdown but I avoid it for writing coding tutorials because it doesn't have an easy way to annotate code with graphics like arrows and floating callouts. Here are some visual examples of code enhanced by arrows: [1][2][3]
Also, all types of text files besides programming syntax can also be explained with graphical annotations such as configuration files or log output files. E.g.[4]
Therefore, I use MS Word because it makes annotation easy. (LaTeX can also do annotation but that has its own workflow issues such as the typical programmer not knowing it which means the team can't easily update the documentation.)
IMO, annotation is important because if we performed eye-tracking and heatmap tests with people reading code tutorials, we'd see that a significant amount of time is wasted with the eyes constantly shifting back and forth between the code and the subsequent paragraphs explaining that code that's located a few inches down the page. I also think this is one reason why live coding demonstrations can sometimes be more effective than reading a book because the presenter is wiggling the mouse (or laser pointer) around the exact spot of the syntax while he's talking.
This can be somewhat mitigated with adding inline code comments in the example but often, it still doesn't point to the exact point in the line that needs to be studied. Code comments also don't easily illustrate (because it has no spatial cues) how separate lines are related to each other.
One workaround of markdown's limitation would be to rasterize the code's text into an image and then use Photoshop to annotate. However, with MS Word, that cumbersome step isn't required.
[1] https://introcs.cs.princeton.edu/java/11cheatsheet/
[2] https://www.oreilly.com/library/view/head-first-python/97814...
[3] https://i.stack.imgur.com/D8JeF.png
[4] https://csharpcorner-mindcrackerinc.netdna-ssl.com/UploadFil...
by danso on 9/5/18, 3:35 PM
by _emacsomancer_ on 9/5/18, 1:44 PM
by purplezooey on 9/6/18, 1:21 AM
by mstolpm on 9/5/18, 11:37 AM
Missing is everything about the writing process, structuring content and editing.
by 6stringmerc on 9/5/18, 3:17 PM
