[zeromq-dev] RFC in Markdown?

Yurii Rashkovskii yrashk at gmail.com
Wed May 18 06:38:30 CEST 2016


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


More information about the zeromq-dev mailing list