[zeromq-dev] RFC in Markdown?

Pieter Hintjens ph at imatix.com
Wed May 18 10:46:21 CEST 2016


I can reformat all the existing RFCs as Markdown, rapidly. Let me know
if you want me to do this.

On Wed, May 18, 2016 at 9:57 AM, Yurii Rashkovskii <yrashk at gmail.com> wrote:
> Kevin,
>
> I believe we can grow a parallel markdown structure in the RFC repository,
> it won't affect the existing workflow and will allow us to change the
> formatting spec-by-spec and once we're fully ready, migrate current
> rfc.zeromq.org over to gitbooks to serve the updated contact.
>
> I would really appreciate help migrating individual specs or anything else
> in between. I am also available on IRC FreeNode (yrashk). My current plan is
> to submit a PR with an update for RFC 42 and we can grow from there.
>
> Yurii.
>
> On Wed, May 18, 2016 at 12:37 AM, Kevin Sapper <kevinsapper88 at gmail.com>
> wrote:
>>
>> I'm all in for migrating to Markdown given that almost everybody is
>> familiar with it. Regarding "more powerful" markup languages like
>> ReStructuredText or Asciidoc, IMO they're more complex but not at all more
>> powerful.
>>
>> @Yuri if you need any help migrating let me know!
>>
>> //Kevin
>>
>> 2016-05-18 8:08 GMT+02:00 Dinu Gherman <gherman at darwin.in-berlin.de>:
>>>
>>> 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
>>>
>>> _______________________________________________
>>> 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



More information about the zeromq-dev mailing list