| 1 |
W dniu pon, 11.09.2017 o godzinie 22∶56 +0200, użytkownik Michał Górny |
| 2 |
napisał: |
| 3 |
> W dniu pon, 11.09.2017 o godzinie 13∶29 -0400, użytkownik Michael |
| 4 |
> Orlitzky napisał: |
| 5 |
> > On 09/11/2017 01:08 PM, Michał Górny wrote: |
| 6 |
> > > Hi, |
| 7 |
> > > |
| 8 |
> > > TL;DR: I'd like to reinstate the old-school GLEPs in .rst files rather |
| 9 |
> > > than Wiki, put in a nice git repo. |
| 10 |
> > > |
| 11 |
> > |
| 12 |
> > I generally agree with you that wiki markup is terrible and that a text |
| 13 |
> > editor and a git repo is The Right Way to do things (with Jekyll or |
| 14 |
> > whatever to push it to the web). But in my experience, crappy and easy |
| 15 |
> > is a better way to get people to contribute. When I've taken wiki |
| 16 |
> > documents and moved them into git repos, more often than not I become |
| 17 |
> > the sole contributor, and otherwise-technical people just start emailing |
| 18 |
> > me their contributions (which decrease greatly in frequency). |
| 19 |
> |
| 20 |
> Rich already answered this in detail, so I'll skip it. |
| 21 |
> |
| 22 |
> > Will it be possible to build the GLEP rst files locally, and view the |
| 23 |
> > output exactly as it would appear on the website? I ask because, so long |
| 24 |
> > as you don't want to be able to preview the result, you can already |
| 25 |
> > write MediaWiki markup into a text file locally. The offline "live |
| 26 |
> > preview" ability is the killer feature of RST as I see it. |
| 27 |
> |
| 28 |
> Of course yes. However, the exactness of result depends on how much |
| 29 |
> effort you put into it. |
| 30 |
> |
| 31 |
> The 'easy way' is rst2html.py (dev-python/docutils). It will give you |
| 32 |
> a rough rendering with a standard style, i.e. kinda ugly but enough to |
| 33 |
> see if everything works as expected. You'll also see the preamble as big |
| 34 |
> mumbo-jumbo on top. |
| 35 |
> |
| 36 |
> Then, there's glep.py (dev-python/docutils-glep) which adds preamble |
| 37 |
> parsing, table of contents and some styling. AFAICS it needs a bit |
| 38 |
> handiwork (copying a stylesheet to a relative directory) but it gives |
| 39 |
> nice old-school rendering. |
| 40 |
> |
| 41 |
> Then, you can just take www.gentoo.org and run it locally. It takes |
| 42 |
> a little more effort but jekyll is really trivial to set up and run |
| 43 |
> locally. Then you see it exactly how it's gonna look on g.o. |
| 44 |
> |
| 45 |
> As a side note, we may also rename GLEPs to .rst. Then, GitHub will also |
| 46 |
> provide out-of-the-box rendering of them. |
| 47 |
> |
| 48 |
|
| 49 |
Example of GitHub rendering: |
| 50 |
https://github.com/mgorny/glep-draft/blob/preamble-test/glep-0001.rst |
| 51 |
|
| 52 |
IMO this beats the preview/editing capabilities MediaWiki gave us. |
| 53 |
|
| 54 |
-- |
| 55 |
Best regards, |
| 56 |
Michał Górny |
Archives