[zeromq-dev] RFC in Markdown?

[Dinu Gherman]

I’m not super-familiar with http://gitbook.com, but it seems to have a high overlap with http://readthedocs.org which is based on http://www.sphinx-doc.org with its gazillion plugins for programming and natural languages and rendering styles.

So I just recommend to have a closer look at that, maybe, too, especially since nowadays readthedocs.org also works with Markdown and not only with ReStructuredText (which I still consider to be more powerful, though). I’ve found this comparison, which doesn’t go very deep, though: https://civicrm.org/blog/michael-mcandrew/experiments-with-read-the-docs. You might be able to find better ones if you spend some more search cycles.

Cheers,

Dinu

> Pieter Hintjens <ph at imatix.com>:
> 
> We don't need upfront agreement :-) We have a problem with the current
> wiki; you have a solution, let's move ahead...
> 
> On Wed, May 18, 2016 at 6:38 AM, Yurii Rashkovskii <yrashk at gmail.com> wrote:
>> Pieter,
>> 
>> Actually, gitbook works perfectly with GitHub. This is how eventsourcing is
>> set up: https://github.com/eventsourcing/rfc is the source of truth and
>> gitbook.com takes care of rendering the gitbook and mapping to a custom
>> subdomain (http://rfc.eventsourcing.com).
>> 
>> I am happy to help out with the transition if there's an agreement around
>> this. We can keep the repo in place, convert the documents and set up a free
>> gitbook.com account and change the CNAME to use gitbook.com (and even if
>> they go out of business, it's fairly trivial to go the self-hosting route)
>> 
>> On Tue, May 17, 2016 at 9:33 PM, Pieter Hintjens <ph at imatix.com> wrote:
>>> 
>>> I think this is a great idea!
>>> 
>>> Your use of gitbooks for the event sourcing RFC proves it works. What
>>> we use now is about ten years old; the Wikidot format works fine, so
>>> does the platform, but we've fragmentation between the git repository
>>> and the published RFCs.
>>> 
>>> It's fairly easy to convert the current format to Markdown; I do this
>>> when writing books. Here's the Perl that does that:
>>> https://github.com/hintjens/mkbook/blob/master/bin/mkmarkdown
>>> 
>>> Yurii, would you like to take the current RFC repo and migrate it to
>>> gitbook? We don't need to keep the repo on github, afaics. We can
>>> freeze work on RFCs in the meantime. Then we can set up the domain
>>> names or redirect so that rfc.zeromq.org goes to the new site.
>>> 
>>> -Pieter
>>> 
>>> On Wed, May 18, 2016 at 6:07 AM, Yurii Rashkovskii <yrashk at gmail.com>
>>> wrote:
>>>> Hi,
>>>> 
>>>> I was wondering if any thought has been given to (potentially) using
>>>> Markdown as a format for RFCs? Pieter asked me if I can ask this
>>>> question on
>>>> the mailing list
>>>> (https://twitter.com/hintjens/status/732779844107415552)
>>>> 
>>>> I know Markdown isn't perfect in more than one way, but given its
>>>> widespread
>>>> adoption and support by different tools (of most importance being
>>>> GitHub,
>>>> probably), was there any consideration to switch over or to duplicate
>>>> them
>>>> in Markdown (if there are automated converters between the syntaxes)?
>>>> 
>>>> In another project's RFC repository, I've decided to use it and it is
>>>> giving
>>>> me immediate results, such as:
>>>> 
>>>> 1. Being able to preview resulting markdown when editing using GitHub
>>>> editing tools (great way to contribute to RFCs quickly without having to
>>>> go
>>>> through branching on a laptop)
>>>> 2. Being able to see the formatted text of the RFC right on GitHub:
>>>> https://github.com/eventsourcing/rfc/tree/master/1
>>>> 3. Being able to use gitbooks to enable even nicer layout and beautiful
>>>> search: http://rfc.eventsourcing.com/1/
>>>> 4. Being more open for contributions as a lot more people are familiar
>>>> and
>>>> comfortable with Markdown (totally an unscientific observation!).
>>>> 
>>>> Thanks!
>>>> 
>>>> --
>>>> Y.
>>>> 
>>>> 
>>>> _______________________________________________
>>>> zeromq-dev mailing list
>>>> zeromq-dev at lists.zeromq.org
>>>> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>>> _______________________________________________
>>> zeromq-dev mailing list
>>> zeromq-dev at lists.zeromq.org
>>> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>> 
>> 
>> 
>> 
>> --
>> Y.
>> 
>> 
>> _______________________________________________
>> zeromq-dev mailing list
>> zeromq-dev at lists.zeromq.org
>> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev at lists.zeromq.org
> http://lists.zeromq.org/mailman/listinfo/zeromq-dev