P.S. +1 for including pillar in the 6.2 image , then start working on the document tree and see how it can be adapted.
On 8/15/17, H. Hirzel <hannes.hir...@gmail.com> wrote: > Offray, > > thanks for the nice write-up about the general usefulness of Markdown > for writing papers. > > Stephen D. wrote yesterday in a terse way > > "We can change the syntax or propose an alternate one as soon as it > uses the same internal structure. > > Stef" > > This means that Pillars tagging system may be changed to a more > generally known tagging system later. > > I assume with 'internal structure' he refers to the AST/Document > Object Model of Pillar which would need to be aligned with one of > another markup system. > > Maybe the gap is not all that large. > > Personally I think as well that if Pharo could also be used as a > markdown (commonmark) editor with its tool-chain to generate different > types of documents would expand the area of application considerably. > > --Hannes > > > On 8/15/17, Offray Vladimir Luna Cárdenas <offray.l...@mutabit.com> wrote: >> Hi, >> >> While I appreciate the historical perspective, I continue to be with Tim >> on this (and I consider myself part of the Pharo Community). I have also >> personal preferences for other light markup languages (like txt2tags[1] >> and dokuwiki's[2]), but I will stick with Pandoc's Markdown, because is >> support everything Stephan or any professional author wants to do and in >> fact you can create full books with it, including references, tables, >> images, and bibliographic references (which are not supported by Pillar >> AFAIK), but also because is an emerging standard beyond the programmers >> community, including academicians and researchers with the Scholarly >> Markdown[3] initiative and with possibilities to import and export >> from/to several markup languages[4]. >> >> [1] http://txt2tags.org/ >> [2] https://www.dokuwiki.org/wiki:syntax >> [3] http://scholmd.org/ >> [4] http://pandoc.org/ >> >> I don't share the vision of particular communities choosing particular >> markup languages as default, because, if you already payed the price of >> learning that particular language/environment, you are willing to pay >> the price with whatever that community choose in other fronts like DVCS >> or markup languages. Python community supports reST, but also markdown >> and several other markup languages and Jupyter notebooks[5] user >> Markdown by default. In fact, the Iceberg Git support shows the >> increasing concern to bridge the Pharo world with the stuff you already >> know and I think that a similar approach should be taken in the >> documentation/markup front, even if this implies breaking compatibility >> with the canonical Smalltalk way (TM) (I really like that critical >> approach from Pharo to the past). >> >> [5] http://jupyter.org/ >> >> That being said, I don't think that should be exclusively one way or >> another. We can have Pillar and (Pandoc's) Markdown, if the community >> doesn't reach and agreement on only one. >> >> I plan to explore the Brick editor once I have time and will try to add >> Pandoc's Markdown support. Unfortunately, in the past I have not had >> many luck testing and giving feedback on Moose alpha releases of tools >> and my questions/comments on them remain largely unanswered or simply >> ignored for long time (or just forever), so my priority on testing these >> tools have just decreased, but once Brick editor become more well >> supported, Pandoc's Markdown support for it will be in my target and >> concerns. >> >> Cheers, >> >> Offray >> >> On 14/08/17 12:48, Jimmie Houchin wrote: >>> >>> Thank Tim, >>> >>> My primary reason to submit the message was not to necessarily >>> persuade you per se. But to provide something historical for the >>> mailing list as this can be a recurring subject. Why use Pillar markup >>> instead of ???(insert personal favorite). >>> >>> If Pharo were to decide on a different markup language. The question >>> would still be which one, why and then how do we proceed. Then our >>> extensions may not be accepted by the greater body of users of said >>> markup. We would still be contributing to the fragmentation of markup. >>> As far as familiarity, I don't know. And familiarity with what. I do >>> not find that reStructuredText to be similar to Markdown. >>> >>> It would stop people from asking why we aren't using Markdown. But it >>> wouldn't prevent others. Why aren't we using GFM Markdown, or Kramdown >>> or Commonmark or ...? Why aren't we using YAML or reST or AsciiDoc or >>> insert latest greatest creation markup or current flavor of the >>> moment. Which is why I wanted to point out that there is no consensus >>> among users of markup languages. At least I do not see one. Nor do I >>> believe that we have seen the end of creation of new markup languages. >>> >>> I understand the difficulty, though I do not suffer from it as I have >>> not mastered any of those other languages. I have been using >>> Squeak/Pharo for a long time. I struggle when I look at those other >>> languages. To me they are the foreign ones. >>> >>> And I do not see these emerging standards you refer to. When we see >>> Python, Ruby, Perl, C++, various projects, etc. communities having >>> consensus on a common markup for documentation. Then I see an emerging >>> standard. Until then it seems to possibly be an emerging standard for >>> a particular markup language which is among the set of markup languages. >>> >>> If we were the only language and development environment doing our own >>> thing. Then we might have a very good reason to talk. But we are not. >>> Python with its enormous community does its own thing. I don't know >>> that other languages have a consensus for markup for documentation >>> except for Python and Pharo. >>> >>> While writing this email I went and discovered that even GitHub is not >>> dogmatic about the subject. Obviously they have an opinion. But they >>> permit multiple markup languages. Quite possibly someone could write a >>> Pillar tool for GitHub to use and then we could just submit >>> Readme.pillar for our projects. :) >>> >>> https://github.com/github/markup >>> >>> Shows that GitHub allows for .markdown, .mdown, .mkdn, .md; .textile; >>> .rdoc; .org; .creole; .mediawiki, .wiki; .rst; .asciidoc, .adoc, .asc; >>> .pod. So it seems that there are many communities on GitHub who >>> prefer their own markup and tools. >>> >>> We could possibly write the Pillar tool for GitHub or an exporter to >>> the preferred markup language of the above. >>> >>> This author provides arguments for using reStructuredText over >>> Markdown for GitHub documents. Citing deficiencies in Markdown and >>> expressiveness in reST. >>> >>> https://gist.github.com/dupuy/1855764 >>> >>> So again. I am just not seeing a consensus around any emerging >>> standard for "the markup language". >>> >>> At the same time if you are desirous of writing in Commonmark in your >>> text editor. Can you not write conversion software that goes from >>> Commonmark to Pillar? Thus, meeting want you want and what we require? >>> If you were to do so, you would definitely have a good understanding >>> of the differences in philosophy and capabilities of each. Just a >>> thought. >>> >>> Any way, thanks for engaging in the conversation. I wasn't targeting >>> you personally, but rather the topic. You are not alone in your >>> thinking. The Pharo community is not alone in its thinking either. >>> >>> Thanks. >>> >>> Jimmie >>> >>> >>> >>> >>> On 08/14/2017 11:34 AM, Tim Mackinnon wrote: >>>> Jimmie et al. nicely reasoned arguments - and Doru's point about >>>> controlling the syntax is an interesting one that I hadn’t thought >>>> about. >>>> >>>> Personally, I find having too many similar syntax’s confusing - >>>> contributing to things is hard enough - having to remember that its >>>> !! Instead of ## and “” instead of ** is just frustrating for me. >>>> >>>> My vote would be what Peter suggested - use >>>> http://spec.commonmark.org/0.28/ and put our Pillar extensions back >>>> on top for things that Stef was mentioning. (I think that’s what I’ve >>>> understood gfm markdown is). >>>> >>>> Sure, maybe we were first with Pillar, but for me, lots of >>>> programming is in other languages, and I use Smalltalk where I can, >>>> and a hybrid of multiple languages and projects is often the reality >>>> - so a lowest common denominator of Markdown is just easier. The fact >>>> that we are quite close to what our colleagues in other languages use >>>> (regardless of what Python has chosen), is quite interesting. >>>> >>>> That said, if the community wants to stick to its gun’s thats fine - >>>> I will probably still investigate how to use Commonmark for myself, >>>> and will still contribute to Pillar docs where I can (and curse >>>> history) - but I think we are long better off trying to join emerging >>>> standards where we can particularly if they aren’t our core language >>>> thing. And it just makes it less frictionless for ourselves and >>>> newcomers. >>>> >>>> Of course, if we were to move, we would need to translate a lot of >>>> quality docs to a new format - but I would be up for contributing to >>>> that if that was a deciding factor. >>>> >>>> Tim >>>> >>>> >>>>> On 14 Aug 2017, at 16:41, Jimmie Houchin <jlhouc...@gmail.com >>>>> <mailto:jlhouc...@gmail.com>> wrote: >>>>> >>>>> TL;DR >>>>> >>>>> Main points: >>>>> Their is no universally accepted markup language. >>>>> Other communities use their own markup and tools and their markup >>>>> and tools choice is not determine by other communities decisions. >>>>> We need a language and tool chain that we can control and maintain >>>>> which accomplishes our goals. >>>>> Our language and tools already exist and have existed for longer >>>>> than most of the other markup languages. Of course they existed in >>>>> various different forms over the years and have evolved into what >>>>> they currently are. >>>>> It might be nice to have a GFM Markdown exporter from Pillar for >>>>> GitHub projects. >>>>> >>>>> >>>>> I just want to comment on the fact that there is no universal markup >>>>> language that every development community has settled upon. Making >>>>> Markdown or some variant the markup language for Pharo only aligns >>>>> us with a certain part of the development community. Even Markdown >>>>> is not unified as is evident by the discussion. >>>>> >>>>> It is true that GitHub uses their variant of Markdown. And as long >>>>> as we use GitHub we will need to use their variant for documents >>>>> that reside on their system. >>>>> >>>>> However as a significant counter example to lets all use gfm >>>>> Markdown, is the Python community and their documentation. >>>>> >>>>> https://docs.python.org/devguide/documenting.html >>>>> """ >>>>> 7. Documenting Python >>>>> The Python language has a substantial body of documentation, much of >>>>> it contributed by various authors. The markup used for the Python >>>>> documentation is reStructuredText, developed by the docutils >>>>> project, amended by custom directives and using a toolset named >>>>> Sphinx to post-process the HTML output. >>>>> >>>>> This document describes the style guide for our documentation as >>>>> well as the custom reStructuredText markup introduced by Sphinx to >>>>> support Python documentation and how it should be used. >>>>> >>>>> The documentation in HTML, PDF or EPUB format is generated from text >>>>> files written using the reStructuredText format and contained in the >>>>> CPython Git repository. >>>>> """ >>>>> >>>>> So the Python community uses their own markup language and their own >>>>> tool chain. So therefore, it is not wrong for a community to go >>>>> their own way, for their own reasons. Even within the conventional >>>>> file based languages such as Python. >>>>> >>>>> The fact that you have tools such as Pandoc, suggest that there is >>>>> not true uniformity or unanimity among developers as to the best >>>>> markup language or tool chain. >>>>> >>>>> I believe that a language that we can control and maintain is better >>>>> than adopting some other foreign markup language that is neither >>>>> better, nor unanimously used by all. That would ultimately >>>>> potentially require extensions to accomplish our goals. Then we >>>>> would be maintaining someone else's language with our extensions >>>>> that may or may not be accepted by the larger community. This does >>>>> not prevent but rather encourages fragmentation of the existing >>>>> Markdown. >>>>> >>>>> Regardless, Pillar markup already exists. The tools in Pharo already >>>>> understand it. Should someone desire to use Pharo which is far more >>>>> different from Python/Ruby/etc. than Pillar syntax is from Markdown. >>>>> Then it should be worth their effort to learn our tools. >>>>> >>>>> Pillar markup is older than Markdown, etc. It's history begins in >>>>> SmallWiki. It isn't as if we jumped up and decided to create >>>>> something new in order to be different. Our markup and tools are >>>>> older. They (and others) are the ones that decided to do their own >>>>> markup and tools. And it is okay that they did so. Nothing wrong >>>>> with doing so. Every community has the right to what they believe is >>>>> best for their community. Even if other communities disagree. >>>>> >>>>> The ability to control and maintain is highly valuable. We can >>>>> understand what our requirements are for today. But we can not know >>>>> what the requirements are in the future. Nor can we know that >>>>> Markdown or whomever will have such requirements when they appear. >>>>> It is easy to see in the beginning with the Squeak Wiki syntax to >>>>> the now Pillar syntax, changes that have been made to accommodate >>>>> new requirements as they became known. We need to maintain that >>>>> ability. Sure we would reserve the right to do so in any language we >>>>> adopt. But the then current standard bearer of said language would >>>>> determine whether what we do is acceptable and incorporate or >>>>> whether we are then in fact adding to their fragmentation. Pillar is >>>>> ours. There is not fragmentation when we evolve. >>>>> >>>>> However, since we have made a decision to use GitHub and GitHub has >>>>> made a decision to use their own GFM Markdown. It might be nice to >>>>> have a GFM Markdown exporter from Pillar for GitHub projects. This >>>>> way we can use our own tools and markup language to accomplish >>>>> whatever we want to accomplish. Including generating a Readme.md for >>>>> our GitHub projects. >>>>> >>>>> Just wanted to toss out this simple opinion and facts about the >>>>> situation. >>>>> >>>>> Jimmie >>>>> >>>>> >>>>> On 08/14/2017 04:10 AM, Tudor Girba wrote: >>>>>> Hi Tim, >>>>>> >>>>>> The main benefit of relying on Pillar is that we control its syntax >>>>>> and can easily extend it for our purposes. Also, there was quite a >>>>>> bit of engineering invested in it, and even though we still need to >>>>>> improve it, there exists a pipeline that allows people to quickly >>>>>> publish books. >>>>>> >>>>>> The figure embedding problem is one example of the need to >>>>>> customize the syntax and behavior, but this extensibility will >>>>>> become even more important for supporting the idea of moving the >>>>>> documentation inside the image. For example, the ability to refer >>>>>> to a class, method or other artifacts will be quite relevant soon >>>>>> especially that the editor will be able to embed advanced elements >>>>>> inside the text. >>>>>> >>>>>> Cheers, >>>>>> Doru >>>>>> >>>>>> >>>>>>> On Aug 14, 2017, at 10:46 AM, Tim Mackinnon <tim@testit.works> >>>>>>> wrote: >>>>>>> >>>>>>> Hi Stef - I think your’s is a fair requirement (in fact I hit >>>>>>> something similar when doing a static website using a JS markdown >>>>>>> framework - and this is why I mentioned Kramdown which adds a few >>>>>>> extras to regular markdown - but it feels like it goes a bit too >>>>>>> far). >>>>>>> >>>>>>> My next item on my learning todo list was to try and replace that >>>>>>> JS generator with something from Smalltalk - so I think we can >>>>>>> possibly come up with something that ticks all the right boxes >>>>>>> (I’d like to try anyway). >>>>>>> >>>>>>> I’ll keep working away on it and compare notes with you. I think >>>>>>> with Pillar, it was more that things like headers, bold and >>>>>>> italics are similar concepts but just use different characters - >>>>>>> so I keep typing the wrong thing and getting frustrated >>>>>>> particularly when we embrace Git and readme.md is in markdown. >>>>>>> >>>>>>> >>>>>>> Tim >>>>>>> >>>>>>>> On 13 Aug 2017, at 20:08, Stephane Ducasse >>>>>>>> <stepharo.s...@gmail.com> wrote: >>>>>>>> >>>>>>>> Hi tim >>>>>>>> >>>>>>>> I personally do not care much about the syntax but I care about >>>>>>>> what I >>>>>>>> can do with it >>>>>>>> (ref, cite, ... ) >>>>>>>> I cannot write books in markdown because reference to figures!!!!!! >>>>>>>> were missing. >>>>>>>> >>>>>>>> And of course a parser because markdown is not really nice to parse >>>>>>>> and I will not write a parser because I have something else to do. >>>>>>>> I >>>>>>>> want to make pillar smaller, simpler, nicer. >>>>>>>> >>>>>>>> Now if someone come up with a parser that parse for REAL a markdown >>>>>>>> that can be extended with decent behavior (figure reference, >>>>>>>> section >>>>>>>> reference, cite) and can be extended because there are many things >>>>>>>> that can be nice to have (for example I want to be able to write >>>>>>>> the >>>>>>>> example below) and emit a PillarModel (AST) we can talk to have >>>>>>>> another syntax for Pillar but not before. >>>>>>>> >>>>>>>> [[[test >>>>>>>> 2+3 >>>>>>>>>>> 5 >>>>>>>> ]]] >>>>>>>> >>>>>>>> and being able to verify that the doc is in sync. >>>>>>>> >>>>>>>> >>>>>>>> Stef >>>>>>>> >>>>>>>> >>>>>>>> >>>>>>>> On Sat, Aug 12, 2017 at 12:37 AM, Tim Mackinnon >>>>>>>> <tim@testit.works> wrote: >>>>>>>>> Of course, I/we recognise and appreciate all the work that's >>>>>>>>> gone into docs in pillar - but I think it should be reasonably >>>>>>>>> straightforward to write a converter as it is pretty closely >>>>>>>>> related from what I have seen. >>>>>>>>> >>>>>>>>> So I don't make the suggestion flippantly, and would want to >>>>>>>>> help write a converter and get us to a common ground where we >>>>>>>>> can differentiate on the aspects where we can excel. >>>>>>>>> >>>>>>>>> Tim >>>>>>>>> >>>>>>>>> Sent from my iPhone >>>>>>>>> >>>>>>>>>> On 11 Aug 2017, at 23:21, Peter Uhnak <i.uh...@gmail.com> wrote: >>>>>>>>>> >>>>>>>>>> A long time issue with Markdown was that there was no >>>>>>>>>> standardization (and when I used Pillar's MD export ~2 years >>>>>>>>>> ago it didn't work well). >>>>>>>>>> >>>>>>>>>> However CommonMark ( http://spec.commonmark.org/0.28/ ) has >>>>>>>>>> become the de-facto standard, so it would make sense to support >>>>>>>>>> it bidirectionally with Pillar. >>>>>>>>>> >>>>>>>>>>> The readme.md that Peter is talking about is gfm markdown >>>>>>>>>> Well, technically it is just a CommonMark, as I am not using >>>>>>>>>> any github extensions. >>>>>>>>>> (Github uses CommonMarks and adds just couple small extensions.) >>>>>>>>>> >>>>>>>>>> Peter >>>>>>>>>> >>>>>>>>> >>>>>>> >>>>>> -- >>>>>> www.tudorgirba.com >>>>>> www.feenk.com >>>>>> >>>>>> “Live like you mean it." >>>>>> >>>>>> >>>>> >>>>> >>>> >>> >> >> >
