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

[Daniel Campbell]

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? Do we really need the entire www.gentoo.org repository in
order to view and hack on GLEPs? I see little reason for GLEPs to not be
in their own repository, depending on something more stable than Jekyll
and Ruby. 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.

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.

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

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
-- 
Daniel Campbell - Gentoo Developer, Trustee, Treasurer
OpenPGP Key: 0x1EA055D6 @ hkp://keys.gnupg.net
fpr: AE03 9064 AE00 053C 270C  1DE4 6F7A 9091 1EA0 55D6