[zeromq-dev] RFC in Markdown?

Yurii Rashkovskii yrashk at gmail.com
Wed May 18 09:57:10 CEST 2016


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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20160518/54ad75f1/attachment.htm>


More information about the zeromq-dev mailing list