[zeromq-dev] RFC in Markdown?

Pieter Hintjens ph at imatix.com
Wed May 18 10:56:19 CEST 2016


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



More information about the zeromq-dev mailing list