[zeromq-dev] RFC in Markdown?

Yurii Rashkovskii yrashk at gmail.com
Wed May 18 22:53:11 CEST 2016


Doron,

I am waiting for a resolution for an gitbook.com hosting issue noted here
https://github.com/zeromq/rfc/pull/92

Yurii.

On Wed, May 18, 2016 at 1:50 PM, Doron Somech <somdoron at gmail.com> wrote:

> 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
>>
>
>
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev at lists.zeromq.org
> http://lists.zeromq.org/mailman/listinfo/zeromq-dev
>



-- 
Y.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20160518/017b7134/attachment.htm>


More information about the zeromq-dev mailing list