We can change the syntax or propose an alternate one as soon as it uses the same internal structure.
Stef On Mon, Aug 14, 2017 at 6:34 PM, Tim Mackinnon <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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." > > > > >
