[SeasonOfDocs] reStructureText Quick Starts and References

[Jared Morgan]

Like Matteo suggested, I'm pretty sure most Code IDEs will have packages
for rST linting (such as putting in the 80 chars of underlining so it
shouldn't be that much of a problem.

If the goal is to have folks editing in GitHub, those little helpers are
not available. So it does play a factor in the barrier to contribution.

Arguably a trivial one that you learn to work around over time.

There is no suggestion that we should move away from rST. My comments about
AsciiDoc were more of an observation rather than a pitch to migrate. ;)

Jared Morgan
M: +61413005479
Google+ <https://plus.google.com/u/0/117309635670089895654/posts/p/pub> |
Twitter <http://twitter.com/!#/jaredmorgs> | Facebook
<http://facebook.com/jaredmorgs>




On Fri, 7 Jun 2019 at 06:17, Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> Hi Jared,
>
> Last time I checked, a few years back, most of our OSGeo projects were
> using RST. So I'd suggest that we should stick with it (at least for this
> round).
>
> Long term I suspect/hope someone will write a WYSIWG tool which allows you
> to save in whatever wiki or doc format your like (and transform between
> formats).
>
> Re heading style, I've seen people use 80 chars of underline for each
> heading. It makes the RST format a bit easier to read:
>
> Chapter 1 Title
>
> ========================================================
>
> Chapter 1.1 Title
>
>
> --------------------------------------------------------------------------------------------------
>
>
> On 6/6/19 6:35 pm, matteo wrote:
>
> Hi Jared,
>
>
>
> http://docutils.sourceforge.net/docs/user/rst/quickstart.html  is the
> first one and takes the form of an abridged version
> of http://docutils.sourceforge.net/docs/user/rst/quickref.html#section-structure
>
> Both are recommended by writers who need a quick reminder of syntax.
>
> thanks for the links.
>
>
> The only thing that grinds my gears about that is that you seem to have
> to stuff around with needless decoration to get the headings to display.
> Those folks who use writing IDEs like Atom an MS Code, are there good
> libraries that take away some of these rough edges?
>
> I'm using Atom, but years ago I just used gedit to write rst text. One
> thing that IMHO is really good in rst (and also markdown) is that the
> syntax is quite linear. You just have to be aware of a few steps
> (chapter, cross-references, code, links and images).
>
> Having a small cheatsheet on the table solve almost all the problems :)
>
> Matteo
> _______________________________________________
> SeasonOfDocs mailing listSeasonOfDocs at lists.osgeo.orghttps://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> --
> Cameron Shorter
> Technology Demystifier
> Open Technologies and Geospatial Consultant
>
> M +61 (0) 419 142 254
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190607/94f2796d/attachment.html>