[zeromq-dev] RFC in Markdown?

Yurii Rashkovskii yrashk at gmail.com
Fri May 27 19:42:24 CEST 2016


Looks like http://rfc.zeromq.org is now starting to resolve to gitbooks
(depending on your nameserver's caching) — thanks Doron! — and it seems to
work well so far.

On Wed, May 18, 2016 at 1:53 PM Yurii Rashkovskii <yrashk at gmail.com> wrote:

> 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/20160527/fec1e9fd/attachment.htm>


More information about the zeromq-dev mailing list