[zeromq-dev] RFC in Markdown?

[Kevin Sapper]

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