[opensuse] Recommendations for Markup syntax format
![](https://seccdn.libravatar.org/avatar/ed9250d458a8eb0a4be0f5d66dadbd27.jpg?s=120&d=mm&r=g)
Hi all, I have a project that implies writing quite a lot of technical documentation. By "technical", I mean it will include: - list, numbered and unnumbered - a few tables - hypertext links of sources - a lot of footnote - excerpt of code and command lines - images - side comments (i.e. more detailed explanation about a word or notion that can't be included inline, so it won't break reading flow, but rather in side or foot notes) I already use Markdown (common markdown) a lot but I think it will be limited for my goal here. I consider using reStructuredText or AsciiDoc as I have heard that they are pretty efficient and standard format for documentation. I guess that some of you already use one of those. Do you have any advises about which one should I choose, any pros and cons of each ? Thank you in advance. Regards, -- Sébastien Poher -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
![](https://seccdn.libravatar.org/avatar/a479086d4672eb3ed901f3270071c367.jpg?s=120&d=mm&r=g)
On 11/01/2019 12:43, Sébastien 'sogal' Poher wrote:
I guess that some of you already use one of those. Do you have any advises about which one should I choose, any pros and cons of each ?
Partly it depends on which, if any, projects you would like to align with, and what tooling you want to use. Internally, SUSE works almost entirely in GeekoDoc, a flavour of DocBook XML. It's very rich and sophisticated, we have a great FOSS toolchain for it, and it lets you do almost anything you could want. But it's hard to learn and hard to read. Personally I use a very rich but sadly proprietary Java editor called <oXygen/> for it, mainly for its "author mode" preview. Geany handles it quite well. Some teams and projects use AsciiDoctor. This is the modern descendant of AsciiDoc. (The difference is the rendering tools -- AsciiDoc was written in Python, I think, and is no longer maintained. Its successor is the Ruby-based AsciiDoctor. Personally, I quite like it, and use it for drafting. RST is used by the kernel and Python teams for their docs. I have not really looked at it. Markdown is OK but too limited & suffers badly from insufficient standardisation, so there are multiple competing flavours. It also irritates me that it gratuitously diverged from the traditional *email* and *Usenet* _markup_ /conventions/ that Thunderbird and so on support. P.S. "Advice" is an uncountable noun. Like "information" it has no plural. :-) -- Liam Proven - Technical Writer, SUSE Linux s.r.o. Corso II, Křižíkova 148/34, 186-00 Praha 8 - Karlín, Czechia Email: lproven@suse.com - Office telephone: +420 284 241 084 -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
![](https://seccdn.libravatar.org/avatar/a479086d4672eb3ed901f3270071c367.jpg?s=120&d=mm&r=g)
On 11/01/2019 13:09, Liam Proven wrote:
Personally, I quite like it, and use it for drafting.
Oops. Forgot to mention tools. I use Atom for ADoc editing, because I like the AsciiDoctor preview add-in. Pluma, GEdit and Xed can also do basic highlighting of ADoc but IMHO Atom does the best job... which is bit of a shame as it is a huge bloated lump of an editor. -- Liam Proven - Technical Writer, SUSE Linux s.r.o. Corso II, Křižíkova 148/34, 186-00 Praha 8 - Karlín, Czechia Email: lproven@suse.com - Office telephone: +420 284 241 084 -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
![](https://seccdn.libravatar.org/avatar/ed9250d458a8eb0a4be0f5d66dadbd27.jpg?s=120&d=mm&r=g)
Hi Liam, Thank you for this addition information (and the english lesson, not my mother tongue, I sometimes make mistakes) :) Le vendredi 11 janvier 2019 à 01:09:27, Liam Proven a écrit :
On 11/01/2019 12:43, Sébastien 'sogal' Poher wrote:
I guess that some of you already use one of those. Do you have any advises about which one should I choose, any pros and cons of each ?
Partly it depends on which, if any, projects you would like to align with, and what tooling you want to use.
My project will be independent from any existing base. I would like to document an IT platform for a client, consisting of several services.
Internally, SUSE works almost entirely in GeekoDoc, a flavour of DocBook XML. It's very rich and sophisticated, we have a great FOSS toolchain for it, and it lets you do almost anything you could want.
But it's hard to learn and hard to read. Personally I use a very rich but sadly proprietary Java editor called <oXygen/> for it, mainly for its "author mode" preview.
Geany handles it quite well.
Seems nice but a bit overkill and, as you mentionned, it will took some time to learn. I do not exclude the possibility that this documentation will be updated by my colleagues so the learning curve should not be too steep.
Some teams and projects use AsciiDoctor. This is the modern descendant of AsciiDoc. (The difference is the rendering tools -- AsciiDoc was written in Python, I think, and is no longer maintained. Its successor is the Ruby-based AsciiDoctor.
Personally, I quite like it, and use it for drafting.
It seems pretty easy to learn and use, quite close from Markdown.
RST is used by the kernel and Python teams for their docs. I have not really looked at it.
Markdown is OK but too limited & suffers badly from insufficient standardisation, so there are multiple competing flavours. It also irritates me that it gratuitously diverged from the traditional *email* and *Usenet* _markup_ /conventions/ that Thunderbird and so on support.
P.S. "Advice" is an uncountable noun. Like "information" it has no plural. :-)
-- Liam Proven - Technical Writer, SUSE Linux s.r.o. Corso II, Křižíkova 148/34, 186-00 Praha 8 - Karlín, Czechia Email: lproven@suse.com - Office telephone: +420 284 241 084
-- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
-- Sébastien Poher -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
![](https://seccdn.libravatar.org/avatar/a479086d4672eb3ed901f3270071c367.jpg?s=120&d=mm&r=g)
On 11/01/2019 13:37, Sébastien 'sogal' Poher wrote:
Hi Liam,
Thank you for this addition information (and the english lesson, not my mother tongue, I sometimes make mistakes) :)
My pleasure. I was hoping I would not cause offence -- this is a very very common error, so common that it is becoming standard international business English, but it makes me twitch every time. To be honest, I suspect there is not much to choose between AsciiDoc/AsciiDoctor and Restructured Text + Sphinx. If you think that you might need to hack on the tooling, then it may depend if you prefer Python or Ruby. But as my team uses ADoc a little, I thought I would investigate it first, and as I personally quite like it and find it easy and logical, I have not bothered to look any further. -- Liam Proven - Technical Writer, SUSE Linux s.r.o. Corso II, Křižíkova 148/34, 186-00 Praha 8 - Karlín, Czechia Email: lproven@suse.com - Office telephone: +420 284 241 084 -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
![](https://seccdn.libravatar.org/avatar/ed9250d458a8eb0a4be0f5d66dadbd27.jpg?s=120&d=mm&r=g)
Le vendredi 11 janvier 2019 à 02:33:15, Liam Proven a écrit :
On 11/01/2019 13:37, Sébastien 'sogal' Poher wrote:
Hi Liam,
Thank you for this addition information (and the english lesson, not my mother tongue, I sometimes make mistakes) :)
My pleasure. I was hoping I would not cause offence -- this is a very very common error, so common that it is becoming standard international business English, but it makes me twitch every time.
No offence taken, I prefer to have my mistakes corrected so I won't repeat them :)
To be honest, I suspect there is not much to choose between AsciiDoc/AsciiDoctor and Restructured Text + Sphinx. If you think that you might need to hack on the tooling, then it may depend if you prefer Python or Ruby.
But as my team uses ADoc a little, I thought I would investigate it first, and as I personally quite like it and find it easy and logical, I have not bothered to look any further.
I dug a little deeper in the comparison between reStructuredText and AsciiDoctor and their tools. I think you advice (without 's') is worth following it, this format seems to suit better booth my logic and what I want to achieve with it. Thank you. -- Sébastien Poher -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
participants (2)
-
Liam Proven
-
Sébastien 'sogal' Poher