7 ms·
Writing a book in the age of open source
- ihaveajob 2y agoWhen I wrote my PhD thesis (the closest thing to a book I've ever worked on), I used LyX and I loved it. All the power of LaTeX, with a usable UI. When you're done, just apply the publisher settings and you're out!
- WillAdams 2y agoBack when I did composition for STEM publishers, the one manuscript I got in LyX stands out as the cleanest, and easiest to work with --- added two custom packages: - first loads some packages and defines all the customization commands to do nothing - second defines the customization commands and applies the formatting as specified by the publisher Edit the LaTeX text, add customization commands for shortening/lengthening paragraphs, &c. for balancing pages and tweaking float placement --- make PDF, send to printer, then at the end of the project, comment out the second package line and return the updated source to the author for their next edition. That said, my current books are being done using: - GitBook: https://willadams.gitbook.io/design-into-3d/2d-drawing https://willadams.gitbook.io/design-into-3d/2d-drawing - using Literate Programming completely in lualatex for coding up the OpenPythonSCAD module: https://github.com/WillAdams/gcodepreview https://github.com/WillAdams/gcodepreview - in normal LaTeX (re-setting of a translation of an Old English poem) and I look forward to a future project working in LyX, since the new 2.4 looks _amazing_.
- mysteria 2y agoI write fiction using Markdown + Git and love the workflow. Now it's kind of strange treating the whole thing like a software project and having each chapter as a seperate file (along with other folders for notes, artwork, etc.) but it's easy to work with, self hostable, and the entire repository with all its history can easily travel with me on any device. It even has a Makefile to spit everything out as a PDF!
- jjice 2y agoI've been writing a book like this for a little while too. It's a great, simple workflow and having git history is just a huge benefit.
- gnulinux 2y agoThis is also what I do. I use markdown+git for all kinds of writing. I use Obsidian with tons of extensions. It's integrated with my personal knowledge base, notes etc. If I'm writing fiction or poetry, one file is one chapter/unit, but sometimes if I'm making huge changes, I'll rename that file to "Chapter X Draft 4" or something like that, so that I can instantly see very old versions without git. If I want to look at the full history git history on "Chapter X" will give the entire thing. It's also nice to write tiny scripts to assemble finished chapters into volumes etc and auto-convert to PDF. I also do literate programming (write code as if it's a book written for your future self) with this exact same approach. Just write a two line script that removes everything that's not between ```python ``` and you can code inside Obsidian. (E.g. you can use a markdown parser like `marko` for python) I personally don't need syntax highlighting, but if you do, you can open it in your IDE/Emacs/etc and IDE should highlight most languages in Markdown files. You obviously don't get all the IDE bells and whistles, for those you can have separate files and import them in, or enable Python mode in markdown files (somehow). (Obsidian should support basic syntax highlighting for most common languages anyway) Since Obsidian is so awesome, this approach has endless possibilities. E.g. you can do project management inside Obsidian via Kanban board, you can use Excalidraw tool in Obsidian to draw architecture diagrams, write music inside Obsidian with its Lilypond plugin, write math with LaTeX plugin etc. It just automatically works out of the box.
- synergy20 2y agoI too use markdown + git for everything. I checked out Obsidian one day, it appears to be a wiki with tags to me, while it's great to do notes taking for some, it seems to be less organized for myself, and it's hard to use it for books, which is more streamlined by chapters etc, am I missing something?
- 2y ago
- __alexander 2y agoIn regards to Markdown, it is nice but not many publishers are going to work with you if the book is in that format. Odds are you will have to convert it to Microsoft Word so the editors can add recommendations, version control, ask questions, apply templates, etc. I wrote a book in Markdown and converted it to Word after the third revision because editing was so painful.
- gnulinux 2y agoWill publishers not accept Latex?
- themadturk 2y agoWord makes the world go round. Perhaps specialized publishers will accept LaTeX, but most of the industry does not. Writers need to plan to transmit their manuscripts in DOCX format and to receive notes back in the same format. Of course, something like LibreOffice may be compatible enough, depending on how comments are handled.
- gnulinux 2y agoHow does one write something like a math textbook in Word, I'm curious how it's even possible. Do you handwrite every single formula in the point-and-click UI, wouldn't that be extremely time consuming and expensive?
- themadturk 2y agoProbably anyone publishing a math textbook would be happy to receive LaTeX files. Math book publishers are a tiny part of the publishing world.
- azhenley 2y agoManning allows asciidoc.
- 2y ago
- Abismith 2y ago[dead]
- mooreds 2y agoWe moved our techdoc from asciidoc to markdown to make it more accessible to devs writing docs. Felt like a step backward to me; asciidoc is so powerful, even if some of the syntax was weird.
- gouggoug 2y agoAs a big advocate of Asciidoc myself, I have to say this sounds backwards to me too. I can't imagine someone calling themselves a developer finding writing asciidoc difficult. It isn't any harder than markdown. It only has a slightly different syntax[0], and more features. I've also faced a lot of resistance from people when asking them to migrate from markdown. My, unfavorable, opinion is that it's simply the usual reluctance to change and unwillingness to learn something new, deal with the short term pain of learning, despite longer term advantages. [0]: https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/#comparison-by-example https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
- thangalin 2y agoA few notes about the reference page: * The ordered list isn't the best way to write numbered lists. Numbered lists can be: 1. 1. 1., etc. The computer will auto-increment. * Typographic quotes are an extension. I wrote KeenQuotes[0] to solve the quote curling problem and integrated it into KeenWrite[1]. * Document header. I fundamentally disagree with putting formatting instructions into plain text documents, in either AsciiDoc or Markdown. I wrote KeenWrite to completely separate the two. Documents are typeset using ConTeXt[2] and a theme[3]. * Admonitions. Pandoc (and KeenWrite) supports annotations in Markdown. I used them on page 5 of my Impacts Project[4] to insert the spectra. I'd say that annotations are more flexible than admonitions because admonitions are often canned (TIP, WARNING, etc.); whereas, annotations are user-defined. * Sidebars and block titles imply presentation. These are also handled by annotations. * Includes. You can use R Markdown to get includes. Or write an extension. Fair point that it isn't bundled, though. * Custom CSS. Again, avoid mixing presentation and content. Specific presentation logic can be applied by annotating the content, rather than trying to format plain text as though it was HTML. * Definition lists. Supported by Markdown, I use them for a glossary in a novel I'm writing. * Tables. While perhaps not CommonMark, basic tables are widely supported by almost all Markdown implementations. There's a fair amount of incorrect, biased, or outdated information on that page. Here's an example page written in Markdown and made into a PDF: https://ibb.co/mX11vZt https://ibb.co/mX11vZt That's a blockquote (story within a story) with nested annotations (the four simultaneous calls). The bigger picture is this: Why have plain text format wars? Here's an architecture I developed for my text editor: https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/docs/images/architecture/architecture.png https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/docs/imag... With that architecture, the source document format doesn't matter. Take any input document, transform it into a structured document format (such as XML), and then typeset it. Pandoc has a similar architecture. [0]: https://whitemagicsoftware.com/keenquotes/ https://whitemagicsoftware.com/keenquotes/ [1]: https://keenwrite.com/ https://keenwrite.com/ [2]: https://wiki.contextgarden.net/ https://wiki.contextgarden.net/ [3]: https://gitlab.com/DaveJarvis/keenwrite-themes/ https://gitlab.com/DaveJarvis/keenwrite-themes/ [4]: https://impacts.to/downloads/lowres/impacts.pdf?page=5 https://impacts.to/downloads/lowres/impacts.pdf?page=5
- fallinditch 2y agoIs anyone using Msty to ingest your Obsidian vaults so you can chat with your notes? This looks like it could be a powerful method for AI-assisted long form writing, technical or otherwise. https://msty.app/ https://msty.app/
- MildlySerious 2y agoTypst[1] is, imo, worth adding to the conversation. I recently used the CLI (and VSCode extensions) to put together a flyer, and I am testing it for invoice generation. So far I am quite enjoying it as a way to put together PDFs programmatically. [1] https://typst.app/ https://typst.app/
- atilimcetin 2y agoI came here to say the same thing. I have some experience with both asciidoc and typst and anybody uses/tried using asciidoc should try typst and see for themselves how good it is.
- recursivedoubts 2y agowe used typst for the second verison of https://hypermedia.systems https://hypermedia.systems and it was a significantly better experience than ASCIIDOC Repo: https://github.com/bigskysoftware/hypermedia-systems-book https://github.com/bigskysoftware/hypermedia-systems-book Blog on the port: https://denizaksimsek.com/2024/new-hypermedia-systems/ https://denizaksimsek.com/2024/new-hypermedia-systems/
- Onawa 2y agoUsing Quarto on top of Typst gives you all the media size and layout options of Typst along with quickly pivoting or adding on other outputs using Quarto. https://quarto.org/docs/output-formats/typst.html https://quarto.org/docs/output-formats/typst.html Though I use Typst on its own for my CV since I primarily needed it in PDF. Almost every other project I create starts with `quarto create project`. https://github.com/mintyfrankie/brilliant-CV https://github.com/mintyfrankie/brilliant-CV
- __mharrison__ 2y agoI just ported my md to pdf (via LaTeX) to use Typst. There are still a few nagging issues but overall Typst is 10x better than LaTeX (for my needs which is writing technical books like Effective Pandas).
- dunyakirkali 2y agoThnx for the tip. Will definitely check it out
- andrei-akopian 2y agoWhat are you guys writing that your thinking speed outperforms your writing speed to the point where you have to optimize your software and hardware? In my (very minuscule) experience in writing 99% of the time is spent switching between browser, scratchpad, notes, and standing up to take a walk and think about it. Start with the minimum possible format you can (plaintext) and step up a standard when necessary. The simpler the standard, the more software there is that just works with it.
- joevandyk 2y agoThe blog post says they use plaintext (asciidoc)?
- powersnail 2y agoI don’t think thinking speed outperforming writing speed is a necessary condition for wanting to optimize the software and hardware. Speed is rarely an issue. I’d say ergonomics, organization of information, and the “feeling” of using the tools are the driving force behind all these efforts of optimizations.
- codazoda 2y agoThey did make it sound like a lot of work. Having done it a few times, I found it easier to write in a word processor. I prefer LibreOffice. I’ve also written in Markdown and HTML, but, for me, a word processor was easier because of the other items they mentioned needing. You can add front matter and Table of Contents easily in a word processor like LibreOffice. In fact, I have a very short book about my step-by-step process on how to format and publish your own book with LibreOffice. I recently wrote a blog post giving the cliff notes version of the book in a couple pages but I seem to have accidentally deleted it. I need to go dig it up.
- renewiltord 2y agoSettings > Accessibility > Slow Keys on MacOS. Turn that on and set the delay to maximum. Now, presumably there's a number that annoys you, and even though you spend most of your time switching between apps it will annoy you when you write. So if you get annoyed there, you must imagine that there is some bell curve of reaction speed. Absent any information, it's worthwhile to imagine you at the center, a pretty median slow guy. In that universe, there is some guy who will be three standard deviations faster. Just like you were annoyed when Slow Keys was on, he's annoyed when he's in the usual mode.
- spudlyo 2y agoI write literate technical docs[0] with Emacs' Org-mode, a plaintext markup language that works well with Git, and exports nicely to LaTeX/PDF to create stunning documents with tables of contents, footnotes, page numbers, headers, footers, and all the usual niceties you'd expect from LaTeX. Many people can appreciate Org-mode the format, but aren't fond of Emacs the editor, which can be a hindrance to collaboration. The way I get around this in a professional setting is that while I'm working on documents and gathering feedback on them, I take pains to ensure that I can export snapshots to OpenDocument Text format--which can look nearly as good as LaTeX. Google Drive can import documents in ODT format and subsequently Google Docs renders them quite nicely. I accept feedback via the "suggestions" mode of Google Docs, and only after I incorporate the changes in the Org mode source do I accept the changes in the ODT/Docs version. [0]: https://www.youtube.com/watch?v=BAFZ-vTnfSo&t https://www.youtube.com/watch?v=BAFZ-vTnfSo&t
- bcantrill 2y agoIt's great to hear about someone else using AsciiDoc! We use it for all of our documentation at Oxide, so I had assumed that it was ubiquitous -- and it was only when we had a recent podcast episode about our RFDs[0] that I learned that it was really much less broadly used than I thought! Anyway, we're big fans of AsciiDoc; glad we're not (totally) alone! [0] https://oxide-and-friends.transistor.fm/episodes/rfds-the-backbone-of-oxide https://oxide-and-friends.transistor.fm/episodes/rfds-the-ba...
- arunc 2y agoWe use AsciiDoc with Antora in our company. Most of the customer facing product docs are written in it.
- Suppafly 2y agoDo you have to type the markup by hand or is their an editor that has support for it?
- dunyakirkali 2y agoAny major editor has support for it. https://docs.asciidoctor.org/asciidoctor/latest/tooling/ https://docs.asciidoctor.org/asciidoctor/latest/tooling/
- dunyakirkali 2y agoAsciidoc is awesome. I only wish that it had better integration tools with other wiki tools (confluence, notion, etc.) That way I could use asciidoc for all my documentation and sync it to whatever wiki tool the company I work for wants to have
- pbronez 2y agoThere’s a working group under the Eclipse Foundation that’s actively working to standardize AsciiDoc. I’m eager to see that effort succeed/complete.
- NoxiousPluK 2y agoOh hey a fellow ZSA Voyager user! There's dozens of us! For writing I really enjoy using WriteMonkey
- koziserek 2y agotens of dozens, even!
- softfalcon 2y agoMy brother just finished writing a fantasy novel. By the time he was finished, he had created a searchable wiki with every idea, lore snippet, and references logged into his note taking app. As easily as we would google an event in history, he could bring up the tagged items associated to a chapter, world event, or character in his book. At the late stages, when he was modifying a lot with the help of his publisher/editor, this was worth its weight in gold. Amazing level of discipline and wisdom choosing to set it up in that way for himself. I would recommend similar to anyone considering writing a book. His book was recently published and is sold in stores everywhere under the title “Gods-Forged”.
- dunyakirkali 2y agoVery interesting
- sankumsek 2y agoDo you mind sharing what note taking app it was? I've heard Scrivener alot.
- chrisdbanks 2y agoProbably Obsidian. It's popular for this because of the linking ability.
- softfalcon 2y agoHe was using Evernote and then switched to Google Drive for collaborating with the editor. I’ve in the past, suggested Obsidian. He is interested in trying it out.
- codazoda 2y agoWhat did he use as a wiki?
- softfalcon 2y agoA combination of Evernote and Google Drive. He’s going to look into Obsidian for his next books.
- AlbertCory 2y agoI use Vellum. It converts to PDF and EPUB, which is all you need for self-publishing books (I don't know about other destinations). I'd never heard of ASCIIDOC. Finally, one thing that I really, really wanted, and YMMV. There's no reason why you should care about it, but I did: drop caps (the first letter of a section is 3 or 4 lines tall). I just think it's cool. You could do it with a lot of machinations in Scrivener, but it's trivial with Vellum. Vellum knows all the things about publishing conventions. What I prefer about it is, you pay money for it. That gives them a stable business model.
- dunyakirkali 2y agoNever heard of Vellum. Thnx for sharing
- fernly 2y agoI can sympathize with the OP authors' frustration with Markdown and resulting preference for ASCIIDoc (try to format a poem, or a play script, in Markdown). Lots of people have addressed this, and NIH rules supreme -- see reStructured Text[2]. However several comments here mention the convenience of a workflow based on Markdown + GIT. Exactly that workflow is the heart of Leanpub[0]. That site facilitates writing into text files organized and stored on Github (or Dropbox), compiling at any point to a finished-looking e-text, which you can then sell via their storefront[1], or take the finished ebook or pdf to a different platform. Leanpub supports their own Markdown variant (sigh). [0] https://leanpub.com/authors https://leanpub.com/authors [1] https://leanpub.com/bookstore?type=book https://leanpub.com/bookstore?type=book [2] https://docutils.sourceforge.io/rst.html https://docutils.sourceforge.io/rst.html
- ryanbigg 2y agoThe "Writing" section here has huge "draw the rest of the owl" vibes. (I say this as an accomplished author of 10 tech books.) Yes, it's worth optimising for your productivity. It's not the be all and end all. I've written at my desk with the comfiest chair (A Mirra) I have, and the most ergonomic keyboard for my needs (Ergodox EZ). I write at cafes with just the laptop. I write on the couch at odd but comfortable angles. I write on public transport squished against strangers. I love using AsciiDoc as the tooling (asciidoctor + friends) give me output that looks decent, and the way I _input_ into that is not mind-breaking like Docbook is. Asciidoctor gives me a PDF which I then style how I like with CSS and then can put on leanpub.com and sell for real dollars. The way I would put the writing section for tech books is this: Start with the _topics_ you want to cover. Make these the chapters. Then dive into each topic and figure out what you want to say about the topic. Usually 3-4 main points per chapter. These come out to be your subheadings. Order the chapters from beginner-to-advanced concepts or in a way that makes sense for the book you're writing. For the books I've written it's usually start with a simple base app and then incrementally build things on top of that.
- dunyakirkali 2y agoYou're spot on about the "writing" section. I actually only wanted to focus on the tooling, but that lacked a little body, so I added a little bit on writing. It actually deserves its own article
- DanielBMarkham 2y agoThank you for your essay. Apologies for being Mr. Negative Guy. I hate folks that do that. But as somebody who is extremely technical and loves tools and coding, moving to long-form fiction writing, I find that every minute I spend on tooling is _not_ writing. It might be good and necessary, and tools can do some amazing things, but it's not writing. Fiction writing, at least for me, is a bit of organized struggle with my subconscious. My brain would much rather be coding, writing build scripts, creating a huge cross-layered tagging system, commenting on HN, and so forth. That's because "struggling with your subconscious" is not something we teach or emphasize. There's a really strong allure of tools, process, and tooling that calls to us when our minds don't want to do the work. Buy the product, learn the tagging, follow the recipe, etc -- it's all about hey, don't do the work, have the tool do the work. Don't be a dummy! But since I don't know the work myself until I create it, there's no tool or process that's going to do anything but distract. Love my tools, spent a lot of time with them. I spent all day yesterday re-creating and re-factoring my build pipeline from markdown to about a dozen different formats. But that wasn't work, not really. It was avoiding work by doing (hopefully) very useful tangential things. I'd love to write a tooling/process essay or book. I will not. This is why.
- firefoxd 2y agoI think you are talking to the right audience who will be excited about all the tools you shared. But to me all these things get in the way of writing. I wrote my first book (short story) entirely on gedit 2.x. It's only when I completed it that I started to use tools to automate publishing. Markdown, auto epub, html, and what not. These tools are a distraction to the process. I just posted another book I'm writing on github and was asked to share a link to it. Now that an audience is actually watching, I spent countless days building tools around it rather than writing the content. It's nice and all, but I better get back to writing the book or I'll have a beautiful pile of code that does nothing. It supports markdown though...
- dsubburam 2y agoYet to be mentioned here is writing with pen and paper... Anybody still do that? If so, what's your approach? When writing an essay, I often start with pen and paper. Mostly, an outline, and sometimes also the introductory couple of paragraphs. But I switch to a word processor when the bulk of the words start flowing.
- dmd 2y agoIn my entire life I have never been able to write more than about 50 words in a row without extreme pain.
- dsubburam 2y agoI re-learnt how to write as an adult, after a hand injury, using this handwriting manual from the ~1920s[1]. Shows positions for holding your hand, arm, etc. as well as exercises for practicing the various strokes involved (for English). [1] https://thepalmermethod.com/ https://thepalmermethod.com/
- al_borland 2y agoIf I'm having trouble getting started, I will sometimes reach for pen/paper to brainstorm and mock up a very rough outline.
- deleted 2y ago[deleted]
- dunyakirkali 2y agoI get cramps on my fingers since I'm not used to holding a pen :)
- chazeon 2y agoTo be honest, I don't understand the author's hatred of LaTeX. Maybe the experience is very different than 10 years ago? Today, if you use Overleaf, the experience is not so different from that of Google Docs / the online markdown editor. If you really want a styling other than the default one, there are a bunch of templates you can choose from. You get document history and almost real-time rendering, and you can sync to GitHub if you want. You can self-host the front end. Given Pandoc, you can easily convert it to Word; it is one of the most portable ways to write in an open format. You can collaborate on it. Honestly, it's the easiest way for me to open the browser and edit.
- dunyakirkali 2y agoNo hatred really. It just felt like going to a knife fight with a Bazooka.
- acidburnNSA 2y agoI'll have to try out asciidoc. I wrote a book in reStructuredText and loved the overall workflow and capabilities. https://digitalsuperpowers.com/blog/2019-02-16-publishing-ebook.html https://digitalsuperpowers.com/blog/2019-02-16-publishing-eb...
- didgetmaster 2y ago>We knew up front that, whatever solution we picked, it should be accessible, easy-to-use, free and preferably open-source. I'm not a Microsoft Word fan, but why does their tool need to be free and open-source? They went to great lengths to explain how the performance of the tools is so important; only to exclude anything you might have to pay for or is closed source. Who cares if you have to shell out a few bucks for something if it works well and provides great value (i.e. saves you more time and hassle than the money you paid for it)?
- dunyakirkali 2y agoIt's just personal preference. There is nothing wrong with Microsoft Word not with paying for a good tool.
- koziserek 2y agoSome people prefer to shape the world also by choosing their consumption habits, e.g.: - encourage development of libre software, to reduce entry barriers for newcomers, allow experimentation, sharing knowledge and reducing trillion-dollar companies dominance - commute with bicycle or electric vehicle, so the planet lasts longer, and anti-liberal governments controlling the resources enjoy our money little less - don't plan holidays in countries which are stuck in teocracy, autocracy or exploiting their citizens (N Korea, SA, China...) - don't buy products originating from such countries, or produced with use of child labor or animal suffering "My life amounts to no more than one drop in a limitless ocean. Yet what is any ocean, but a multitude of drops?"
- a1o 2y agoLaTeX in a repository can be accessed also using Overleaf which is a cool online platform that takes out a lot of the hard things about LaTeX. I highly recommend to anyone that haven't yet tried Overleaf to use it.
- kstenerud 2y agoI'll second the asciidoc approach. After my wife was killed by a Russian tank in Ukraine, I collected up everything she wrote (she wrote a LOT - I've collected 250,000 words so far) and needed to compile it into a book in a way that allowed easy edits and arrangements. Asciidoctor was a godsend in this regard, able to output in PDF, EPUB, MS Word, whatever you want. With Asciidoctor, ImageMagick, FFMpeg, LibreTranslate, and about 800 lines of Python code I'm now able to generate any part of the book draft in any language (this is mainly to build excerpts for publishers).
- rossant 2y agoI am so sorry for your loss. What you're doing for her is beautiful. Good luck.
- dunyakirkali 2y agothis is beautiful
- deleted 2y ago[deleted]
- duduzeta 2y agoI've been thinking of writing a book and was really excited when i heard about 37 signals' free book editing tool called writebook. Did you get the chance to try it out? Does anyone know if its worth checking out?