Hi,


On 31/12/17 06:47, Dimitris Chloupis wrote:
��

I have argued time and again and in length about Markdown support in Pharo, so I will not do it again. I'll just repeat that, in order to make Pharo less isolated, Git support for managing software source code has the strategic importance, in the same way that Markdown support for managing documentation source code has strategic importance. This doesn't preclude support for native/alternative DVCS in the software front (Monticello, Fossil, etc) or markup languages in the documentation one (Pillar, Dokuwiki, t2tags, etc).


It's kinda funny because me and Esteban have been very early on huge supporters of git and github when the rest of the community was mildly interested to passionately against it.�� I have been very vocal about it, to the point of annoying people and being accused of just supporting a overhyped product. 4 years later working with git is the official way of doing things and we even have our very own github client in the image.

Well it's kinda funny to experience the same resistance in the documentation front that we have in the Git/GitHub, even using the same old arguments. I don't like Git/GitHub, but I understand the strategic importance of it for the community. In the documentation front, each time Markdown is mentioned (with any external tool that works with it) we restart from zero to have the same old arguments (just look at the current thread).

[...]

My personal opinion on this is that using syntax for documentation in 2017 feels to me like stone age. We did not even do this in 1980. I will dare to predict and you can bookmark this post that Markdow will slowly disappear to be replaced with the proper way of doing documentation and that is through a dedicated documentation editor like Libreoffice.�� Even Google docs seem to return in favour of Markdown.

In 1980 we don't have Wikipedia and more that 5 million of articles written using a light markup language (LML). We didn't have GitHub and several devs communities writing collaboratively documentation using same kind of languages. We didn't have Ulysses[2], Ghost[3] and other apps directed towards non-devs, but bloggers and writers, using/advocating plain text and LMLs to keep you focused on writing (not typography or margins) and being able to write in small form factor screens. So I see the return in favor of LML as a progress over complicated and bloated XML files or cumbersome verbose markup languages for documentation (and their supporting GUIs).

[1] https://en.wikipedia.org/wiki/Wikipedia:Size_of_Wikipedia
[2] https://ulyssesapp.com/
[3] https://ghost.org/


The wide range of documentation formats take only a tiny fraction of the market. Adobe may have lost the war with Flash but when it comes to PDF they have won and won it easily.��

EPub for example is the least relevant format nowadays, it used be widely popular format, nowhere near to pdf but popular indeed at the time of PDAs but then iPhone came out and killed it together with Flash. Nowdays is used mostly on Kindle which is also another device that has lost most of its popularity.

ePub is still important for librarians working on public access to several works, in places where people (fortunately) doesn't have and iPhone, like in the wide Global South, from Mexico to Patagonia and beyond. In fact, recently we have a talk in the Grafoscopio mailing list about exporting to ePub the Data Driven Journalist Handbook (with the Pandoc source it was just matter of changing one parameter and voil��).


I consider myself an expert on documentation because my day job is being a lawyer and basically what we do is we write complex technical documentation for courts. Especially my kind of lawyer that do not do criminal law. I am writing legal documentation in a week what takes our community to write in years.��


I have been also close to documentation since 2002 (and I like to write long before that). From 2004 to 2008 we have the biggest wiki collection of Spanish recipes and how-to's about FLOSS with 4000 community articles. Of course this was a project in the "Global South", so nobody noticed it then, and now it slept lost in the cyberspace and somebody's offline backup. I was the main translator of TeXmacs[4] documentation to Spanish. An interactive mathematical documentation system with multiple backens long before Jupyter. So yes, I'm pretty sure that this community contains a lot of expertise in the documentation front.

[4] http://texmacs.org/

Microsoft Office has been monopolising our field to an extreme extend and I must be one of those rare exceptions that I use Libreoffice and quite frankly I dont blame them because it has its issues.��

No I am not a believer in Markdown which usage became relevant only because Github supported it out of the box. With Github Markdown is nothing.

Well, Markdown has several use cases beyond programmers and beyond GitHub, as shown above (most programmers fail to see this).


I am not a believer in LaText again, another specialised software that is used by a very specific community.����


I think its syntax is too verbose, but you don't need it all the time. You could write in (Pandoc's) Markdown (or Pillar) and tweak the parts you need using only LaTeX in the places you want, leveraging decades of experience in layout, templates, typography or kerning, without paying upfront expertise you don't need. So combining LML with LaTeX and its engines is pretty powerful (that's the approach used in most LML systems to produce PDFs).

I am not a believe in Pandoc, why bother with a million formats when only 2 dominate the market ?

Because people use them, and fortunately reality is not only about market dominance dictate and its simplistic view. To the wikipedians, the format that dominates their reality is the one in their wiki, as happens with any wiki engine user, with their particular syntax. A lot of small communities are better serve by their particular LML despite of the "global market" efforts to reduce reality to the two oligopolistic "options".

[...]

Why ?

Because either they are unnecessary hard to use or limited to what they can do.��


You can have a combination of extensible LML that combine with HTML, LaTeX or YAML, so they're easy to learn and not so limited.

If it was up to me, Libreoffice would have been our official way of documentation and the only alternative would have been an in image editor probably leveraging the existing Libreoffice API.


I am a GUI guy, anything that helps me type less and visualise more its far better option to the alternatives.��



Fortunately this was a community decision and not up to a single person. Good luck with a XML diff for a document wrote among several authors(!). TeXmacs for me had a lot of potential: WYSIWYM edition, math typography, diverse interactive backends, S expression all the way down, Lisp (Guile) scripting. But, because of the time it started, the toolkit was kind of isolated with a lot of ad-hoc, in-house solutions in a small community (at the end some Qt front-end was implemented). With Pharo we have the advantage of a continuum between the app, the IDE, the document, and that's something nobody has so evolved until now (not even the people at Mathematica or Jupyter Lab) and that makes a huge difference in the future of the application and its adaptability to the future/context.

But I have never stopped anyone from doing anything nor I tried to discourage.��

I can guarantee to you the same people that have not embraced Pillar is extremely unlikely they will embrace Markdown and Pandoc. There are two things that coders hate a) Writing documentation b) Creating GUIs. This is not going to change any time soon. Well not this millennium at least.��

In any case whatever your goal I wish you very good luck. You are going to need it.����

Coders are not my target and I'm already having luck, because our small diverse local community is already using LML for documentation.�� They're librarians, students, philosophers, historians, teachers, journalist, and even we have coders using it. So your millennium of skepticism and resistance have already expired, at least locally :-), which is why I bet on serendipity instead of luck (the encounter of luck, opportunity and preparation).

Cheers,

Offray