Hacker News Reader

Comment by AaronO | Hacker News Reader

You also might want to take a look at GitBook (https://www.gitbook.com/).

It supports both Markdown and AsciiDoc and is used by authors to write books, documentation, research-papers (GitBook has great TeX support, in all outputs: web, pdf, epub, mobi). (Here's a math heavy book for example: http://jandeleeuw.gitbooks.io/bras1/content/blockrelaxation/...)

The format and toolchain itself is open-source (https://github.com/GitbookIO/gitbook)

There's a ecosystem built on top of that such as a Desktop Editor (https://www.gitbook.com/editor), plugins (http://plugins.gitbook.com/), and more ...

I don't want to hijack the current thread, Madoko seems really cool, I thought some of you might be interested in a more established solution. I'm happy to answer any questions !

Disclaimer: I'm one of the GitBook co-founders

View on HN

You also might want to take a look at PollPub: (http://pollenpub.com)

Discussed here on HN previously: (https://news.ycombinator.com/item?id=10030585)

This reinforces some ideas that have been percolating in my brain for about two years. Between Gibook, PollenPub, and now Madoko it is now apparent that for the first time in its existence LaTeX is getting some competition.

What LaTeX gets right is that it produces beautiful structured academic-type (references and figures and such) documents. What it gets wrong as Gruber's Markdown has shown us is that the basic units of text should look like text and trigger markup through whitespace and intuitive but ultra-minimal markup such that without a processor it looks like an anally retentive writer produced the document. It codifies ascii practices. It's one of those ideas that until it happens you'd never think of it but afterwards you're going, "of course!". Besides Python and Markdown, do any file formats work this way?

I'm not going to make a Steve Yegge type predication but if I were I'd say that some form of scholarly markdown with multiple toolchain implementations (with git integration) is going to oust LaTeX as the structured document tool of choice. Be interested in what others have to say on the matter.

One of the basic tenets of TeX and LaTeX is stability, Maths has a very long shelf life! You can TeX Knuth's papers from 30 years ago and they will still produce the same output. If I were to spend 3-5 years on writing a PhD Thesis the investment in learning LaTeX is minimal compared to the rest of the effort. With a new extended markdown markup, you will still need to learn a new syntax and LaTeX markup for example if you wanted to include TikZ code.

TeX and friends has adapted over the years through external tooling, without changes to the core, for example moving from postscript to pdf, the new engines XeLaTeX and LuaTeX. Madoko is just a preprocessor for LaTeX. If you had to finally do some changes to the LaTeX code it produces it will be very difficult as this LaTeX code is not very clean. Having said this though Madoko and similar projects are great for the LaTeX community, as an entry point to newcomers and to occassional users. It is a great Project especially as is written in Koka in itself a beautiful Project.

+1 for Madoko as it's free and Gitbook is not. I can use Madoko to create and publish my content and keep 100% of the income unlike Gitbook that takes a cut.

How dare someone provide a service for remuneration!

He didn't seem to be arguing against the principle of charging for the service. But, from a user's viewpoint, having to pay for something is rarely an argument in its favor.

It's called "trying to capture more value than you add." Seems to be a key idea behind many SaaS/PaaS startups these days. Not an indicator for long-term success.

Well that's a judgement call for the user choosing the service. If they think the value is there, they will pay. That's how capitalism works, and I daresay if Gitbook had it wrong, they'd have given up by now.

What experience do you have with Gitbook to deem that it doesn't add enough value to deserve the payment?

Free and FOSS, the latter being more important. I can customize and self-host Madoko.

> The format and toolchain itself is open-source (https://github.com/GitbookIO/gitbook)

How does your tool handle cross-references to #include'd pages? I have some home-grown tools that basically use a C++ preprocessor to assemble one big Markdown file from per-chapter or per-section chunks. What I struggle with (to do elegantly) is having robust cross-references, and to keep header levels consistent (e.g. when you include a section that itself has headers inside a h1 or inside a h2, you'd want the section's headers to become h2 or h3, respectively).

Do you have any support for reviewing, in a way similar to Word's 'Review' (comments and tracking addition deletions)? Using version control and branches is not OK, because non-software people cannot wrap their heads around it (just getting them to write in anything but Word is already a big enough hurdle...)

Do you have a proposed workflow to work with formulas? Inline TeX (or LaTeX) is again a no-go, it's too finicky to get right for people who don't have Edit/Compile/Preview Stockholm syndrome (bitter? me? nah). What I'd settle for is a separate file for each formula, and a graphical editor that can edit those files. A somewhat convenient desktop-based editor that'd give an overview of everything would be better (so having some way to start EqualX from your desktop tool would be enough).

A couple questions:

Your website talks about GitHub. Is it specific to GitHub or does it work with any Git repository?

What if you shut down? How do I continue to produce my book/paper?

All books are stored as git repositories so you get branching, history, etc ... out of the box.

We have great GitHub integration because it's the main Git host out there, we store git repos too.

If we shutdown, our toolchain and book format is already open source (https://github.com/GitbookIO/gitbook), so no matter what you'll always be able to use that to build your book locally. Secondly our Desktop Editor (https://www.gitbook.com/editor) works offline so you could even continue to use that. And well since your book is a git repo, you can have a local copy, a copy on GitHub or any other git server of your choice. So I think you should be good :)

We don't believe in vendor lock, we're big supporters of open-source and we want users to use our tools and platform not because they're obliged to, but simply because it's the best workflow/product for them.

Does that make sense ?

Sounds like you have addressed my concerns.

See also RMarkdown. It also has very good support for TeX equations, plus inline R code, and it uses Pandoc behind the scenes to handle multiple ouput formats (even .docx!) as well as bibliography. The big caveat for now is poor support for internal cross-references.

Love this idea, might copy my current novella on the web (http://www.flailfast.com/) over to your platform to see how it looks. Out of curiosity: any chance you guys might integrate bitcoin donations/payments in addition to USD?

Seconding Bitcoin integration. Thanks for mentioning it. Your story looks interesting too.

> GitBook has great TeX support

You probably want to update your website in that case: "Markdown, books are written using the markdown or AsciiDoc syntax. TeX support is planned."

Ahh, I also was thinking there is some TeX templating support... What they have is only KaTeX for math formulas.

By TeX support I meant that we fully support TeX equations.

The website mentions TeX but means LaTeX, I'll get that fixed, sorry for the confusion.

Our TeX support allows you basically to write Markdown/Asciidoc and use TeX formulas wherever you need to, which gives you the best of both worlds (the simplicity of Markdown and the power of TeX formulas).

FWIW I still found it confusing. I think you'd better leave out the 'is planned' part all together (just makes it seem half-finished), and instead replace that with 'TeX equations are fully supported.'.

Hehe, I had the same idea for my master thesis. A asciidoc academic paper editor.

Still not finished it, since I wanted to make it realtime collaborative.

Thanks for sharing. I didn't realize how much improvement has been made to GitBook, glad to try it again for my manuals.

Reply on news.ycombinator.com