[zeromq-dev] RFC in Markdown?

Doron Somech somdoron at gmail.com
Wed May 18 22:50:45 CEST 2016


Hey Yurri, I missed the irc messages.

Let me know if the gibook is ready and I will change the DNS...

On Wed, May 18, 2016 at 7:57 PM, Joe McIlvain <joe.eli.mac at gmail.com> wrote:

> Awesome work, everyone!
>
> On Wed, May 18, 2016 at 9:52 AM, Yurii Rashkovskii <yrashk at gmail.com>
> wrote:
>
>> Pieter,
>>
>> That was a great PR! The site is available at
>> https://zeromq.gitbooks.io/rfc/content/ — I can see we're still missing
>> a few things, but they are fairly cosmetic and will be easy to fix, like
>> RFCs having no prominent titles (compare http://rfc.unprotocols.org/1/
>> and https://zeromq.gitbooks.io/rfc/content/42/). Barring these minor
>> details (those can be fixed any time), we're ready for a CNAME update. It
>> should be coordinated so that we lose as little uptime as possible. I can
>> do the CNAME part on gitbooks while Doron is update the DNS. Again, I am
>> available as yrashk on IRC (FreeNode). Let me know!
>>
>> On Wed, May 18, 2016 at 3:00 AM, Pieter Hintjens <ph at imatix.com> wrote:
>>
>>> 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
>>> _______________________________________________
>>> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20160518/b0024e73/attachment.htm>


More information about the zeromq-dev mailing list