[zeromq-dev] RFC in Markdown?

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


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


More information about the zeromq-dev mailing list