[zeromq-dev] RFC in Markdown?

Pieter Hintjens ph at imatix.com
Wed May 18 12:00:46 CEST 2016


Done, pull request made. The old .txt files can be removed in a next sweep.

On Wed, May 18, 2016 at 11:05 AM, Pieter Hintjens <ph at imatix.com> wrote:
> OK, I'll make the same structure.
>
> On Wed, May 18, 2016 at 10:58 AM, Yurii Rashkovskii <yrashk at gmail.com> wrote:
>> Pieter,
>>
>> this is great — will you be able to generate them using the directory layout
>> in https://github.com/zeromq/rfc/pull/88? We can change it later if better
>> ideas will surface.
>>
>> Yurii
>>
>> On Wed, May 18, 2016 at 1:56 AM, Pieter Hintjens <ph at imatix.com> wrote:
>>>
>>> OK, I'm writing some Perl to make the conversion and will push the .md
>>> files when they're ready.
>>>
>>> On Wed, May 18, 2016 at 10:54 AM, Doron Somech <somdoron at gmail.com> wrote:
>>> > Markdown will be great. Let me know when it is ready, I will change the
>>> > DNS
>>> > record for rfc to gitbook.
>>> >
>>> > On May 18, 2016 11:47, "Pieter Hintjens" <ph at imatix.com> wrote:
>>> >>
>>> >> 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
>>> >> _______________________________________________
>>> >> 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