News:

Simutrans Wiki Manual
The official on-line manual for Simutrans. Read and contribute.

GitBooks

Started by sdog, November 18, 2016, 09:17:56 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

sdog

I've stumbled over an interesting service for collaborative writing. Using markdown in conjunction with git, in a GitHub like environment. Important is that they include a powerful toolchain to produce html, printable, and epub output. I found a lot of limitations, which would me chose git right away over it. However, I've to say, that for many projects they might be a good choice.

I've commented my test directly in my test document:

https://www.gitbook.com/book/gschenk/test/

The limitation, or rather idiosyncracy, I found most inconvenient is that for every time one saves in the online editor, a new git commit is made. These commits have non-descriptive names. As a consequence, the git log is rendered next to useless. Of course it can be avoided, when using it in the typical git way, editing locally and then pushing upstream. In other words, using them for hosting and for their impressive toolchain.* However, that loses most of their user-friendly interface, which in turn would hinder the few people who cannot use git yet.


* I've to reiterate this. I have a bit of experience trying to get documents to html like forms (epub). It is not trivial, especially when it is to be done reliably, without much tweaking, and for unknown sources.




I have found that one can disable automatic committing in the online editor. That makes it almost perfect then.



For some completely not understandable reason, one cannot simply clone, push, or pull from that repository. They haven't implemented ssh access. "There is no SSH key with GitBook (only https is supported for now, not ssh)."
There seem to be other ways, using ssh. However, that is non-trivial, as it seems to require a token to allow an API to connect. (see also https://github.com/GitbookIO/gitbook/issues/660)