P.S. 3 And I realize that there is an pillar issue "Create a small parser independant of PetitParser for a light pillar"
https://github.com/pillar-markup/pillar/issues/174 AFAIK this parser already exists. The hand written parser from in the Pier CMS. Some small adaptations are probably necessary. On 8/15/17, H. Hirzel <hannes.hir...@gmail.com> wrote: > P.S. 2 > > And yes the Pillar syntax which goes back to the Pier syntax [1] has > been around for quite some time > > > 2008 at least according to > > Pier > http://wiki.squeak.org/squeak/3700 > > http://www.piercms.com/doc/syntax > > > > [1] Pharo 6.1 catalog entry for Pillar > > Pillar is a wiki-like syntax, its document model, a parser for it, and > a set of exporters (e.g., HTML, LaTeX, Markdown...). Pillar is > primarily used as the wiki syntax behind the *Pier > CMS>http://piercms.com*. Pillar is also being used to write books: > e.g., *the Enterprise Pharo book>http://books.pharo.org/*. > > The original creator of Pillar (formerly known as ''the syntax behind > the Pier CMS'') is Lukas Renggli. Nevertheless, *Damien > Cassou>damien.cas...@inria.fr* is now the maintainer. The website is > at *http://www.smalltalkhub.com/#!/~Pier/Pillar*. Issues should be > reported to *https://github.com/pillar-markup/pillar/issues* > > On 8/15/17, H. Hirzel <hannes.hir...@gmail.com> wrote: >> 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." >>>>>>>> >>>>>>>> >>>>>>> >>>>>>> >>>>>> >>>>> >>>> >>>> >>> >> >
