Re: [gentoo-dev] [RFC] Reinstating old-school GLEPs masterplan

[Michał Górny]

W dniu wto, 12.09.2017 o godzinie 00∶07 -0700, użytkownik Daniel
Campbell napisał:
> On 09/11/2017 01:56 PM, Michał Górny wrote:
> > W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael
> > Orlitzky napisał:
> > > On 09/11/2017 01:08 PM, Michał Górny wrote:
> > > > Hi,
> > > >
> > > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather
> > > > than Wiki, put in a nice git repo.
> > > >
> > >
> > > I generally agree with you that wiki markup is terrible and that a text
> > > editor and a git repo is The Right Way to do things (with Jekyll or
> > > whatever to push it to the web). But in my experience, crappy and easy
> > > is a better way to get people to contribute. When I've taken wiki
> > > documents and moved them into git repos, more often than not I become
> > > the sole contributor, and otherwise-technical people just start emailing
> > > me their contributions (which decrease greatly in frequency).
> >
> > Rich already answered this in detail, so I'll skip it.
> >
> > > Will it be possible to build the GLEP rst files locally, and view the
> > > output exactly as it would appear on the website? I ask because, so long
> > > as you don't want to be able to preview the result, you can already
> > > write MediaWiki markup into a text file locally. The offline "live
> > > preview" ability is the killer feature of RST as I see it.
> >
> > Of course yes. However, the exactness of result depends on how much
> > effort you put into it.
> >
> > The 'easy way' is rst2html.py (dev-python/docutils). It will give you
> > a rough rendering with a standard style, i.e. kinda ugly but enough to
> > see if everything works as expected. You'll also see the preamble as big
> > mumbo-jumbo on top.
> >
> > Then, there's glep.py (dev-python/docutils-glep) which adds preamble
> > parsing, table of contents and some styling. AFAICS it needs a bit
> > handiwork (copying a stylesheet to a relative directory) but it gives
> > nice old-school rendering.
> >
> > Then, you can just take www.gentoo.org and run it locally. It takes
> > a little more effort but jekyll is really trivial to set up and run
> > locally. Then you see it exactly how it's gonna look on g.o.
> >
> > As a side note, we may also rename GLEPs to .rst. Then, GitHub will also
> > provide out-of-the-box rendering of them.
> >
>
> To preface, I really like the idea to do this in Git. Much as I
> appreciate what the wiki team has done, collaboration isn't quite as
> smooth on it and as another person mentioned, it's hard to get reviews,
> so you get to choose to leave something in your userspace (I liked your
> Drafts namespace idea, fwiw) or edit a page anyway and hope for the best.
>
> That said... Is it wise to rely on Ruby (via Jekyll) for critical
> reference documents, given how often minor version bumps in Ruby disrupt
> its ecosystem?

The point of using ReST (i.e. an established markup) and git
(established VCS) is to avoid depending on any particular software to
get things working, and to make it easy to replace the guts
as necessary.

Jekyll is what infra uses at the moment, so I see no reason to reinvent
the wheel just to prove the point.

>  Do we really need the entire www.gentoo.org repository in
> order to view and hack on GLEPs?

No, you don't.

>  I see little reason for GLEPs to not be
> in their own repository, depending on something more stable than Jekyll
> and Ruby.

They are, and they don't depend on Ruby at all. In fact, you can view
them using a line printer if you like.

>  Given that the doc tools themselves are written in Python, it
> makes more sense (imo) to leverage Gentoo's existing technical
> investment in Python and use something like app-text/pelican, which is
> equally, if not more capable than Jekyll and will not require pulling in
> Ruby just to hack on and preview some text. Every Gentoo system comes
> with Python unless you go off the beaten path and know what you're
> doing, so that's a bonus, too.

See the first part of my reply to R0b0t1.

> Of course, this changes if we need some extremely advanced behavior. I'm
> not sure how easy it is to build a Pelican plugin, but there's an entire
> repo full of them. [1] Pelican also uses a Makefile you can hack on
> (even multiple publishing targets), and supports GNU gettext for
> translations.
>
> Or is Jekyll chosen purely because the current website is built with it?
> In that case, it at least makes sense despite the heavyweight dependencies.

That's exactly the point. I'm sorry, I thought it was obvious from what
I have written.

> If anyone's interested in seeing a mockup of a few GLEPs in Pelican, I
> can get that started.

You sure can. However, I have serious doubts about the value of
establishing yet another framework for a single thing that nobody will
afterwards use or maintain. See SMW.

>
> Whether or not the structure works on GitHub is orthogonal to the
> decision. Still, put me down in favor of switching to Git. Thanks for
> putting together the proposal.
>
> [1]: https://github.com/getpelican/pelican-plugins

-- 
Best regards,
Michał Górny