> 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. Pandoc has a feature set far, far longer and more important that Pillar and > Markdown, including Yaml metadata blocks, fine grained exportation control, > ePub and a myriad of other output (an input) formats support (see graphic > below), a community that is mostly devoted to discuss extensively/mainly a > lightweight markup language for "full stack" documentation, scholarly > Markdown community for academic writing, annotated Markdown for > collaborative editing and writing, programmable templates, multilingual > scripting support, including embedded one for Lua (which came pretty handy > to import our most recently publication[1][1a]). And that just to mention > some prominent features in the greater feature set that just Pillar or > Markdown provides. As community we need to not blind ourselves to > alternatives and overcome the Not Invented Here Syndrome, to see value in > what is done outside Pharo for documentation in the same way we have done > for software management (specifically Git). > > A playground for Markdown will enhance Pandoc integration, which we > already have in Grafoscopio, but writing medium to long texts in it, using > the current plain text input objects support is cumbersome. Despite that we > have managed to have long book sized texts redone in Grafoscopio in an > agile way. The Data Driven Journalism Handbook [2] has 300+ pages (13 Mb > PDF) in a single Grafoscopio notebook, stored under just a 600kb STON file > (and a 500 kb exported Markdown file). > > [1] > http://mutabit.com/repos.fossil/dataweek/uv/Artefactos/BibliotecaDigitalBogota/pasos-para-bidibog.pdf > [1a] > http://mutabit.com/repos.fossil/dataweek/doc/tip/Artefactos/BibliotecaDigitalBogota/intro.md > [2] http://mutabit.com/repos.fossil/mapeda/ > > Several times, when I ask questions about Markdown, I'm pointed towards > the Pillar existence, and I reiterate/expand my motives for wanting to > implement *Markdown* support in Pharo. This exercise allow me to reiterate > my questions in a more precise manner and hopefully this time someone will > point me to a starting place about how to create a "playground for > Markdown". > > Cheers, > > Offray > 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. 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. 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. 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. I am not a believer in LaText again, another specialised software that is used by a very specific community. I am not a believe in Pandoc, why bother with a million formats when only 2 dominate the market ? I am not even a believer in doc string apis that exist for creating reference documentation from inside code. Why ? Because either they are unnecessary hard to use or limited to what they can do. 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. 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.
