Hi, I'm a big fan of the **reStructuredText** (rST) markup language: It's a quite simple but still powerful notation to write complex content. It's used a lot in the documentation of software libraries, but frankly I think it has the potential to replace Word and/or LaTex for academic publications.

Once you've written your rST manuscript (a simple editor is enough for that), you can turn it into PDF (via Sphinx & LaTex), HTML, EPUB etc. There are even online service like https://notex.ch that make it very easy for you to learn this language.

Now, what I don't understand: When I mention rST to my PhD friends or people who in general write complex content, the usual reaction is either complete fascination or simply (continued) ignorance!

I think Word is really simply a bad choice if people want to show their thesis in a presentable manner, since although it is *possible* to write nice looking content, it's very easy to screw things up. On the other hand I really understand people who can't stand LaTex either due to it's cryptic language to express content **and** presentation (layout configuration, styles etc.) within the same document.

When I stumbled upon rST - which has been created about 10 years ago - I was immediately converted and never looked back on Word or even LaTex. But, when I preach it's benefits to PhD/MSc candidates then they usually say nice, but keep using Word/LaTex. .. I don't get it.

So my question would be: Why? Is maybe something with rST wrong? In terms of complexity it is somewhere between Word and LaTex. Or is it that Word users simply refuse anything that looks remotely tech and LaTex users have been using it since eternity, and they will keep using it for another eternity?

What I try to figure out is the psychology of potential users and the way users are attached to a particular piece of software; any insight here is very much appreciated. Thank you! :)

My first impression is that it looks good for someone who doesn't already use LaTeX (like myself) as the learning curve may be less steep. It's also quite neat that you can export as HTML and LaTeX, not only PDF :)

The biggest problem that I can see is that the documentation is sparse and very 'techie'.

Installation of Word is a no-brainer (MS Office Suite has to be easy to install and use, given its target market is like everyone under the sun), and although LaTeX is a little more complex, there is an abundance of online support. And from my not-so-deep peruse of how to get the environment for rST up and running on my machine, I'm finding the documentation very unwieldy.

The fact that you have to have python up and running would probably be confusing too. I can't really imagine anyone who isn't of a technical background and who doesn't already know how to script (in which case, would probably already be using LaTeX) be persuaded to use it otherwise.

I used Word for my thesis.

Why? cos it was already on my computer......... because it was easy to send things to my supervisors who also used it.......... because it was all I'd known for the last how ever many years and I didn't (and still don't) know what the alternatives do that Word can't....... and finally because I had no problems with Word, so there was nothing to give me the push to use other things.

hi hsk81
thanks for posting! I have not heard of **reStructuredText** (rST) so thank you for introducing this to me.

I only started using Latex because Word was running very slowly on my mac--and there was some incompatibility when I worked on my Word.doc on the pc--and then on the mac, and problems with referencing also occurred across platforms.

I wrote my thesis using LaTeX and for journal drafts I use Word because my supervisor likes word and doesn't really want to learn anything new.

For people to use rST (or Latex, whatever..and etc.) they need to have trouble-shooting tips and solutions, I think this is the biggest obstacle to using it. People generally want to do things painlessly.

I know about pain (HAHAHAHA) because I went through 2+ difficult weeks learning latex by myself. When I went online to see the issues and solutions on the latex forum, at first I couldn't even understand what users were talking about!!!

will you be using rST all the way then?
love satchi

@contradirony

Do you know if it is possible to export LaTex documents to HTML or EPUB? Since I started using rST, my corresponding knowledge about the LaTex toolchain is a little dated. So you think having a book like **reStructuredText for dummies** would be of some help? It seems that this relatively new markup lacks awareness (compared to latex, which every tech oriented university seem to have in their "required" skill sets).

I mean, I don't think convincing tech savvy people like you to switch from LaTex to rST is possible, but maybe some 1st semester tech student might be inclined to give it a try. Interesting, so you found that the condition of setting up Python put's people already into a certain category; what about online services like https://notex.ch which eliminate installation & maintenance issues: Do you think people would be willing go for it?

@catalinbond

So you seem to be a happy Word user; I'm fine with that: I'm not a religious preacher trying to convince everybody of the "right" path. I think for every subset of people with different backgrounds there are various software solutions.

Still, may I ask how long your thesis was? How many images did you have? Did you have a table of content, footnotes and an index at the end? What about version management? Text based solutions like rST (or LaTex) can usually be combined with a version-ing system like GIT (or SVN/CVS), so you have all the time access to **older** versions of your draft.

And as with *any* software there are *always* problems: E.g. LaTex is for many people simply to techy, rST seems to be underdocumented; what about problems you faced with Word? I really would appreciate if you could share one or two "incidences/irritations" however small you had while working with a WYSIWYG editor like Word; thank you.

@satchi

At lease *somebody* who seems to like rST; yay! ;D Mmh, I fear that will be one of the problems for rST; people have invested a certain amount of time and energy to learn a particular technology and you have to have *really* good arguments make people give up on that investment. I see .. on Stackoverflow you already find many good tips people are sharing which each other; it is by no means comparable to the sophistication of LaTex forums [which is a much more powerful, but also *harder* language to learn], but people seem already be helping out each other. Another forum I've just recently seen is https://notex.ch/forum: Since it seems relatively new there are not that many people using it, **but** you do have a dedicated sub-forum for rST. That was pretty much my reaction: I mean I really loved how of much **better** LaTex generated PDFs looked like compared to Word, but the amount of investment people had to put into getting certain things done struck me a little out of proportion.Definitely! I write the actual **content** with rST, but w.r.t. *customized* styling (**presentation**) I stick to LaTex.

Stay away from Sphinx. It's terrible.

It has
* extremely limited markup (no bold and at the same time italic text, no text-colour, no fine control over tables)
* Bad pdf output (tables with column / row spanning is broken; image placement is restricted)

If you want to do good writing, use LaTex or Asciidoc (via asciidoctor)!
Asciidoc is really great, if you want a easily human-readable source. (It has none of the problems mentioned above).

I have a question when I try to write my paper with ReST.
How can I add citation at the end of my paper just like Word does? Is the citation often located at the bottom of the page when use citation(or footnote)?

Hi CHxin,

You may want to consider starting a new thread with this question, as the original post was 5 years ago! :)