[zeromq-dev] RFC in Markdown?

Doron Somech somdoron at gmail.com
Wed May 18 10:54:00 CEST 2016


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


More information about the zeromq-dev mailing list